External Mailbox (MCI Mailbox) Commands Spec

Overview

This document outlines the external mailbox commands that enable SoC agents to interact with the MCU via MCI mailbox. These commands support common Caliptra management functions, including querying firmware information, retrieving debug and attestation logs, exporting attested CSRs, utilizing cryptographic services, secure debug unlock, and in-field fuse provisioning.

The MC_AUTHORIZED_COMMAND envelope described here is an MCU Runtime protocol. MCU ROM's boot-time fuse mailbox retains its ROM-specific direct command framing and is not changed by this Runtime ABI.

• Device Identification and Capabilities

  • Retrieve firmware versions and device capabilities to ensure compatibility and proper configuration.

• Debugging and Diagnostics

  • Retrieve debug logs to analyze device behavior, diagnose issues, and monitor runtime states.
  • Clear logs to reset diagnostic data and maintain storage efficiency.

• Certificate Management

  • Export attested Certificate Signing Requests (CSRs) for device keys to facilitate secure provisioning.

• Cryptographic Services

  • AES encryption and decryption
  • SHA hashing
  • Random number generation
  • Digital signing
  • Signature verification
  • Key exchange

• Debug Unlock Mechanisms

  • Facilitate secure debugging in production environments
  • Ensure controlled access to debugging features

• In-Field Fuse Provisioning

  • See fuses spec for details.

Mailbox Commands List

Vendor-Unique Command IDs

VU00 through VUFF reserve exactly 256 four-byte command IDs for vendor-unique use. The first two bytes are the ASCII characters VU; each suffix byte is one uppercase ASCII hexadecimal digit (0-9 or A-F). Consequently, the numeric values between 0x5655_3030 (VU00) and 0x5655_4646 (VUFF) are not one contiguous allocation.

These are innermost command IDs. Both MCI and SPDM carry the ID inside AuthorizedCommand; it is not a top-level transport command code. The reference MCU does not implement vendor-specific behavior and returns an unsupported-command error.

Command Format

Common command payloads are defined in Caliptra Common Commands. This section lists the MCI mailbox command code for each common command and keeps mailbox-only command definitions in this document. MCI mailbox checksum, fips_status, and variable-length data_len fields are transport-specific response framing and are not part of the common command payload tables.

MC_AUTHORIZED_COMMAND

Every MCI authorization-related request uses command register value 0x00000012. The first payload dword is always a little-endian target ID. Direct targets carry their operation payload next; family targets carry a second little-endian family subcommand.

Direct: checksum || target_id:u32 || command_payload || authorization_trailer
Family: checksum || family_id:u32 || family_subcommand:u32
        || command_payload || authorization_trailer
MACC:   checksum || 0x4D41_4343:u32

MACC has no command payload or authorization trailer. For signed requests, the preimage is target_id(BE) || signed_payload || nonce; for a family target, the signed payload begins with the family subcommand.

MC_DEVICE_OWNERSHIP_TRANSFER

Native MCU Runtime DOT requests use MCI command register value 0x00000011. Authorized DOT requests use MC_AUTHORIZED_COMMAND with family target 0x00000011.

Native:     checksum || DOT_FourCC || DOT_payload
Authorized: checksum || 0x00000011 || DOT_FourCC
            || DOT_payload || authorization_trailer

The authorized trailer is nonce[48] || ecc_pub_x[48] || ecc_pub_y[48] || mldsa_pub[2592] || HybridSignature. For authorized DOT commands the signed preimage is 0x00000011(BE) || DOT_FourCC(LE) || DOT_payload || nonce.

Payload semantics match Caliptra SPDM VDM DOT commands.

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

MC_FIRMWARE_VERSION

Retrieves the version of the target firmware.

Command Code: 0x4D46_5756 ("MFWV")

Payload semantics are defined by Firmware Version.

MCI mailbox response payload:

MC_DEVICE_CAPABILITIES

Retrieve the device capabilites.

Command Code: 0x4D43_4150 ("MCAP")

Payload semantics are defined by Device Capabilities.

MC_EXPORT_ATTESTED_CSR

Discovers supported Caliptra identity keys or exports an attested Certificate Signing Request (CSR) for a specified device key.

Command Code: 0x4D45_4143 ("MEAC")

Payload semantics are defined by Export Attested CSR.

MC_GET_ATTESTATION

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

