User Guide#

Overview#

The C API of nvat is located here This document follows the terminology and architectural concepts defined in the Remote Attestation Procedures Architecture (RATS) RFC.

The API is divided into high level and low level APIs.

The high level API offers a pluggable interface to perform end-to-end system attestation, which includes collecting evidence from an attester, submitting the evidence to a verifier to obtain attestation results, and applying appraisal policies to attestation results. The entrypoint for the high level APIs is nvat_attest_device().

The SDK also provides low-level APIs for advanced or custom attestation workflows. These APIs allow you to directly collect evidence, verify evidence, and evaluate attestation results as needed. For example, you can use nvat_gpu_evidence_collect() to gather GPU evidence from a system. This function is useful if you need to submit evidence to a custom verifier or save it for auditing. Similarly, nvat_verify_gpu_evidence() can be used to verify evidence that was collected elsewhere or at a different time.

Check API groups to see all the api’s, categorized by their functionality.

Conventions#

  • Allocations:

    • All structures besides return codes, primitive flags, and bitmaps are opaque and cannot be allocated on the stack. For example, nvat_sdk_opts_t is defined as typedef nvat_sdk_opts_st* nvat_sdk_opts_t. nvat_sdk_opts_st is forward declared and cannot be directly used outside the SDK. The rest of this document will omit this detail for brevity.

    • All structures are allocated on the heap using functions named nvat_<type>_create and released using nvat_<type>_destroy.

    • Most objects internally implement reference counting, so the user must free the objects created by SDK. Any exceptions will be called out in the API documentation.

  • Error handling:

    • All fallible errors return nvat_rc_t (NVAT_RC_OK to indicate the success case) .

    • Return values are communicated to callers using out parameters which are always the last parameter of a function signature.

Examples#

The NVIDIA Attestation SDK provides a simple C API for performing hardware attestation of NVIDIA GPUs and switches. This guide links to examples which cover the most common use cases.

The attestation examples below will work for the following GPU architectures and configurations:

  • Hopper Single GPU

  • Blackwell Single GPU

  • Blackwell Multi GPU

If attestation is successful, the examples print the detached EAT and the claims. For more details on the structure of both of those, please see here.

For an example of doing attestation on Hopper PPCIE, please refer to this. The docs for Hopper PPCIE verifier are here

Basic GPU Attestation#

View Source Code

This example demonstrates how to perform basic GPU attestation using the NVIDIA Attestation SDK. This is the most common use case - verifying the integrity and authenticity of NVIDIA GPU hardware and firmware using a complete end-to-end attestation workflow with a relying party policy. It combines features from other specific examples into a unified demonstration.

Local Attestation#

View Source Code

Perform attestation where the verification logic runs locally on the same device.

Remote Attestation#

View Source Code

Perform attestation using a remote verification service (NRAS).

Attesting with an appraisal policy for attestation results#

View Source Code

Learn how to apply a custom OPA Rego policy to the attestation results. This allows you to define specific security criteria that must be met.

Attestation without any appraisal policy#

View Source Code

Run attestation without applying any specific relying party policy.

Evidence Collection#

View Source Code

Understand how to collect attestation evidence and perform verification using lower-level APIs. This example demonstrates how to manually collect GPU evidence, set up verification components, and process attestation results. This approach provides more control over the attestation process compared to the simplified nvat_attest_device() workflow.

Custom Logger#

View Source Code

Learn how to integrate custom logging functionality with the attestation SDK. The SDK provides flexible logging capabilities that can be customized to integrate with your application’s logging system. You can define custom callbacks for log message handling, filtering, and flushing.

Verifying an attestation token (relying party)#

View Source Code

A relying party receives a detached EAT produced by nvat_attest_device() and wants to verify it independently.

A service key is optional — the public JWKS endpoint at <nras_base_url>/.well-known/jwks.json does not require one, so pass NULL unless your NRAS deployment authenticates the JWKS fetch.

Step 1 — Verify the token and decode the claims#

nvat_claims_collection_t claims;
nvat_rc_t rc = nvat_verify_attestation_result(
    eat_json_string,
    "https://nras.attestation.nvidia.com",
    NULL,           /* service_key — NULL sends no credential (JWKS is public) */
    NULL,           /* expected_nonce — NULL skips the nonce check */
    NULL,           /* http_options — NULL uses defaults */
    NULL,           /* jwt_validation_options — NULL uses 60-second leeway */
    &claims);

nvat_verify_attestation_result checks the token’s signature, issuer, and structure. When an expected_nonce is supplied, it also verifies that the token’s eat_nonce matches it.

Pass NULL for http_options to use the SDK defaults, or supply an nvat_http_options_t to configure the HTTPS fetch of the JWKS — for example a custom TLS CA bundle (for a private or internal NRAS) or non-default timeouts.

