User Guide#

Overview#

This guide provides detailed examples and best practices for using the NVIDIA Attestation SDK Rust bindings.

API Organization#

The Rust SDK provides a safe API that wraps the C library. Key modules include:

  • client: SDK initialization and global configuration

  • context: Attestation context and workflow orchestration

  • nonce: Nonce generation and management

  • evidence: Evidence collection and handling

  • verifier: Local and remote verification

  • result: Attestation results and claims

Core Concepts#

SDK Initialization#

The SDK must be initialized before use with NvatSdk::init_default() or NvatSdk::init(options):

// Simple initialization with defaults
let client = NvatSdk::init_default()?;

// Or with custom options
let mut opts = SdkOptions::new()?;
// Configure options...
let client = NvatSdk::init(opts)?;

The NvatSdk instance manages global SDK state and should be kept alive for the duration of SDK usage.

Attestation Context#

The AttestationContext represents an attestation session and is used to configure and execute attestation:

let mut ctx = AttestationContext::new()?;
ctx.set_device_type(DeviceType::Gpu)?;
ctx.set_verifier_type(VerifierType::Remote)?;

Device Types#

  • DeviceType::Gpu: NVIDIA GPUs (Hopper, Blackwell, etc.)

  • DeviceType::NvSwitch: NVIDIA NVLink Switches

Verifier Types#

  • VerifierType::Local: Verify evidence locally using RIM store and OCSP

  • VerifierType::Remote: Use NVIDIA Remote Attestation Service (NRAS)

Nonce Operations#

Nonces provide freshness guarantees for attestation:

// Generate random nonce
let nonce = Nonce::generate(32)?;
println!("Nonce: {}", nonce.to_hex_string()?);

// Create from hex string
let nonce2 = Nonce::from_hex("0123456789abcdef")?;

// Get raw bytes
let bytes = nonce.as_bytes();

Error Handling#

All operations return Result<T, NvatError>:

match ctx.attest_device(None) {
    Ok(result) => {
        println!("Success: {:?}", result);
    }
    Err(e) => {
        eprintln!("Error {}: {}", e.code, e.message());
    }
}

The NvatError type provides:

  • Error code from the C library

  • Human-readable error message

  • Implementation of std::error::Error for integration with error handling libraries

GPU Ready State#

After successful attestation, GPUs may need to be transitioned to the Ready state before they can be used for workloads. This is only required when Confidential Computing is enabled.

For details on setting the GPU Ready state, see the Overview - GPU Ready State section.

Quick Start#

Examples#

The attestation examples below work with supported NVIDIA GPU architectures in both single and multi-GPU configurations.

If attestation is successful, the examples print the detached EAT and the claims. For more details on the structure of both, see the Claims Schema Reference.

For attestation on Hopper PPCIE, please refer to this documentation.

Example 1: Remote GPU Attestation#

View Source Code

This example demonstrates end-to-end GPU attestation with remote verification using NRAS:

use nv_attestation_sdk::{
    NvatSdk, AttestationContext, Nonce,
    DeviceType, VerifierType
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize SDK
    let _client = NvatSdk::init_default()?;

    // Create and configure attestation context
    let mut ctx = AttestationContext::new()?;
    ctx.set_device_type(DeviceType::Gpu)?;
    ctx.set_verifier_type(VerifierType::Remote)?;

    // Generate nonce for freshness
    let nonce = Nonce::generate(32)?;
    println!("Generated nonce: {}", nonce.to_hex_string()?);

    // Perform attestation
    println!("Attesting GPU...");
    let result = ctx.attest_device(Some(&nonce))?;

    // Get and display results
    let eat = result.eat_json()?;
    let claims = result.claims_json()?;

    println!("\n=== Attestation Successful ===");
    println!("\nEntity Attestation Token (EAT):");
    println!("{}", eat);
    println!("\nClaims:");
    println!("{}", claims);

    Ok(())
}

Key Concepts:

  • SDK initialization with NvatSdk::init_default()

  • Attestation context creation and configuration

  • Nonce generation for replay protection

  • Remote verification via NRAS

  • Results extraction and display

Example 2: Local GPU Attestation#

View Source Code

This example shows local verification using a RIM store and OCSP client:

