Caliptra Common Commands

Overview

This document defines the common Caliptra device management commands. These commands are transport-agnostic and common across all vendors integrating the Caliptra subsystem. They are accessed via the following transport mechanisms:

• SPDM VDM over MCTP (out-of-band)
• MCI Mailbox (in-band)

For the unified software architecture that handles both paths, see Unified Caliptra Command Handling.

Command List

The following table describes the commands defined under this specification. There are two categories: (1) Required commands (R) that are mandatory for all implementations, (2) Optional commands (O) that may be utilized if the specific implementation requires it.

Device Information

Logging

Attestation

Debug Unlock

Lifecycle & Provisioning

Certificate Provisioning

Authorized Commands

Device Lifecycle

Command Definitions

This section defines the request and response payloads for each command.

Firmware Version

Retrieves the version of the target firmware.

Request Payload:

Response Payload:

Device Capabilities

Request Payload: Empty

Response Payload:

Device ID

This command retrieves the device ID.

Request Payload: Empty

Response Payload:

Device Information

This command retrieves information about the target device.

Request Payload:

Response Payload:

Export IDevID CSR

Exports the IDevID Certificate Signing Request (CSR) so that a Certificate Authority (CA) can endorse it and issue an IDevID certificate. The CSR is available in two algorithm variants: ECC P-384 and ML-DSA (post-quantum). This command is only available when the device lifecycle state is Manufacturing.

Request Payload:

Response Payload:

Set Slot 0 Cert

Sets the CA-signed IDevID certificate in certificate slot 0 (Vendor slot). This is a one-time operation performed during manufacturing — the command will fail if slot 0 has already been provisioned.

Request Payload:

Response Payload:

Get Slot 0 State

Determines the provisioning state of certificate slot 0 (Vendor PKI). This slot holds the device identity certificate provisioned during manufacturing. For other certificate slots (Owner, Tenant), use the SPDM GET_DIGESTS command.

Request Payload: Empty

Response Payload:

Get Debug Log

Retrieves the debug log for the RoT. The debug log contains RoT application information and machine state, useful for diagnostics and troubleshooting.

Request Payload: Empty

Response Payload:

The length is determined by the end of the log or the packet size based on device capabilities. If the response spans multiple messages, the end of the response will be determined by a message with a payload smaller than the maximum payload supported by both devices.

Debug Log Format:

The debug log reported by the device has no specified format, as this can vary between different devices and is not necessary for attestation. It is expected that diagnostic utilities for the device will be able to understand the exposed log information. A recommended entry format is provided here:

Clear Debug Log

Clears the debug log in the RoT subsystem. No authorization is required.

Request Payload: Empty

Response Payload:

Request Debug Unlock

Requests debug unlock in production environment.

Request Payload:

Response Payload:

Authorize Debug Unlock Token

Authorizes the debug unlock token.

Request Payload:

Response Payload:

Export Attested CSR

Exports an attested Certificate Signing Request (CSR) for a specified device key.

Request Payload:

Response Payload:

Authorized Commands

All commands that require cryptographic authorization are dispatched through the single Authorized Command (0x12) SPDM VDM code using a 1-byte sub_cmd_id field. This ensures a consistent challenge-response flow regardless of which operation is being authorized.

Authorization Flow

The requester must first obtain a one-time challenge nonce from the device, then compute an HMAC-SHA384 MAC over the nonce and command parameters, and include that MAC in the subsequent command request.

Requester                                       Device
    |                                               |
    |-- Authorized Command (sub_cmd_id=0x01) ------>|
    |                                               |-- generate 32-byte nonce
    |<-- challenge[32] -----------------------------|    stored internally (one-time use)
    |                                               |
    | compute MAC:                                  |
    |   HMAC-SHA384(key,                            |
    |     cmd_id_be32(4) || payload_le(N) ||        |
    |     challenge(32))                            |
    |                                               |
    |-- Authorized Command (sub_cmd_id=0x02,        |
    |   payload + mac) ---------------------------->|
    |                                               |-- verify MAC, execute command
    |<-- completion_code ---------------------------|

The cmd_id used in the HMAC input is the sub_cmd_id itself, serialized as a 4-byte big-endian integer. Because sub-command IDs match the canonical MCU mailbox command IDs, the HMAC input is identical across SPDM VDM and MCU mailbox transports.

Request Payload

Response Payload

Sub-Command List

Sub-Command: Get Auth Challenge

Requests a one-time 32-byte challenge nonce from the device. The nonce is stored internally and consumed after the next authorized command is received (or discarded if another Get Auth Challenge is issued).

Sub-Payload: Empty

Sub-Response:

Sub-Command: Program Field Entropy

Programs device-unique entropy into a specific OTP partition. This operation is write-once and irreversible. The requester must have previously obtained a challenge nonce via Get Auth Challenge and computed a valid MAC.

MAC input: HMAC-SHA384(key, sub_cmd_id_be32(4) || partition_le(4) || challenge(32))

where sub_cmd_id = 0x4D43_4650 (MC_FE_PROG). Because the sub-command ID is the same as the canonical MCU mailbox command ID, the HMAC input is identical across SPDM VDM and MCU mailbox transports.

Sub-Payload:

Sub-Response: Empty (success indicated by outer completion_code = 0x00).

Device Ownership Transfer

Transfers device ownership. Requires authorization.

Request Payload: TBD

Response Payload:

Completion Codes

Command responses include a completion code indicating the result of the operation. Standard codes (0x00-0x0F) follow the OCP command registry. Codes 0xC0-0xFF are reserved for Caliptra project-specific errors.

OCP Standard Codes

Caliptra Project-Specific Codes (0xC0-0xFF)