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:

• MCTP VDM (out-of-band)
• 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.

Transport-specific command codes are defined by the transport documents. This document defines the common command names, transport assignment, and payload semantics.

Transport Selection

Commands are assigned to MCTP VDM IANA when they do not require SPDM authorization, SPDM-defined semantics, or SPDM streaming/chunking. Commands are assigned to SPDM VDM IANA when they require those properties. The MCI mailbox provides the in-band path for the same common command semantics where implemented.

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.

Authorization-Gated Subcommands

The following subcommands are assigned to the SPDM VDM IANA authorization-gated path and are also available through the MCI mailbox path where implemented. SPDM VDM requests use the challenge and hybrid-signature flow described in Caliptra SPDM VDM Commands. For the MCI mailbox path, access control is governed by the mailbox security boundary and platform policy.

Command Definitions

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

Common response payload tables describe command-specific response data only. They exclude transport-specific status and framing fields such as SPDM VDM completion codes, MCTP VDM completion codes, MCI mailbox chksum, MCI mailbox fips_status, and MCI mailbox variable-length data_len headers.

Firmware Version

Retrieves the version of the target firmware.

Request Payload:

Response Payload:

Versions use major.minor.patch ASCII format. Index 02h returns UnsupportedOperation when the integrator does not provide a single aggregate SoC firmware-set version. Individual SoC component versions may use firmware-specific additional indexes.

Device Capabilities

Request Payload: Empty

Response Payload:

external_commands covers the OCP command codes 01h through 20h. Command code N maps to bitmap bit N - 1, allowing all 32 top-level codes to fit in this field. This is Caliptra common-command discovery carried by DeviceCapabilities; it is not MCTP Control Protocol command discovery.

External Common-Command Capability Flags:

This table defines the bit assignment for every allocated command code. A responder sets a bit only when the corresponding command is implemented. GetAttestation is set when a responder that carries it is built and the device can produce at least one evidence format. AuthorizedCommand is set when its wrapper and at least one authorized subcommand are implemented.

Authorized-Subcommand Capability Flags:

The authorized-subcommand assignments are stable capability indexes; they are not transport command IDs. A responder sets a bit only when that subcommand is implemented under AuthorizedCommand. Authorization, lifecycle, or policy restrictions do not clear an implementation capability bit; execution can still return AccessDenied, PolicyViolation, or InvalidState.

MCU Runtime Capability Flags:

The mcu_rom field is reserved for a future versioned ROM-to-Runtime capability handoff. Until that handoff is specified, responders set mcu_rom to zero and the following assignments are not advertised.

Proposed MCU ROM Capability Flags:

Get Debug Log

Retrieves the debug log for the MCU Runtime.

Request Payload: Empty

Response Payload:

For defmt-based debug logs, the device exposes a sequential drain interface rather than random access to individual log entries. Callers drain the debug log by repeating this command until more_data is 0. Each response contains zero or more complete defmt frames. The host concatenates the returned data and decodes the resulting frame stream using the matching firmware ELF.

Debug Log Format:

The debug log payload is an opaque byte stream. For the MCU Runtime debug log, the current implementation uses the defmt crate. Each defmt log macro emits one complete rzCOBS-encoded frame, and the MCU runtime logging backend appends that complete frame as one flash log entry. Get Debug Log returns the concatenated raw frame bytes.

The device does not store human-readable log strings in the debug log. A host tool decodes the returned byte stream with defmt-decoder or defmt-print using the exact app's ELF that produced the log; the ELF .defmt section contains the interned format strings and metadata required to render readable messages.

Clear Debug Log

Clears the debug log in the MCU Runtime. No authorization is required.

Request Payload: Empty

Response Payload: Empty. Command completion status is carried by the transport-specific response framing.

Get Attestation

Retrieves signed attestation evidence bound to a requester-supplied nonce.

The requester selects the evidence format at runtime. The set of formats a device can produce is fixed at build time by the evidence generators it links. A requester discovers that set with the format-discovery query below.

All formats are signed with the device attestation key that terminates the device's SPDM certificate chain. Evidence retrieved over the MCI mailbox verifies against a certificate chain retrieved over SPDM, and the reverse.

Evidence Formats

A device that supports a format need not support it under every algorithm. The OCP EAT signer emits ES384 only; ML-DSA-87 EATs are not implemented yet. A request naming an unsupported (evidence_format, algorithm) pair returns UNSUPPORTED_OPERATION and no evidence is generated.

PKI Entity Slot

pki_entity_slot names the PKI entity whose hierarchy endorses the signing key.

A value not listed above returns INVALID_PARAMS. Owner is reserved and returns UNSUPPORTED_OPERATION today: signing is not yet slot-aware, so every entity would resolve to the same vendor key, and serving it would return evidence claiming an endorsement that was never selected or provisioned. Once signing is slot-aware, whether an entity can be served follows the provisioning state of its endorsement slot.