use nv_attestation_sdk::{
    NvatSdk, AttestationContext, RimStore, OcspClient,
    HttpOptions, DeviceType, VerifierType
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _client = NvatSdk::init_default()?;

    // Configure HTTP options
    let mut http_opts = HttpOptions::default_options()?;
    http_opts.set_max_retry_count(5);
    http_opts.set_connection_timeout_ms(10000);
    http_opts.set_request_timeout_ms(30000);

    // Create RIM store
    let _rim_store = RimStore::create_filesystem("/var/lib/nvat/rims")?;

    // Create OCSP client
    let _ocsp_client = OcspClient::create_default(
        Some("https://ocsp.attestation.nvidia.com"),
        Some("your-api-key"),
        Some(&http_opts)
    )?;

    // Configure for local verification
    let mut ctx = AttestationContext::new()?;
    ctx.set_device_type(DeviceType::Gpu)?;
    ctx.set_verifier_type(VerifierType::Local)?;

    // Perform attestation
    println!("Performing local attestation...");
    let result = ctx.attest_device(None)?;

    println!("Local attestation successful!");
    println!("Claims: {}", result.claims_json()?);

    Ok(())
}

Key Concepts:

  • HTTP options configuration for network requests

  • Filesystem-based RIM store

  • OCSP client for certificate revocation checking

  • Local verification workflow

Example 3: Low-Level Evidence Collection#

This example demonstrates manual evidence collection and verification using low-level APIs:

use nv_attestation_sdk::{
    NvatSdk, GpuEvidenceSource, GpuEvidence, GpuVerifier,
    Nonce, RimStore, OcspClient, HttpOptions
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _client = NvatSdk::init_default()?;

    // Create evidence source (NVML or Corelib)
    let evidence_source = GpuEvidenceSource::create_nvml()?;

    // Generate nonce
    let nonce = Nonce::generate(32)?;

    // Collect evidence
    println!("Collecting GPU evidence...");
    let evidence = GpuEvidence::collect(&evidence_source, Some(&nonce))?;

    // Serialize evidence to JSON
    let evidence_json = evidence.to_json()?;
    println!("Evidence collected: {} bytes", evidence_json.len());

    // Set up verification components
    let http_opts = HttpOptions::default_options()?;
    let rim_store = RimStore::create_filesystem("/var/lib/nvat/rims")?;
    let ocsp_client = OcspClient::create_default(
        Some("https://ocsp.attestation.nvidia.com"),
        Some("your-api-key"),
        Some(&http_opts)
    )?;

    // Create local verifier
    let verifier = GpuVerifier::create_local(
        &rim_store,
        &ocsp_client,
        None // No HTTP options override
    )?;

    // Verify evidence
    println!("Verifying evidence...");
    let verification_result = verifier.verify(&evidence, Some(&nonce))?;

    println!("Verification successful!");
    println!("Claims: {}", verification_result.claims_json()?);

    Ok(())
}

Key Concepts:

  • Manual evidence source creation

  • Direct evidence collection

  • Evidence serialization

  • Manual verifier setup

  • Low-level verification workflow

Example 4: Custom Logging#

This example shows how to integrate SDK logging with Rust’s logging ecosystem:

use nv_attestation_sdk::{NvatSdk, SdkOptions, Logger};
use log::{info, debug};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize env_logger for Rust logging
    env_logger::Builder::from_default_env()
        .filter_level(log::LevelFilter::Debug)
        .init();

    info!("Initializing NVIDIA Attestation SDK");

    // Create SDK options
    let mut opts = SdkOptions::new()?;

    // Create logger that forwards C SDK logs to Rust's log facade
    let logger = Logger::new()?;
    opts.set_logger(logger);

    // Initialize SDK with logging
    let _client = NvatSdk::init(opts)?;

    debug!("SDK initialized successfully");

    // SDK operations will now log through env_logger
    // ...

    Ok(())
}

Key Concepts:

  • Integration with env_logger

  • Custom logger creation

  • C SDK log forwarding to Rust log facade

  • Unified logging for Rust and C components

Example 5: NVSwitch Attestation#

This example demonstrates NVSwitch attestation:

use nv_attestation_sdk::{
    NvatSdk, AttestationContext,
    DeviceType, VerifierType
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _client = NvatSdk::init_default()?;

    let mut ctx = AttestationContext::new()?;

    // Configure for NVSwitch
    ctx.set_device_type(DeviceType::NvSwitch)?;
    ctx.set_verifier_type(VerifierType::Remote)?;

    // Perform attestation
    println!("Attesting NVSwitch...");
    let result = ctx.attest_device(None)?;

    println!("NVSwitch attestation successful!");
    println!("Claims: {}", result.claims_json()?);

    Ok(())
}

Key Concepts:

  • NVSwitch device type configuration

  • NVSwitch-specific attestation workflow

Next Steps#