JWT time claims and clock skew#

When present, the JWT exp, nbf, and iat claims are validated. The SDK allows a 60-second clock-skew leeway by default, which accommodates normal difference between independently synchronized issuer and verifier clocks.

Pass NULL for jwt_validation_options to retain that default. To use a different leeway, create an options handle, set the number of seconds, pass it to nvat_verify_attestation_result(), then free it:

nvat_jwt_validation_options_t jwt_options = NULL;
nvat_jwt_validation_options_create_default(&jwt_options);
nvat_jwt_validation_options_set_clock_skew_leeway_seconds(
    jwt_options, 5 * 60); /* five minutes */

nvat_rc_t rc = nvat_verify_attestation_result(
    eat_json_string, nras_url, NULL, NULL, NULL, jwt_options, &claims);

nvat_jwt_validation_options_free(&jwt_options);

Time-claim failures are reported as JWT expired, JWT not yet valid (nbf), or JWT issued in the future (iat), so callers can distinguish an expired token from a verifier clock that is behind the issuer.

Return codes:

Code

Meaning

NVAT_RC_OK

Token is valid; claims is populated.

NVAT_RC_OVERALL_RESULT_FALSE

Token is valid but the attestation overall result is false; claims is still populated.

NVAT_RC_NONCE_MISMATCH

An expected_nonce was supplied but the token’s eat_nonce did not match it.

NVAT_RC_NRAS_TOKEN_INVALID

Signature, issuer, or structure is invalid.

NVAT_RC_BAD_ARGUMENT

A required argument is NULL.

Step 2 — Optionally apply a relying-party policy#

nvat_relying_party_policy_t rp_policy;
nvat_rc_t rc = nvat_relying_party_policy_create_rego_from_str(&rp_policy, rego_src);
if (rc == NVAT_RC_OK) {
    rc = nvat_apply_relying_party_policy(rp_policy, claims);
    nvat_relying_party_policy_free(&rp_policy);
}
/* rc == NVAT_RC_RP_POLICY_MISMATCH if the policy rejected the claims */

Freshness / nonce flow#

In the RATS architecture the relying party is the challenger. A complete freshness-preserving exchange works as follows:

  1. Relying party generates a nonce and sends it to the attesting party:

    nvat_nonce_t nonce;
nvat_nonce_create(&nonce, 32);
/* ... transport nonce to the attesting party ... */

  2. Attesting party runs attestation with the nonce and returns the resulting EAT to the relying party:

    nvat_attest_device(ctx, nonce, &eat, &claims);
/* ... send eat back to the relying party ... */

  3. Relying party verifies the returned EAT, passing the nonce it issued so the SDK enforces freshness:

    nvat_verify_attestation_result(eat, nras_url, NULL /*service_key*/, nonce /*expected_nonce*/, NULL /*http_options*/, NULL /*jwt_validation_options*/, &claims);

Note: When an expected_nonce is supplied, nvat_verify_attestation_result verifies that the token’s overall eat_nonce equals it and returns NVAT_RC_NONCE_MISMATCH otherwise. Passing NULL skips this comparison (the token must still contain a nonce). A relying party that prefers to compare freshness itself can still inspect the eat_nonce field in the decoded claims.

Selecting the OCSP CertID hash#

The C API defaults to SHA-256. Create an options handle, optionally select a different algorithm, pass it to the options-aware constructor, and then free the handle. The following example shows all supported choices; leave the setter out for the default SHA-256 choice:

nvat_ocsp_client_options_t options = NULL;
nvat_ocsp_client_t client = NULL;
nvat_rc_t rc = nvat_ocsp_client_options_create_default(&options);

/* Default: SHA-256. Select one of these instead when needed: */
/* rc = nvat_ocsp_client_options_set_cert_id_hash_algorithm(
       options, NVAT_OCSP_CERT_ID_HASH_SHA1);   // legacy responder */
/* rc = nvat_ocsp_client_options_set_cert_id_hash_algorithm(
       options, NVAT_OCSP_CERT_ID_HASH_SHA384); */

if (rc == NVAT_RC_OK) {
    rc = nvat_ocsp_client_create_default_with_options(
        &client, NULL, NULL, NULL, options);
}

nvat_ocsp_client_options_free(&options);
nvat_ocsp_client_free(&client);

nvat_ocsp_client_create_aia accepts the same options handle when OCSP responder URLs should be read from certificate AIA extensions.

Next Steps#

Explore the Full API#

  • Complete API Reference: Browse the API groups for detailed descriptions of all SDK functions, types, and constants

  • Advanced Configuration: See here to learn more about configuring the attestation process