Format Discovery

A request with evidence_format = 0x0000 is a query, not an evidence request. The device returns a bitmap of the formats it can produce instead of evidence. Bit n of the bitmap is set when the device supports the format whose wire value is n; bit 0 is never set.

The supported set depends on which evidence generators the integrator built into the device. A requester issues this query before requesting evidence rather than inferring the set from DeviceCapabilities.

Request Payload:

For the query request, algorithm, pki_entity_slot, and nonce are ignored. For an evidence request, a value outside the tables above returns INVALID_PARAMS.

Response Payload:

The evidence blob is variable length, delimited by the transport's length field. The transports scope that field differently:

For the MCI mailbox the evidence length is therefore data_len - 4.

Truncated evidence cannot pass signature verification, so a device that cannot fit the evidence in the response buffer fails the command instead.

Transport Sizing

Attestation evidence is variable length, and its size depends on which evidence generators the integrator builds into the device. Each transport sizes its response buffer from those generators:

• SPDM VDM reserves the size the requested format needs. Evidence that does not fit in a single message is returned over the large-response (chunked) path. The advertised MaxSPDMmsgSize must cover the largest evidence the device can produce. See SPDM VDM commands.
• MCI Mailbox sizes the GET_ATTESTATION response buffer for the largest supported evidence. Other commands' response buffers are unaffected.

Request Debug Unlock

Requests debug unlock in production environment.

Request Payload:

Response Payload:

Authorize Debug Unlock Token

Authorizes the debug unlock token. The request body is identical for MCI mailbox and SPDM VDM transports. The requester computes the leading checksum field as the Caliptra RT mailbox request checksum so the unified command handler can relay the complete request unchanged.

Request Payload:

Response Payload: Empty. Command completion status is carried by the transport-specific response framing.

Export Attested CSR

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

Request Payload:

Response Payload:

Authorization-Gated Subcommand Wrapper

Security-sensitive provisioning and fuse subcommands are assigned to the SPDM VDM IANA authorization-gated path and the MCI mailbox path. The SPDM VDM transport uses an Authorized Command wrapper. Its requester first obtains a one-use 48-byte challenge, then appends a hybrid signature over sub_cmd_id(BE) || sub_payload || challenge. See Caliptra SPDM VDM Commands for the byte-exact transport payloads.

Request Payload

Response Payload

The subcommands covered by this wrapper are listed in Authorization-Gated Subcommands.

DotLock, DotDisable, DotRotate, and GetDotBackupBlob are the DOT-family subcommands that use this authorization wrapper. The remaining DOT commands (DotUnlockChallenge, DotUnlock, DotStatus, DotRecovery, DotOverrideChallenge, and DotOverride) are native device-ownership-transfer commands carried under top-level command 0x11 rather than via the AuthorizedCommand wrapper.

Subcommand-specific payloads are defined by the corresponding command specifications and contain no mailbox request header.

Get Auth Challenge

Requests a one-use challenge for authorization-gated commands.

Request Payload: Empty

Response Payload:

Provision Vendor PK Hash

Provisions the vendor public key hash.

Request Payload: slot:u32 | hash:u8[48] | HybridSignature

Response Payload: Empty

Fuse Increase Caliptra Min SVN

Increases the Caliptra minimum SVN.

Request Payload: flags:u32 | svn:u32 | HybridSignature

Response Payload: Empty

Program Field Entropy

Programs field entropy.

Request Payload: partition:u32 | HybridSignature

Response Payload: Empty

Fuse Revoke Vendor Public Key

Revokes a vendor public key.

Request Payload: reserved:u32 | slot:u32 | key_type:u32 | key_index:u32 | HybridSignature

Response Payload: Empty

Fuse Revoke Vendor PK Hash

Revokes a vendor public key hash.

Request Payload: reserved:u32 | slot:u32 | HybridSignature

Response Payload: Empty

Fuse Lock Partition

Locks a fuse partition.

Request Payload: TBD

Response Payload: TBD

Device Ownership Transfer (DOT)

The device-ownership-transfer family is carried under the top-level DeviceOwnershipTransfer command (0x11). This family uses the DOT FourCC namespace and is split between authorization-gated and native commands:

• Authorization-gated: MDLK (DotLock), MDDS (DotDisable), MDRT (DotRotate), MDBB (GetDotBackupBlob)
• Native: MDUC (DotUnlockChallenge), MDUL (DotUnlock), MDST (DotStatus), MDRC (DotRecovery), DOTW (DotOverrideChallenge), DOTX (DotOverride)

The authorization-gated DOT commands are sent via the AuthorizedCommand wrapper and are rejected if delivered directly under 0x11. The native DOT commands perform challenge-and-signature verification against the current ownership blob or the recovery-key hash, as appropriate for the command.

See DOT Commands for the detailed state machine, validation rules, and command sequencing.

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)