Command Code: 0x4D47_4154 ("MGAT")

Payload semantics, the evidence format values, and the format-discovery query are defined by Get Attestation.

MCI mailbox response payload:

MC_GET_LOG

Retrieves the debug log for the MCU Runtime.

Command Code: 0x4D47_4C47 ("MGLG")

Payload semantics and debug log format are defined by Get Debug Log.

MCI mailbox request payload contains only the mailbox checksum header. The command always retrieves the MCU Runtime debug log.

MCI mailbox response payload:

MC_CLEAR_LOG

Clears the debug log in the MCU Runtime.

Command Code: 0x4D43_4C47 ("MCLG")

Payload semantics are defined by Clear Debug Log.

MC_FIPS_PERIODIC_ENABLE

Enables or disables periodic FIPS self-test. When enabled, the MCU runs FIPS self-tests in the background at a configurable interval (default: 60 seconds).

The periodic FIPS commands in this section are available only when MCU Runtime enables the periodic-fips-self-test feature. Builds without that feature report both commands as unsupported.

Command Code: 0x4D46_5045 ("MFPE")

Table: MC_FIPS_PERIODIC_ENABLE input arguments

Table: MC_FIPS_PERIODIC_ENABLE output arguments

MC_FIPS_PERIODIC_STATUS

Retrieves the status of the periodic FIPS self-test, including whether it is enabled, the number of completed iterations, and the result of the last test.

Command Code: 0x4D46_5053 ("MFPS")

Table: MC_FIPS_PERIODIC_STATUS input arguments

Table: MC_FIPS_PERIODIC_STATUS output arguments

MC_ECDSA384_SIG_VERIFY

Command Code: 0x4D45_4356 ("MECV")

Payload format and verification behavior are defined by Caliptra Core ECDSA384_SIGNATURE_VERIFY. MCU Runtime translates the MCI command code to the Caliptra Core command code and forwards the request and response payloads unchanged apart from recalculating their transport checksums.

Successful verification returns fips_status 0x5553_5244 (USRD) because the digest is caller-supplied. An invalid signature completes the MCI mailbox transaction with failure and no response payload.

MC_LMS_SIG_VERIFY

Command Code: 0x4D4C_4D56 ("MLMV")

Payload format, supported LMS parameters, and verification behavior are defined by Caliptra Core LMS_SIGNATURE_VERIFY.

Successful verification returns fips_status 0x5553_5244 (USRD) because the digest is caller-supplied.

MC_PROD_DEBUG_UNLOCK_REQ

Requests debug unlock in production environment.

Command Code: 0x4D50_5552 ("MPUR")

Payload semantics are defined by Request Debug Unlock.

MC_PROD_DEBUG_UNLOCK_TOKEN

Sends the debug unlock token.

Command Code: 0x4D50_5554 ("MPUT")

Payload semantics are defined by Authorize Debug Unlock Token.

MC_GET_AUTH_CMD_CHALLENGE

Authorized target ID: 0x4D41_4343 ("MACC")

Payload semantics are defined by Get Auth Challenge. The MCI request contains no fields after the target ID. The response inserts a zero reserved:u32 between the mailbox response header and the common 48-byte challenge payload.

MC_FUSE_INCREASE_MIN_SVN

Increases the selected minimum SVN.

Authorized target ID: 0x4D43_4D53 ("MCMS")

Payload semantics and target assignments are defined by Fuse Increase Min SVN.

MC_FE_PROG

Programs field entropy for the selected fuse partition.

Authorized target ID: 0x4D43_4650 ("MCFP")

Payload semantics are defined by Program Field Entropy.

MC_VENDOR_PK_HASH_STATUS

Reports occupied vendor public-key hash slots and their PQC key types without requiring authorization. Revoked slots remain occupied because OTP storage cannot be reused.

Command Code: 0x4D56_5053 ("MVPS")

The request contains only the mailbox checksum header. The response contains the standard mailbox response header followed by:

The identifiers in this section are MCU Runtime AuthorizedCommand target IDs, not top-level Runtime mailbox command-register values. Runtime requests use:

MBOX_CMD = 0x00000012
SRAM = checksum || target_id(LE) || operation_payload
       || nonce[48] || ecc_pub_x[48] || ecc_pub_y[48]
       || mldsa_pub[2592] || HybridSignature

The request tables below describe operation_payload; the common checksum, target ID, and authorization trailer are shown once above.

