C SDK (v2)
Install
Section titled “Install”# Use the ratify-c 2.0.0-beta.2 release archive, or build it from the release tag# (Rust toolchain required). Include ratify.h and call the ratify_v2_* functions.git clone --branch v2.0.0-beta.2 https://github.com/identities-ai/ratify-protocolcd ratify-protocol/sdks/ccargo build --releasePackage: ratify-c 2.x, header ratify.h, functions prefixed ratify_v2_. API documentation: the header sdks/c/include/ratify.h.
- An ABI over the Rust implementation. Agreement between C and Rust is not independent evidence.
- Input buffers are borrowed for the call; library-allocated outputs are freed only with the matching
ratify_v2_*_freefunction. - Callbacks run on the calling thread and are never retained. One handle is used by one thread at a time.
- Every export contains panics and returns the internal-failure code; a handle in use during a panic is poisoned.
- Check
ratify_v2_abi_versionat startup.
Part B stores
Section titled “Part B stores”Production verifiers implement the claim store, rate reservations, receipt publisher,
independent checkpoint, and journal store durably, as C callbacks. The library’s in-memory
reference stores exist only in builds with the test-only test-reference feature, which a
shipped build never enables. See Deployment profiles.
Quickstart
Section titled “Quickstart”Delegate, present, verify, and release: C quickstart (development only).
Examples
Section titled “Examples”Signed status
Section titled “Signed status”An issuer’s status publisher signs revocation lists and pushes under a separate status key; the verifier applies them to its journal. See Status from signed evidence.
/* * Ratify Protocol v2 signed status: a status publisher under a separate * status key, journal ingestion, and a revocation that turns a later * verification into deny. * * DEVELOPMENT ONLY. This program uses the in-memory reference stores * (ratify_v2_ref_*), compiled only into a test-reference build. A production * verifier supplies durable Part B stores, an anchored journal store and an * independent checkpoint through the callback structs (SPEC-v2 §7). * * Build and run: examples/v2/c/test.sh */#include "example_util.h"
#define START 1800000000LL#define NAMESPACE "signed-status"#define EPOCH 1#define LOG_ID "00000000000000000000000000000002"#define CERT_ID "status-demo-cert-1"#define TZDB_VERSION "2025c"
typedef struct { const char *root_id; const RatifyV2PublicKey *root_key;} trust_config;
static int32_t resolve_trust(void *user, const RatifyV2CertView *chain, uintptr_t chain_len, int32_t *outcome, RatifyV2PublicKey *root_key) { const trust_config *t = user; if (strcmp(chain[chain_len - 1].issuer_id, t->root_id) == 0) { *outcome = RatifyV2TrustTrusted; *root_key = *t->root_key; } else { *outcome = RatifyV2TrustUntrusted; } return 0;}
/* The status objects the provider currently serves. */typedef struct { RatifyV2StatusObject objects[2]; uintptr_t count;} status_feed;
/* The provider returns signed objects only; the verifier checks each * signature against the configured status key and applies it to the journal * before it derives a status. */static int32_t fetch_status(void *user, const RatifyV2StatusRequest *request, RatifyV2StatusBatch *out) { (void)request; const status_feed *feed = user; out->objects = feed->objects; out->count = feed->count; return 0;}
typedef struct { RatifyV2RefStore *store; RatifyV2KeyPair *agent; const RatifyV2IssuanceStoreCallbacks *issuance; const RatifyV2VerifyCallbacks *callbacks; const RatifyV2ReleaseStoreCallbacks *release; const RatifyV2CheckpointCallbacks *checkpoint; const RatifyV2ClockCallbacks *clock; const RatifyV2PublicKey *verifier_pub; const char *root_id, *agent_id, *verifier_id, *agent_json, *status_json, *cert;} deployment;
/* Runs one complete live verification at the store's current time and * prints the released decision. */static void verify_and_release(const deployment *d, const char *label) { char *issue_req = format( "{\"verifier_namespace\":\"%s\",\"replay_epoch\":%d,\"verifier_id\":\"%s\",\"lifetime_seconds\":120," "\"expected_agent_id\":\"%s\",\"expected_agent_public_key\":%s}", NAMESPACE, EPOCH, d->verifier_id, d->agent_id, d->agent_json); RatifyV2ClockCallbacks clock = *d->clock; RatifyV2Buffer challenge_buf; CHECK(ratify_v2_issue_challenge((const uint8_t *)issue_req, strlen(issue_req), &clock, d->issuance, NULL, &challenge_buf)); char *challenge = take_string(challenge_buf); char challenge_b64[64]; json_str(challenge, "value_b64", challenge_b64, sizeof challenge_b64); char *bundle_in = format( "{\"agent_id\":\"%s\",\"agent_pub_key\":%s,\"challenge\":\"%s\",\"challenge_at\":%lld,\"delegations\":[%s]," "\"session_context\":null,\"stream_id\":null,\"stream_seq\":null,\"verifier_id\":\"%s\",\"version\":2}", d->agent_id, d->agent_json, challenge_b64, (long long)json_int(challenge, "issued_at"), d->cert, d->verifier_id); RatifyV2Buffer bundle; CHECK(ratify_v2_sign_proof_bundle((const uint8_t *)bundle_in, strlen(bundle_in), d->agent, NULL, &bundle));
uint8_t challenge_bytes[32]; b64_decode(challenge_b64, challenge_bytes, sizeof challenge_bytes); RatifyV2Buffer expected_buf; CHECK(ratify_v2_load_expected_challenge(d->issuance, NAMESPACE, EPOCH, challenge_bytes, 32, &expected_buf)); char *expected = take_string(expected_buf); int64_t now; CHECK(ratify_v2_ref_store_time(d->store, &now)); char *request = format( "{\"required_scope\":\"data:read\",\"verifier_namespace\":\"%s\",\"replay_epoch\":%d,\"verifier_id\":\"%s\",\"now\":%lld," "\"max_challenge_age_seconds\":300,\"future_skew_seconds\":5,\"tzdb_version\":\"%s\"," "\"status_keys\":{\"%s\":{\"epoch\":1,\"public_key\":%s}}," "\"status_policy\":{\"max_list_lifetime_seconds\":3600,\"max_status_age_seconds\":3600,\"clock_skew_seconds\":5}," "\"expected_challenge\":%s," "\"context_policy\":{\"profile\":\"example.signed-status/v1\",\"require_bound\":false,\"required_fields\":[]," "\"expected_session_context_b64\":null}}", NAMESPACE, EPOCH, d->verifier_id, (long long)now, TZDB_VERSION, d->root_id, d->status_json, expected); RatifyV2VerifyOutcome outcome; RatifyV2Committed *committed = NULL; CHECK(ratify_v2_verify_proof_bundle(bundle.ptr, bundle.len, (const uint8_t *)request, strlen(request), NULL, d->callbacks, &outcome, NULL, &committed)); if (outcome.stage != RatifyV2StageCommitted) fail("verify did not commit");
char *claim_id; RatifyV2Buffer body, receipt_buf; const char *refusal = NULL; CHECK(ratify_v2_committed_claim_id(committed, &claim_id)); CHECK(ratify_v2_committed_receipt_body(committed, &body)); CHECK(ratify_v2_ref_store_publish(d->store, claim_id, body.ptr, body.len, &receipt_buf, &refusal)); int32_t release_status; char *release_reason = NULL; RatifyV2Released *decision = NULL; RatifyV2Slice receipt_wire = {receipt_buf.ptr, receipt_buf.len}; CHECK(ratify_v2_release_decision(committed, receipt_wire, d->verifier_pub, LOG_ID, d->release, d->checkpoint, &release_status, &release_reason, &decision)); if (release_status != RatifyV2ReleaseReleased) fail("release did not release"); char *verdict, *reason, assessment[64]; CHECK(ratify_v2_released_string(decision, RatifyV2ReleasedDecision, &verdict)); CHECK(ratify_v2_released_string(decision, RatifyV2ReleasedReason, &reason)); RatifyV2Buffer released_receipt; CHECK(ratify_v2_released_receipt(decision, &released_receipt)); char *receipt = take_string(released_receipt); json_str(receipt, "status_assessment", assessment, sizeof assessment); printf("%s: decision=%s reason=%s status_assessment=%s allowed=%s\n", label, verdict, reason, assessment, ratify_v2_released_allowed(decision, &clock) ? "true" : "false");
free(receipt); ratify_v2_string_free(reason); ratify_v2_string_free(verdict); ratify_v2_string_free(release_reason); ratify_v2_released_free(decision); ratify_v2_buffer_free(receipt_buf); ratify_v2_buffer_free(body); ratify_v2_string_free(claim_id); ratify_v2_committed_free(committed); free(request); free(expected); ratify_v2_buffer_free(bundle); free(bundle_in); free(challenge); free(issue_req);}
/* Prints the journal's status for the certificate at `now`. */static void print_journal_status(const RatifyV2JournalStoreCallbacks *journal, const char *root_id, const RatifyV2PublicKey *status_pub, const RatifyV2StatusPolicy *policy, const char *what, int64_t sequence, int64_t now) { RatifyV2Buffer result_buf; CHECK(ratify_v2_journal_status(journal, root_id, CERT_ID, 1, status_pub, policy, now, &result_buf)); char *result = take_string(result_buf), status[64]; json_str(result, "status", status, sizeof status); printf("journal: ingested %s sequence %lld; %s is %s\n", what, (long long)sequence, CERT_ID, status); free(result);}
int main(void) { printf("Ratify Protocol v2 signed status\n"); printf("development only: in-memory reference stores\n");
RatifyV2KeyPair *root, *agent, *status, *verifier; CHECK(ratify_v2_keypair_generate(&root, NULL, NULL)); CHECK(ratify_v2_keypair_generate(&agent, NULL, NULL)); CHECK(ratify_v2_keypair_generate(&status, NULL, NULL)); CHECK(ratify_v2_keypair_generate(&verifier, NULL, NULL)); static RatifyV2PublicKey root_pub, agent_pub, status_pub, verifier_pub; CHECK(ratify_v2_keypair_public_key(root, &root_pub)); CHECK(ratify_v2_keypair_public_key(agent, &agent_pub)); CHECK(ratify_v2_keypair_public_key(status, &status_pub)); CHECK(ratify_v2_keypair_public_key(verifier, &verifier_pub)); char root_id[RATIFY_V2_KEY_ID_BUF_LEN], agent_id[RATIFY_V2_KEY_ID_BUF_LEN], verifier_id[RATIFY_V2_KEY_ID_BUF_LEN]; CHECK(ratify_v2_keypair_key_id(root, root_id, sizeof root_id)); CHECK(ratify_v2_keypair_key_id(agent, agent_id, sizeof agent_id)); CHECK(ratify_v2_keypair_key_id(verifier, verifier_id, sizeof verifier_id)); char *root_json = key_json(&root_pub), *agent_json = key_json(&agent_pub), *status_json = key_json(&status_pub);
char *cert_in = format( "{\"cert_id\":\"%s\",\"constraints\":[],\"expires_at\":%lld,\"issued_at\":%lld,\"issuer_id\":\"%s\"," "\"issuer_pub_key\":%s,\"scope\":[\"data:read\"],\"subject_id\":\"%s\",\"subject_pub_key\":%s,\"version\":2}", CERT_ID, START + 86400, START, root_id, root_json, agent_id, agent_json); RatifyV2Buffer cert_buf; CHECK(ratify_v2_sign_delegation_certificate((const uint8_t *)cert_in, strlen(cert_in), root, NULL, &cert_buf)); char *cert = take_string(cert_buf); printf("delegation: %s scope=data:read\n", CERT_ID);
/* The journal is the verifier's anchored record of key roles, status-key * epochs and accepted status. Roles are recorded once, when the * deployment authenticates its trust configuration. */ RatifyV2RefJournal *journal_store; RatifyV2JournalStoreCallbacks journal; CHECK(ratify_v2_ref_journal_new(&journal_store)); CHECK(ratify_v2_ref_journal_callbacks(journal_store, &journal, NULL, NULL)); CHECK(ratify_v2_journal_record_key_role(&journal, "issuer", &root_pub)); CHECK(ratify_v2_journal_record_key_role(&journal, "delegation", &agent_pub)); CHECK(ratify_v2_journal_record_key_role(&journal, "verifier", &verifier_pub)); CHECK(ratify_v2_journal_configure_status_key(&journal, root_id, 1, &status_pub)); printf("journal: key roles recorded; status key configured for the root at epoch 1\n");
/* Role separation: the root key can never sign status for itself. */ RatifyV2Buffer list_buf, push_buf, state_buf; int32_t refused = ratify_v2_status_publish(RatifyV2PublishGenesis, &journal, &root_pub, root, NULL, 3600, NULL, 0, NULL, 0, START, &list_buf, &push_buf, &state_buf); printf("publisher with the root key as status key: refused (%s)\n", ratify_v2_error_class_str(refused));
RatifyV2StatusPolicy policy = {3600, 3600, 5};
/* Genesis: sequence 1, nothing revoked. The caller persists the returned * state before publishing the signed list. */ CHECK(ratify_v2_status_publish(RatifyV2PublishGenesis, &journal, &root_pub, status, NULL, 3600, NULL, 0, NULL, 0, START, &list_buf, &push_buf, &state_buf)); ratify_v2_buffer_free(push_buf); RatifyV2Buffer genesis_list = list_buf; char *genesis_state = take_string(state_buf); int64_t genesis_sequence = json_int(genesis_state, "sequence"); printf("publisher: genesis list sequence %lld\n", (long long)genesis_sequence); CHECK(ratify_v2_journal_apply(&journal, RatifyV2KindRevocationList, genesis_list.ptr, genesis_list.len, root_id, 1, &status_pub, &policy, START)); print_journal_status(&journal, root_id, &status_pub, &policy, "list", genesis_sequence, START);
RatifyV2RefStore *store; CHECK(ratify_v2_ref_store_new(START, 30, LOG_ID, verifier, &store)); RatifyV2ClaimStoreCallbacks claim_cb; RatifyV2ReleaseStoreCallbacks release_cb; RatifyV2CheckpointCallbacks checkpoint_cb; RatifyV2ClockCallbacks clock_cb; CHECK(ratify_v2_ref_store_callbacks(store, 0, &claim_cb, NULL, &release_cb, &checkpoint_cb, &clock_cb)); RatifyV2RefIssuance *issuance_store; RatifyV2IssuanceStoreCallbacks issuance; CHECK(ratify_v2_ref_issuance_new(&issuance_store)); CHECK(ratify_v2_ref_issuance_control(issuance_store, -1, &issuance, NULL));
status_feed feed = {{{RatifyV2KindRevocationList, {genesis_list.ptr, genesis_list.len}}}, 1}; trust_config trust_user = {root_id, &root_pub}; RatifyV2TrustCallbacks trust = {&trust_user, resolve_trust}; RatifyV2StatusEvidenceCallbacks evidence = {&feed, fetch_status}; RatifyV2VerifyCallbacks callbacks = {&claim_cb, &trust, &evidence, &journal, NULL, NULL, NULL}; deployment d = {store, agent, &issuance, &callbacks, &release_cb, &checkpoint_cb, &clock_cb, &verifier_pub, root_id, agent_id, verifier_id, agent_json, status_json, cert};
CHECK(ratify_v2_ref_store_control(store, 1, START + 5)); verify_and_release(&d, "verify before revocation");
/* Revoke: a push with the newly revoked ID and the cumulative list, both * at sequence 2. */ const char *revoke_ids = "[\"" CERT_ID "\"]"; CHECK(ratify_v2_status_publish(RatifyV2PublishRevoke, &journal, &root_pub, status, NULL, 3600, (const uint8_t *)genesis_state, strlen(genesis_state), (const uint8_t *)revoke_ids, strlen(revoke_ids), START + 10, &list_buf, &push_buf, &state_buf)); ratify_v2_buffer_free(state_buf); char *push = format("%.*s", (int)push_buf.len, (const char *)push_buf.ptr); char *list = format("%.*s", (int)list_buf.len, (const char *)list_buf.ptr); int64_t push_sequence = json_int(push, "sequence"); printf("publisher: revoked %s (push sequence %lld, list sequence %lld)\n", CERT_ID, (long long)push_sequence, (long long)json_int(list, "sequence")); CHECK(ratify_v2_journal_apply(&journal, RatifyV2KindRevocationPush, push_buf.ptr, push_buf.len, root_id, 1, &status_pub, &policy, START + 10)); print_journal_status(&journal, root_id, &status_pub, &policy, "push", push_sequence, START + 10);
feed.objects[0] = (RatifyV2StatusObject){RatifyV2KindRevocationPush, {push_buf.ptr, push_buf.len}}; feed.objects[1] = (RatifyV2StatusObject){RatifyV2KindRevocationList, {list_buf.ptr, list_buf.len}}; feed.count = 2; CHECK(ratify_v2_ref_store_control(store, 1, START + 15)); verify_and_release(&d, "verify after revocation");
free(push); free(list); ratify_v2_buffer_free(push_buf); ratify_v2_buffer_free(list_buf); ratify_v2_buffer_free(genesis_list); free(genesis_state); ratify_v2_ref_issuance_free(issuance_store); ratify_v2_ref_store_free(store); ratify_v2_ref_journal_free(journal_store); free(cert); free(cert_in); free(root_json); free(agent_json); free(status_json); ratify_v2_keypair_free(root); ratify_v2_keypair_free(agent); ratify_v2_keypair_free(status); ratify_v2_keypair_free(verifier); return 0;}Source: examples/v2/c/signed_status at commit 5ca7585c2c1d, SHA-256 checked at build time.
Custom scope and evaluator profile
Section titled “Custom scope and evaluator profile”An exact custom: required scope and a registered evaluator profile.
See Delegation and constraints.
/* * Ratify Protocol v2 custom scope and the standard max_count evaluator * profile (com.ratifyprotocol.max_count/v1). * * DEVELOPMENT ONLY. This program uses the in-memory reference stores * (ratify_v2_ref_*), compiled only into a test-reference build. A production * verifier supplies durable Part B stores and an independent checkpoint * through the callback structs (SPEC-v2 §7). * * Build and run: examples/v2/c/test.sh */#include "example_util.h"
#define START 1800000000LL#define NAMESPACE "custom-scope"#define EPOCH 1#define LOG_ID "00000000000000000000000000000003"#define CUSTOM_SCOPE "custom:acme:deploy"#define MAX_COUNT_TYPE "com.ratifyprotocol.max_count"#define MAX_COUNT_PROFILE "com.ratifyprotocol.max_count/v1"#define TZDB_VERSION "2025c"
typedef struct { const char *root_id; const RatifyV2PublicKey *root_key;} trust_config;
static int32_t resolve_trust(void *user, const RatifyV2CertView *chain, uintptr_t chain_len, int32_t *outcome, RatifyV2PublicKey *root_key) { const trust_config *t = user; if (strcmp(chain[chain_len - 1].issuer_id, t->root_id) == 0) { *outcome = RatifyV2TrustTrusted; *root_key = *t->root_key; } else { *outcome = RatifyV2TrustUntrusted; } return 0;}
static int32_t fetch_status(void *user, const RatifyV2StatusRequest *request, RatifyV2StatusBatch *out) { (void)request; out->objects = user; out->count = 1; return 0;}
typedef struct { RatifyV2RefStore *store; RatifyV2KeyPair *agent; const RatifyV2IssuanceStoreCallbacks *issuance; const RatifyV2VerifyCallbacks *callbacks; const RatifyV2ReleaseStoreCallbacks *release; const RatifyV2CheckpointCallbacks *checkpoint; const RatifyV2ClockCallbacks *clock; const RatifyV2PublicKey *verifier_pub; const char *root_id, *agent_id, *verifier_id, *agent_json, *status_json, *cert;} deployment;
/* Verifies one request for `nodes` nodes and releases the result. */static void attempt(const deployment *d, const char *label, int nodes, const RatifyV2EvaluatorConfig *evaluators) { int64_t now; CHECK(ratify_v2_ref_store_time(d->store, &now)); CHECK(ratify_v2_ref_store_control(d->store, 1, now + 1)); now += 1; char *issue_req = format( "{\"verifier_namespace\":\"%s\",\"replay_epoch\":%d,\"verifier_id\":\"%s\",\"lifetime_seconds\":120," "\"expected_agent_id\":\"%s\",\"expected_agent_public_key\":%s}", NAMESPACE, EPOCH, d->verifier_id, d->agent_id, d->agent_json); RatifyV2ClockCallbacks clock = *d->clock; RatifyV2Buffer challenge_buf; CHECK(ratify_v2_issue_challenge((const uint8_t *)issue_req, strlen(issue_req), &clock, d->issuance, NULL, &challenge_buf)); char *challenge = take_string(challenge_buf); char challenge_b64[64]; json_str(challenge, "value_b64", challenge_b64, sizeof challenge_b64); char *bundle_in = format( "{\"agent_id\":\"%s\",\"agent_pub_key\":%s,\"challenge\":\"%s\",\"challenge_at\":%lld,\"delegations\":[%s]," "\"session_context\":null,\"stream_id\":null,\"stream_seq\":null,\"verifier_id\":\"%s\",\"version\":2}", d->agent_id, d->agent_json, challenge_b64, (long long)json_int(challenge, "issued_at"), d->cert, d->verifier_id); RatifyV2Buffer bundle; CHECK(ratify_v2_sign_proof_bundle((const uint8_t *)bundle_in, strlen(bundle_in), d->agent, NULL, &bundle));
uint8_t challenge_bytes[32]; b64_decode(challenge_b64, challenge_bytes, sizeof challenge_bytes); RatifyV2Buffer expected_buf; CHECK(ratify_v2_load_expected_challenge(d->issuance, NAMESPACE, EPOCH, challenge_bytes, 32, &expected_buf)); char *expected = take_string(expected_buf); /* The requested quantity comes from the authenticated request, never * from the proof. */ char *request = format( "{\"required_scope\":\"%s\",\"verifier_namespace\":\"%s\",\"replay_epoch\":%d,\"verifier_id\":\"%s\",\"now\":%lld," "\"max_challenge_age_seconds\":300,\"future_skew_seconds\":5,\"tzdb_version\":\"%s\"," "\"status_keys\":{\"%s\":{\"epoch\":1,\"public_key\":%s}}," "\"status_policy\":{\"max_list_lifetime_seconds\":3600,\"max_status_age_seconds\":3600,\"clock_skew_seconds\":5}," "\"expected_challenge\":%s," "\"context_policy\":{\"profile\":\"example.custom-scope/v1\",\"require_bound\":false,\"required_fields\":[]," "\"expected_session_context_b64\":null}," "\"context\":{\"extension_counts\":{\"nodes\":%d}}}", CUSTOM_SCOPE, NAMESPACE, EPOCH, d->verifier_id, (long long)now, TZDB_VERSION, d->root_id, d->status_json, expected, nodes); RatifyV2VerifyOutcome outcome; RatifyV2Committed *committed = NULL; CHECK(ratify_v2_verify_proof_bundle(bundle.ptr, bundle.len, (const uint8_t *)request, strlen(request), evaluators, d->callbacks, &outcome, NULL, &committed)); if (outcome.stage != RatifyV2StageCommitted) fail("verify did not commit");
char *claim_id; RatifyV2Buffer body, receipt_buf; const char *refusal = NULL; CHECK(ratify_v2_committed_claim_id(committed, &claim_id)); CHECK(ratify_v2_committed_receipt_body(committed, &body)); CHECK(ratify_v2_ref_store_publish(d->store, claim_id, body.ptr, body.len, &receipt_buf, &refusal)); int32_t release_status; char *release_reason = NULL; RatifyV2Released *decision = NULL; RatifyV2Slice receipt_wire = {receipt_buf.ptr, receipt_buf.len}; CHECK(ratify_v2_release_decision(committed, receipt_wire, d->verifier_pub, LOG_ID, d->release, d->checkpoint, &release_status, &release_reason, &decision)); if (release_status != RatifyV2ReleaseReleased) fail("release did not release"); char *verdict, *reason; CHECK(ratify_v2_released_string(decision, RatifyV2ReleasedDecision, &verdict)); CHECK(ratify_v2_released_string(decision, RatifyV2ReleasedReason, &reason)); printf("%s: decision=%s reason=%s allowed=%s\n", label, verdict, reason, ratify_v2_released_allowed(decision, &clock) ? "true" : "false");
/* The signed receipt names every evaluator profile the claim sealed. */ RatifyV2Buffer released_receipt; CHECK(ratify_v2_released_receipt(decision, &released_receipt)); char *receipt = take_string(released_receipt); const char *refs = strstr(receipt, "\"constraint_evaluators\":["); if (refs) { const char *end = strchr(refs, ']'); for (const char *p = strstr(refs, "{"); p && p < end; p = strstr(p + 1, "{")) { char digest[128], type[160]; json_str(p, "profile_digest", digest, sizeof digest); json_str(p, "type", type, sizeof type); printf(" receipt constraint_evaluators: %s %s\n", type, digest); } }
free(receipt); ratify_v2_string_free(reason); ratify_v2_string_free(verdict); ratify_v2_string_free(release_reason); ratify_v2_released_free(decision); ratify_v2_buffer_free(receipt_buf); ratify_v2_buffer_free(body); ratify_v2_string_free(claim_id); ratify_v2_committed_free(committed); free(request); free(expected); ratify_v2_buffer_free(bundle); free(bundle_in); free(challenge); free(issue_req);}
int main(void) { printf("Ratify Protocol v2 custom scope and max_count profile\n"); printf("development only: in-memory reference stores\n");
RatifyV2KeyPair *root, *agent, *status, *verifier; CHECK(ratify_v2_keypair_generate(&root, NULL, NULL)); CHECK(ratify_v2_keypair_generate(&agent, NULL, NULL)); CHECK(ratify_v2_keypair_generate(&status, NULL, NULL)); CHECK(ratify_v2_keypair_generate(&verifier, NULL, NULL)); static RatifyV2PublicKey root_pub, agent_pub, status_pub, verifier_pub; CHECK(ratify_v2_keypair_public_key(root, &root_pub)); CHECK(ratify_v2_keypair_public_key(agent, &agent_pub)); CHECK(ratify_v2_keypair_public_key(status, &status_pub)); CHECK(ratify_v2_keypair_public_key(verifier, &verifier_pub)); char root_id[RATIFY_V2_KEY_ID_BUF_LEN], agent_id[RATIFY_V2_KEY_ID_BUF_LEN], verifier_id[RATIFY_V2_KEY_ID_BUF_LEN]; CHECK(ratify_v2_keypair_key_id(root, root_id, sizeof root_id)); CHECK(ratify_v2_keypair_key_id(agent, agent_id, sizeof agent_id)); CHECK(ratify_v2_keypair_key_id(verifier, verifier_id, sizeof verifier_id)); char *root_json = key_json(&root_pub), *agent_json = key_json(&agent_pub), *status_json = key_json(&status_pub);
/* A custom scope is one exact name. Wildcards are invalid. */ char *wildcard = format( "{\"cert_id\":\"custom-scope-cert-1\",\"constraints\":[],\"expires_at\":%lld,\"issued_at\":%lld," "\"issuer_id\":\"%s\",\"issuer_pub_key\":%s,\"scope\":[\"custom:*\"],\"subject_id\":\"%s\"," "\"subject_pub_key\":%s,\"version\":2}", START + 86400, START, root_id, root_json, agent_id, agent_json); RatifyV2Buffer refused_buf = {0}; int32_t refused = ratify_v2_sign_delegation_certificate((const uint8_t *)wildcard, strlen(wildcard), root, NULL, &refused_buf); printf("issue scope custom:*: refused (%s)\n", ratify_v2_error_class_str(refused));
/* The certificate carries an extension constraint. Only a verifier that * registered the max_count/v1 profile for this type can evaluate it. */ char *cert_in = format( "{\"cert_id\":\"custom-scope-cert-1\",\"constraints\":[{\"params\":{\"counter\":\"nodes\",\"max\":5}," "\"type\":\"%s\"}],\"expires_at\":%lld,\"issued_at\":%lld,\"issuer_id\":\"%s\",\"issuer_pub_key\":%s," "\"scope\":[\"%s\"],\"subject_id\":\"%s\",\"subject_pub_key\":%s,\"version\":2}", MAX_COUNT_TYPE, START + 86400, START, root_id, root_json, CUSTOM_SCOPE, agent_id, agent_json); RatifyV2Buffer cert_buf; CHECK(ratify_v2_sign_delegation_certificate((const uint8_t *)cert_in, strlen(cert_in), root, NULL, &cert_buf)); char *cert = take_string(cert_buf); printf("delegation: scope=%s constraint=%s(counter=nodes, max=5)\n", CUSTOM_SCOPE, MAX_COUNT_TYPE);
char *digest; CHECK(ratify_v2_constraint_profile_digest(MAX_COUNT_PROFILE, MAX_COUNT_TYPE, &digest)); printf("profile: %s digest=%s\n", MAX_COUNT_PROFILE, digest); RatifyV2EvaluatorRegistration max_count = {MAX_COUNT_TYPE, MAX_COUNT_PROFILE, RatifyV2EvaluatorStandardMaxCount, NULL, NULL}; RatifyV2EvaluatorConfig registry = {1000, &max_count, 1};
RatifyV2RefJournal *journal_store; RatifyV2JournalStoreCallbacks journal; CHECK(ratify_v2_ref_journal_new(&journal_store)); CHECK(ratify_v2_ref_journal_callbacks(journal_store, &journal, NULL, NULL)); CHECK(ratify_v2_journal_record_key_role(&journal, "issuer", &root_pub)); CHECK(ratify_v2_journal_configure_status_key(&journal, root_id, 1, &status_pub)); RatifyV2Buffer list_buf, push_buf, state_buf; CHECK(ratify_v2_status_publish(RatifyV2PublishGenesis, &journal, &root_pub, status, NULL, 3600, NULL, 0, NULL, 0, START, &list_buf, &push_buf, &state_buf)); ratify_v2_buffer_free(push_buf); ratify_v2_buffer_free(state_buf); RatifyV2StatusObject status_object = {RatifyV2KindRevocationList, {list_buf.ptr, list_buf.len}};
RatifyV2RefStore *store; CHECK(ratify_v2_ref_store_new(START, 30, LOG_ID, verifier, &store)); RatifyV2ClaimStoreCallbacks claim_cb; RatifyV2ReleaseStoreCallbacks release_cb; RatifyV2CheckpointCallbacks checkpoint_cb; RatifyV2ClockCallbacks clock_cb; CHECK(ratify_v2_ref_store_callbacks(store, 0, &claim_cb, NULL, &release_cb, &checkpoint_cb, &clock_cb)); RatifyV2RefIssuance *issuance_store; RatifyV2IssuanceStoreCallbacks issuance; CHECK(ratify_v2_ref_issuance_new(&issuance_store)); CHECK(ratify_v2_ref_issuance_control(issuance_store, -1, &issuance, NULL));
trust_config trust_user = {root_id, &root_pub}; RatifyV2TrustCallbacks trust = {&trust_user, resolve_trust}; RatifyV2StatusEvidenceCallbacks evidence = {&status_object, fetch_status}; RatifyV2VerifyCallbacks callbacks = {&claim_cb, &trust, &evidence, &journal, NULL, NULL, NULL}; deployment d = {store, agent, &issuance, &callbacks, &release_cb, &checkpoint_cb, &clock_cb, &verifier_pub, root_id, agent_id, verifier_id, agent_json, status_json, cert};
attempt(&d, "request nodes=3", 3, ®istry); attempt(&d, "request nodes=8", 8, ®istry); attempt(&d, "request nodes=3 without the profile registered", 3, NULL);
ratify_v2_ref_issuance_free(issuance_store); ratify_v2_ref_store_free(store); ratify_v2_buffer_free(list_buf); ratify_v2_ref_journal_free(journal_store); ratify_v2_string_free(digest); free(cert); free(cert_in); ratify_v2_buffer_free(refused_buf); free(wildcard); free(root_json); free(agent_json); free(status_json); ratify_v2_keypair_free(root); ratify_v2_keypair_free(agent); ratify_v2_keypair_free(status); ratify_v2_keypair_free(verifier); return 0;}Source: examples/v2/c/custom_scope at commit 5ca7585c2c1d, SHA-256 checked at build time.
External signer
Section titled “External signer”Signing through a key held outside the SDK, with verify-before-use. See Typed signing and key IDs.
/* * Ratify Protocol v2 external signer: a signing provider holds the private * key; the library prepares each typed statement and verifies every * returned signature before using it. * * The provider here is an in-process stand-in for a remote signing service. * It uses OpenSSL libcrypto (3.5 or later, for ML-DSA-65) as its own * cryptography, so the library never sees its private keys. The interface * makes no claim about any particular KMS or HSM. * * Build and run: examples/v2/c/test.sh */#include <openssl/core_names.h>#include <openssl/evp.h>#include <openssl/params.h>
#include "example_util.h"
#define START 1800000000LL/* 32 bytes of 0x42: a fixed challenge, since nothing is verified live here. */#define CHALLENGE_B64 "QkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkI="
/* A signing service. Its private keys never leave it. It signs in direct * mode: Ed25519 over the 77-byte message M and ML-DSA-65 over M with the * library-chosen context string. */typedef struct { const char *name; RatifyV2PublicKey pub; EVP_PKEY *ed; EVP_PKEY *ml; char log[160];} provider;
static void provider_init(provider *p, const char *name) { size_t len; p->name = name; p->log[0] = '\0'; p->ed = EVP_PKEY_Q_keygen(NULL, NULL, "ED25519"); p->ml = EVP_PKEY_Q_keygen(NULL, NULL, "ML-DSA-65"); if (!p->ed || !p->ml) fail("provider key generation failed (OpenSSL 3.5 or later is required)"); len = sizeof p->pub.ed25519; if (!EVP_PKEY_get_raw_public_key(p->ed, p->pub.ed25519, &len) || len != sizeof p->pub.ed25519) fail("provider Ed25519 public key"); len = sizeof p->pub.ml_dsa_65; if (!EVP_PKEY_get_raw_public_key(p->ml, p->pub.ml_dsa_65, &len) || len != sizeof p->pub.ml_dsa_65) fail("provider ML-DSA-65 public key");}
static int32_t provider_public_key(void *user, RatifyV2PublicKey *out) { *out = ((const provider *)user)->pub; return 0;}
static int32_t provider_sign(void *user, const RatifyV2SignRequest *req, RatifyV2Signature *out) { provider *p = user; /* A provider refuses any request for a key it does not hold. */ if (req->mode != RatifyV2SignerDirect || memcmp(req->public_key, &p->pub, sizeof p->pub) != 0) return 1; snprintf(p->log, sizeof p->log, "%s signed: mode=direct message=%zu bytes context=%.*s", p->name, (size_t)req->message.len, (int)req->ml_dsa_context.len, (const char *)req->ml_dsa_context.ptr);
size_t len = sizeof out->ed25519; EVP_MD_CTX *md = EVP_MD_CTX_new(); int ok = md && EVP_DigestSignInit(md, NULL, NULL, NULL, p->ed) == 1 && EVP_DigestSign(md, out->ed25519, &len, req->message.ptr, req->message.len) == 1; EVP_MD_CTX_free(md); if (!ok) return 1; out->ed25519_len = len;
EVP_SIGNATURE *alg = EVP_SIGNATURE_fetch(NULL, "ML-DSA-65", NULL); EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_pkey(NULL, p->ml, NULL); OSSL_PARAM params[] = { OSSL_PARAM_construct_octet_string(OSSL_SIGNATURE_PARAM_CONTEXT_STRING, (void *)req->ml_dsa_context.ptr, req->ml_dsa_context.len), OSSL_PARAM_construct_end(), }; len = sizeof out->ml_dsa_65; ok = alg && ctx && EVP_PKEY_sign_message_init(ctx, alg, params) == 1 && EVP_PKEY_sign(ctx, out->ml_dsa_65, &len, req->message.ptr, req->message.len) == 1; EVP_PKEY_CTX_free(ctx); EVP_SIGNATURE_free(alg); if (!ok) return 1; out->ml_dsa_65_len = len; return 0;}
int main(void) { printf("Ratify Protocol v2 external signer\n");
provider issuer, agent; provider_init(&issuer, "issuer provider"); provider_init(&agent, "agent provider"); RatifyV2ExternalSigner issuer_signer = {&issuer, RatifyV2SignerDirect, provider_public_key, provider_sign}; RatifyV2ExternalSigner agent_signer = {&agent, RatifyV2SignerDirect, provider_public_key, provider_sign}; RatifyV2KeyPair *verifier; CHECK(ratify_v2_keypair_generate(&verifier, NULL, NULL)); char issuer_id[RATIFY_V2_KEY_ID_BUF_LEN], agent_id[RATIFY_V2_KEY_ID_BUF_LEN], verifier_id[RATIFY_V2_KEY_ID_BUF_LEN]; CHECK(ratify_v2_public_key_id(&issuer.pub, issuer_id, sizeof issuer_id)); CHECK(ratify_v2_public_key_id(&agent.pub, agent_id, sizeof agent_id)); CHECK(ratify_v2_keypair_key_id(verifier, verifier_id, sizeof verifier_id)); char *issuer_json = key_json(&issuer.pub), *agent_json = key_json(&agent.pub);
char *cert_in = format( "{\"cert_id\":\"external-signer-cert-1\",\"constraints\":[],\"expires_at\":%lld,\"issued_at\":%lld," "\"issuer_id\":\"%s\",\"issuer_pub_key\":%s,\"scope\":[\"files:read\"],\"subject_id\":\"%s\"," "\"subject_pub_key\":%s,\"version\":2}", START + 86400, START, issuer_id, issuer_json, agent_id, agent_json); RatifyV2Buffer cert_buf; CHECK(ratify_v2_sign_delegation_certificate((const uint8_t *)cert_in, strlen(cert_in), NULL, &issuer_signer, &cert_buf)); printf("%s\n", issuer.log); int cert_ok = ratify_v2_verify_object(RatifyV2KindDelegationCertificate, cert_buf.ptr, cert_buf.len, NULL, NULL) == 0; printf("delegation: signature verified by the SDK (%s)\n", cert_ok ? "true" : "false"); char *cert = take_string(cert_buf);
char *bundle_in = format( "{\"agent_id\":\"%s\",\"agent_pub_key\":%s,\"challenge\":\"%s\",\"challenge_at\":%lld,\"delegations\":[%s]," "\"session_context\":null,\"stream_id\":null,\"stream_seq\":null,\"verifier_id\":\"%s\",\"version\":2}", agent_id, agent_json, CHALLENGE_B64, START, cert, verifier_id); RatifyV2Buffer bundle; CHECK(ratify_v2_sign_proof_bundle((const uint8_t *)bundle_in, strlen(bundle_in), NULL, &agent_signer, &bundle)); printf("%s\n", agent.log); int bundle_ok = ratify_v2_proof_bundle_verify_signatures(bundle.ptr, bundle.len, NULL, 0, NULL) == 0; printf("proof bundle: signatures verified by the SDK (%s)\n", bundle_ok ? "true" : "false");
/* A faulty provider returns an ML-DSA-65 signature from a different key. * The library verifies before use, so nothing is signed. */ EVP_PKEY *wrong = EVP_PKEY_Q_keygen(NULL, NULL, "ML-DSA-65"); if (!wrong) fail("key generation failed"); EVP_PKEY *right = agent.ml; agent.ml = wrong; RatifyV2Buffer refused_buf = {0}; int32_t refused = ratify_v2_sign_proof_bundle((const uint8_t *)bundle_in, strlen(bundle_in), NULL, &agent_signer, &refused_buf); printf("faulty provider: refused (%s)\n", ratify_v2_error_class_str(refused));
ratify_v2_buffer_free(refused_buf); EVP_PKEY_free(wrong); EVP_PKEY_free(right); EVP_PKEY_free(agent.ed); EVP_PKEY_free(issuer.ed); EVP_PKEY_free(issuer.ml); ratify_v2_buffer_free(bundle); free(bundle_in); free(cert); free(cert_in); free(issuer_json); free(agent_json); ratify_v2_keypair_free(verifier); return 0;}Source: examples/v2/c/external_signer at commit 5ca7585c2c1d, SHA-256 checked at build time.
Conformance
Section titled “Conformance”The SDK runs the shared corpus in testvectors/v2.
Which files each SDK runs, and the results at the tag, are recorded in the release notes and in
docs/V2_REFERENCE_COMPATIBILITY.md.
