RootHerald.lib / librootherald.a

#include <rootherald.h>

/* Opaque handle. */
typedef struct RootHeraldClient RootHeraldClient;

/* Status codes — there is NO client-side verdict enum. */
typedef enum {
    ROOTHERALD_OK = 0,
    ROOTHERALD_ERR_INVALID_ARG = 1,
    ROOTHERALD_ERR_TPM_UNAVAILABLE = 2,
    ROOTHERALD_ERR_NETWORK = 3,
    ROOTHERALD_ERR_SERVER = 4,
    ROOTHERALD_ERR_QUOTA_EXCEEDED = 5,
    ROOTHERALD_ERR_NOT_ENROLLED = 6,        /* no enrolled attestation key on the device */
    ROOTHERALD_ERR_ELEVATION_REQUIRED = 7,  /* Windows enroll: process not elevated. See "Windows elevation patterns". */
    ROOTHERALD_ERR_INTERNAL = 99
} RootHeraldStatus;

/* Caller-allocated local-info structs (never touch the network). */
typedef struct {
    int  is_enrolled;
    int  has_tpm;
    char device_id[129];
    char platform_name[16];   /* "windows" | "linux" | "macos" */
} RootHeraldDeviceInfo;

typedef struct {
    int  has_tpm;
    int  is_enrolled;
    int  ek_cert_present;
    int  secure_boot;          /* 1 on, 0 off, -1 undetermined */
    int  oem_keyed;            /* 1 known-OEM, 0 custom, -1 undetermined */
    char oem_name[64];
    int  boot_log_measurements;
    int  boot_log_revoked;
    char device_id[129];
    char detail_json[2048];
} RootHeraldPosture;

/* Lifecycle — keyless: no api_key, no endpoint. */
RootHeraldClient* RootHeraldClient_Create(void);
void              RootHeraldClient_Destroy(RootHeraldClient* client);
RootHeraldStatus  RootHeraldClient_SetApplicationId(RootHeraldClient* client, const char* app_id);

/* Enrollment — keyless, two-leg blob handshake (elevated on Windows).
   Your backend relays each blob to /devices/enroll then /devices/activate. */
RootHeraldStatus RootHeraldClient_EnrollBegin(RootHeraldClient* client,
                                              char** out_request_json);
RootHeraldStatus RootHeraldClient_EnrollComplete(RootHeraldClient* client,
                                                 const char* challenge_json,
                                                 char** out_activation_json);

/* Per-attestation evidence — keyless quote over a backend-issued nonce.
   The returned blob is exactly what /attestations/verify expects. */
RootHeraldStatus RootHeraldClient_CollectEvidence(const char* nonce_b64,
                                                  char** out_evidence_json);

/* Local, network-free snapshots. */
RootHeraldStatus RootHeraldClient_GetDeviceInfo(RootHeraldClient* client,
                                                RootHeraldDeviceInfo* out_result);
RootHeraldStatus RootHeraldClient_CollectPosture(RootHeraldClient* client,
                                                 RootHeraldPosture* out_result);

/* Free any blob returned by EnrollBegin / EnrollComplete / CollectEvidence. */
void RootHeraldClient_FreeEvidence(char* evidence_json);

const char* RootHerald_AbiVersionString(void);
const char* RootHerald_LibraryVersionString(void);

#include <rootherald.h>
#include <cstdio>

// Provided by YOUR app: fetches a fresh challenge nonce from your backend
// (which called POST /api/v1/attestations/challenge with its rh_sk_ secret)
// and relays the collected evidence back for /attestations/verify.
extern std::string fetch_nonce_from_your_backend();
extern bool        relay_evidence_to_your_backend(const std::string& evidence_json);

int main()
{
    // Keyless: no api_key, no endpoint — nothing to connect to.
    auto* client = RootHeraldClient_Create();
    if (!client)
    {
        std::fprintf(stderr, "Root Herald init failed\n");
        return 1;
    }

    RootHeraldClient_SetApplicationId(client, "com.acme.launcher");

    // 1. Get the server-issued nonce from your backend.
    std::string nonce = fetch_nonce_from_your_backend();

    // 2. Collect a quote-over-nonce evidence blob locally. Keyless, no network.
    char* evidence_json = nullptr;
    auto status = RootHeraldClient_CollectEvidence(nonce.c_str(), &evidence_json);
    if (status != ROOTHERALD_OK)
    {
        std::fprintf(stderr, "collect failed (%d): %s\n",
                     status, RootHerald_ErrorString(status));
        RootHeraldClient_Destroy(client);
        return 1;
    }

    // 3. Hand the blob to your backend, which relays it to /attestations/verify
    //    and enforces the verdict. The verdict never travels through the client.
    bool ok = relay_evidence_to_your_backend(evidence_json);
    RootHeraldClient_FreeEvidence(evidence_json);

    if (!ok)
    {
        std::fprintf(stderr, "device not trusted (backend rejected)\n");
        RootHeraldClient_Destroy(client);
        return 1;
    }

    std::printf("Device attested; backend allowed launch.\n");
    RootHeraldClient_Destroy(client);
    return 0;
}

find_package(RootHerald REQUIRED)
target_link_libraries(your_game PRIVATE RootHerald::RootHerald)

# Or, vendored as a sub-tree (typical for game studios):
add_subdirectory(third_party/rootherald)
target_link_libraries(your_game PRIVATE RootHerald)
target_include_directories(your_game PRIVATE third_party/rootherald/include)

link.exe your_game.obj RootHerald.lib ncrypt.lib tbs.lib winhttp.lib bcrypt.lib crypt32.lib

gcc your_game.o -lrootherald -ltss2-esys -ltss2-tctildr -ltss2-mu -lcurl -lpthread

clang your_game.o -lrootherald -framework Security -framework Foundation