MCU ROM has a separate boot-time direct fuse API for IFPR, IFPW, and IFPK. ROM places that identifier directly in the mailbox command register and uses checksum || operation_payload without the Runtime target field or authorization trailer.

MC_FUSE_READ

Reads fuse values.

Runtime target ID / ROM direct command code: 0x4946_5052 ("IFPR")

Table: MC_FUSE_READ operation payload

Table: MC_FUSE_READ output arguments

MC_FUSE_WRITE

Write fuse values.

Runtime target ID / ROM direct command code: 0x4946_5057 ("IFPW")

Table: MC_FUSE_WRITE operation payload

Table: MC_FUSE_WRITE output arguments

Caveats:

• This command is idempotent, so that identical writes will have no effect.
• Will fail if any of the existing data is 1 but is set to 0 in the input data.
• Bits cleared in mask are ignored
• Writes to buffered partitions will not take effect until the next reset.

MC_FUSE_LOCK_PARTITION

Lock a partition.

Runtime target ID / ROM direct command code: 0x4946_504B ("IFPK")

Table: MC_FUSE_LOCK_PARTITION operation payload

Table: MC_FUSE_LOCK_PARTITION output arguments

Caveats:

• This command is idempotent, so that locking a partition twice has no effect.
• Locking a partition causes subsequent writes to it to fail.
• Locking does not fully take effect until the next reset.

MC_PROVISION_VENDOR_PK_HASH

Provision a new vendor PK hash.

Runtime authorized target ID: 0x5056_504b ("PVPK")

Table: MC_PROVISION_VENDOR_PK_HASH operation payload

Table: MC_PROVISION_VENDOR_PK_HASH output arguments

Caveats:

• Fails if the slot already contains data

MC_PROVISION_OWNER_PK_HASH

Provision CPTRA_SS_OWNER_PK_HASH using its 48-byte dword-reversed OTP representation.

Runtime authorized target ID: 0x504F_504B ("POPK")

Table: MC_PROVISION_OWNER_PK_HASH operation payload

Table: MC_PROVISION_OWNER_PK_HASH output arguments

Caveats:

• The all-zero hash is rejected.
• Reprovisioning the identical hash is idempotent.
• Provisioning a different hash after any owner-hash data has been burned is rejected.
• After verifying the hash, the command burns and verifies bit 0 of CPTRA_SS_OWNER_PK_HASH_VALID for use as a commit marker by ROM versions that enforce it.
• Current MCU ROM does not check CPTRA_SS_OWNER_PK_HASH_VALID before consuming the hash. Provisioning must not be interrupted by reset or power loss; an interruption can cause ROM to consume a partial hash and prevent retrying the intended hash.
• The newly provisioned owner hash is consumed by MCU ROM on the next reset.

MC_FUSE_REVOKE_VENDOR_PUB_KEY

Revoke one vendor firmware verification key within a vendor PK hash slot.

Runtime authorized target ID: 0x4D52_564B ("MRVK")

Table: MC_FUSE_REVOKE_VENDOR_PUB_KEY operation payload

Table: MC_FUSE_REVOKE_VENDOR_PUB_KEY output arguments

Caveats:

• This command must be authorized.
• The selected PK hash slot must be provisioned and valid.
• The command fails if it targets the key used to boot the currently running firmware.
• The last key index for a key type cannot be revoked.

MC_FUSE_REVOKE_VENDOR_PK_HASH

Revoke a vendor PK hash. Marks a vendor PK hash as invalid, revoking all of the associated keys.

Runtime authorized target ID: 0x5256_4b48 ("RVKH")

Table: MC_FUSE_REVOKE_VENDOR_PK_HASH operation payload

Table: MC_FUSE_REVOKE_VENDOR_PK_HASH output arguments

Caveats:

• This command must be authorized.
• This command is idempotent, so that revoking a slot twice has no effect.
• Trying to revoke an empty slot will result in an error
• Trying to revoke the PK hash slot used to boot the currently running firmware will result in an error

Cryptographic Command Format

The MCI mailbox cryptographic commands are mapped to their corresponding Caliptra Mailbox Cryptographic commands. The mapping is detailed in the table below. For the specific format of each command, refer to the Mailbox Commands: Cryptographic Mailbox (2.0).

Table: mapping MCI commands to Caliptra Core commands