Caliptra SPDM VDM Commands

Overview

This document describes how Caliptra common commands are transported over SPDM Vendor Defined Messages (VDM) via MCTP. This is the out-of-band (OOB) path for standard, vendor-neutral Caliptra device management commands that require SPDM-defined semantics, SPDM authorization, or SPDM streaming/chunking.

For command definitions (categories, payloads, and completion codes), see Caliptra Common Commands.

For the unified software architecture shared between OOB (SPDM VDM) and in-band (MCI Mailbox) paths, see Unified Caliptra Command Handling.

Transport Stack

┌─────────────────────────────────────────┐
│        Caliptra VDM Commands            │
│ (FirmwareVersion, ExportAttestedCsr, …) │
├─────────────────────────────────────────┤
│      Caliptra Command Header            │
│     (Command Version, Command Code)     │
├─────────────────────────────────────────┤
│        OCP SPDM VDM Framing             │
│     (IANA Registry ID, Vendor ID)       │
├─────────────────────────────────────────┤
│              SPDM                       │
│     (VENDOR_DEFINED_REQUEST/RESPONSE)   │
├─────────────────────────────────────────┤
│              MCTP                       │
│        (Message Type 0x05)              │
├─────────────────────────────────────────┤
│         Physical Layer                  │
│              (I3C)                      │
└─────────────────────────────────────────┘

SPDM VDM Encapsulation

Caliptra commands assigned to SPDM VDM are carried within SPDM VENDOR_DEFINED_REQUEST and VENDOR_DEFINED_RESPONSE messages using the OCP-assigned Vendor ID (42623). The command range 0x01-0x20 is reserved in the OCP registry and defined by the Caliptra Working Group.

OCP VDM Header

The SPDM VDM standard header identifies the vendor organization:

Caliptra VDM Message Header

Following the OCP VDM standard header, the Caliptra-specific message header appears:

Response Format

Responses follow the same header structure. The Command Code in the response mirrors the request. The response payload begins with a CaliptraCompletionCode (1 byte) indicating success or failure. Command-specific response data, if any, follows the completion code:

See Completion Codes for the full list of error codes.

The SPDM VDM completion code is transport-specific response status and is not included in the transport-agnostic common response payload tables.

Command Codes

The following table maps SPDM VDM command codes to Caliptra common commands. For command payload definitions, see Caliptra Common Commands.

These command codes are assigned from the Caliptra range reserved in the OCP command registry.

R = Required, O = Optional

Implemented commands are advertised in the external_commands field returned by DeviceCapabilities. Implemented operations under AuthorizedCommand are advertised individually in authorized_subcommands. Recognized but unimplemented commands are not advertised. See Device Capabilities.

Authorization-Gated Subcommands

The following subcommands are assigned to the SPDM VDM IANA authorization-gated path and are carried under AuthorizedCommand. Multi-byte payload integers and the subcommand ID are encoded little-endian on the wire.

Authorization Flow

1. Send GetAuthChallenge with an empty subcommand payload. The successful response data is a 48-byte challenge.
2. Serialize the target subcommand payload exactly as listed below, excluding the common authorization trailer.
3. Sign subcommand_id(BE) || payload || challenge with both the authorized ECC P-384 and ML-DSA-87 keys. The signed command ID is big-endian even though the AuthorizedCommand wire field is little-endian.
4. Append the common authorization trailer and submit the complete request under AuthorizedCommand.

For ordinary authorized subcommands, subcommand_id is the FourCC shown in the table. For DOT, subcommand_id is the family ID 0x00000011; the signed payload is DOT_FourCC(LE) || DOT_payload. Thus both MCI and SPDM verify the same preimage:

0x00000011(BE) || DOT_FourCC(LE) || DOT_payload || challenge

The common authorization trailer is:

nonce[48] || ecc_pub_x[48] || ecc_pub_y[48] || mldsa_pub[2592] || HybridSignature

nonce echoes the challenge. HybridSignature is ecc_sig_r[48] || ecc_sig_s[48] || mldsa_sig[4628]. The challenge is consumed by the verification attempt and cannot be reused. Requests must have the exact documented size; missing, truncated, and oversized trailers are rejected with InvalidPayloadSize, while failed authorization returns AccessDenied.

Implemented Subcommand Payloads

Byte offsets below begin immediately after the four-byte subcommand_id and include the complete authorization trailer.

Device Ownership Transfer Commands

Runtime DOT commands use a common four-byte subcommand namespace under family ID 0x11. Multi-byte fields are little-endian.

Authorization-gated DOT request:

[version=1][command=0x12][family=0x11:u32][DOT FourCC:u32]
[DOT payload][authorization trailer]

Native-authenticated/read-only DOT request:

[version=1][command=0x11][DOT FourCC:u32][DOT payload]

MDLK, MDDS, MDRT, and MDBB are rejected with AccessDenied when sent directly under top-level command 0x11. Recovery-mode gating for MDRC, DOTW, and DOTX is deferred; their native cryptographic and state checks are always enforced.

For detailed command flows, state transitions, security properties, and use cases, see Device Ownership Transfer (DOT).