Caliptra Documentation

Caliptra provides control plane services via Logic IOs and a Command Mailbox. These services are used to power on systems or initiate tasks rather than for high-performance data path cryptography.

Service Vectors

• Logic IOs: Used to indicate IP status, message availability via AXI, and to enable/disable debug capabilities (e.g., JTAG enable/disable).
• Command Mailbox: The primary API interface for SoC components. Key services include:
  • Loading firmware: Firmware is loaded via the mailbox at cold boot, or at runtime for hitless/impactless updates.
  • DICE-as-a-Service: Exposes the TCG DICE Protection Environment iRoT Profile API. Caliptra can derive and wield a DICE identity on behalf of other SoC elements (e.g., signing messages for an SPDM responder).
  • Measurement Vault: Supports stashing measurements for SoC code and configuration. Measurements are provided via the PCR Quote API or DPE.
  • FW Authentication: Supports ECDSA and PQC MLDSA-87 verification for SoC firmware. The SHA384 block provides a hardware API for hashing, and the runtime firmware provides the verification APIs.

The Caliptra Checklist and Evaluation Methodology is a guide for the secure integration of Caliptra hardware root-of-trust (RoT) IP into a system-on-chip (SoC). It provides testable requirements and evaluation methods to ensure security compliance (aligning with NIST and FIPS) and to facilitate consistent assessments by security auditors.

Compliance Requirements

Requirements follow RFC 2119 terminology:

• MUST / MUST NOT / REQUIRED / SHALL / SHALL NOT: Mandatory requirements.
• SHOULD / SHOULD NOT / RECOMMENDED: Best practices.
• MAY / OPTIONAL: Non-mandatory options.

Note: Requirements marked with an asterisk () may be exempted if there is sufficient, documented, and approved justification.*

Evidence for Auditors

To demonstrate compliance, vendors must provide collateral to security auditors, such as:

• Integrated RTL
• Synthesized netlist reports
• GLS FEV reports
• SoC boot diagrams
• Documentation summarizing plans and procedures (e.g., NIST-compliant obfuscation key generation)

Caliptra is a design standard for a Silicon Root of Trust (Silicon RoT) implemented within a System on Chip (SoC) or ASIC. Its purpose is to provide core security capabilities for datacenter-class devices (such as CPUs, GPUs, SmartNICs, and SSDs) to ensure platform integrity.

Key components of the Caliptra 2.0 specification include:

• Root of Trust for Measurement (RTM): Measures the code and configuration the SoC boots into.
• Root of Trust for Identity (RTI): Stores measurements and reports them via signed attestations rooted in unique per-asset cryptographic entropy.
• Root of Trust for Update (RTU): Authenticates firmware updates and critical data changes.
• Root of Trust for Recovery (RTRec): Handles recovery of firmware and critical data when corruption is detected or requested.

Caliptra is designed to be minimalistic to maximize architectural composability and reusability across different Cloud Service Providers (CSPs) and vendors.

The Caliptra module operates according to a Finite State Model (FSM) to ensure FIPS compliance. The module transitions through various states including initialization, self-testing, identity generation, and command processing. Understanding these states is critical for predicting the module's behavior during power-on, reset, and runtime command execution.

Key state categories include:

• Initialization & Self-Test: OFF (Power off), INIT (Cold reset/General initialization), and SELF-TEST (which includes specific sub-states ST01 through ST07 for KAT and integrity tests).
• Identity & Context: READ SECRETS (CSP entry), and various CTX states (CTX IDEVID, CTX LDEVID, CTX FMC, CTX RTn) used for generating layer identities and measurements.
• Operational States: AWAIT CMD (Crypto Officer state), MB SERVICE (Approved state for processing mailbox commands), and specific command-handling states like FW_LOAD, IDENTITY, MEASUREMENT, SANITIZE, SELF-TEST, UTILITY, VERIFY, and VERSION.
• Error State: ERROR (Error state).

When implementing or validating Caliptra for FIPS compliance, ensure the following Cryptographic Algorithm Self-Test (CAST) requirements are met for signature algorithms:

• Deterministic ECDSA: If deterministic ECDSA signature generation is implemented, it must have its own dedicated CAST. Note that signature verification self-tests satisfy the requirement for signatures generated via deterministic ECDSA.
• Dual Implementation: If both standard ECDSA signature generation and deterministic ECDSA signature generation are implemented in the approved mode, each must have its own independent self-test.
• Randomized Algorithms (DSA, ECDSA, RSA PSS): For algorithms where output varies for a given set of inputs, you must implement both a signature generation CAST and a signature verification CAST.
  • Known Answer Test (KAT): Requires the randomization parameter to be fixed.
  • Comparison Test: Requires the randomization parameter to be shared across all compared implementations.
• Curve Coverage: An ECDSA CAST must be performed on at least one implemented NIST-recommended curve (included in the CAVP certificate) for each supported field type: prime fields $GF(p)$ and binary fields $GF(2^m)$.

All Caliptra Mailbox commands support asynchronous usage. When the asynchronous option (the last parameter) is set, the function returns immediately after the request is issued. To complete the transaction, follow this lifecycle:

1. Issue Command: Call the specific command function with the asynchronous flag set.
2. Poll for Completion: Use caliptra_test_for_completion to check if the operation is finished. This returns True if the mailbox is no longer busy.
3. Finalize Transaction: Once polling returns True, call caliptra_complete. This resets the mailbox and software state and populates the response buffer provided during the initial command.

CRITICAL: The caller MUST ensure the response buffer remains available in memory until caliptra_complete returns.

Note: Avoid using caliptra_mailbox_execute directly; use the specific command functions provided for your task.

// Conceptual workflow for asynchronous command
// 1. Issue command
caliptra_specific_command(..., true); 

// 2. Poll
while (caliptra_test_for_completion()) {
    // Wait or perform other tasks
}

// 3. Complete
caliptra_complete();