Skip to content
You are reading the Ratify Protocol v2 beta documentation. Protocol v1 remains available at the site root.

C SDK (v2)

Terminal window
# 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-protocol
cd ratify-protocol/sdks/c
cargo build --release

Package: 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_*_free function.
  • 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_version at startup.

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.

Delegate, present, verify, and release: C quickstart (development only).

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.

examples/v2/c/signed_status.c
/*
* 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.

An exact custom: required scope and a registered evaluator profile. See Delegation and constraints.

examples/v2/c/custom_scope.c
/*
* 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, &registry);
attempt(&d, "request nodes=8", 8, &registry);
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.

Signing through a key held outside the SDK, with verify-before-use. See Typed signing and key IDs.

examples/v2/c/external_signer.c
/*
* 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.

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.