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.

• 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

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_DEVICE_OWNERSHIP_TRANSFER

All MCU Runtime DOT requests use MCI command register value 0x00000011. Mailbox SRAM begins with the normal checksum followed by a little-endian DOT FourCC and its payload.

Native:     checksum || DOT_FourCC || DOT_payload
Authorized: checksum || 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

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

Command Code: 0x4D41_4343 ("MACC")

Payload semantics are defined by Get Auth Challenge. The MCI request appends flags:u32 and reserved:u32 after the mailbox checksum header; both fields are reserved and must be zero. The MCI response inserts a zero reserved:u32 between the mailbox response header and the common 48-byte challenge payload.

MC_FUSE_INCREASE_CALIPTRA_MIN_SVN

Increases the minimum bootable Caliptra firmware SVN.

Command Code: 0x4D43_4D53 ("MCMS")

Payload semantics are defined by Fuse Increase Caliptra Min SVN.

MC_FE_PROG

Programs field entropy for the selected fuse partition.

Command Code: 0x4D43_4650 ("MCFP")

Payload semantics are defined by Program Field Entropy.

MC_FUSE_READ

Reads fuse values.

Command Code: 0x4946_5052 ("IFPR")

Table: MC_FUSE_READ input arguments

Table: MC_FUSE_READ output arguments

MC_FUSE_WRITE

Write fuse values.

Command Code: 0x4946_5057 ("IFPW")

Table: MC_FUSE_WRITE input arguments

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 masked with mask will be ignored
• Writes to buffered partitions will not take effect until the next reset.

MC_FUSE_LOCK_PARTITION

Lock a partition.

Command Code: 0x4946_504B ("IFPK")

Table: MC_FUSE_LOCK_PARTITION input arguments

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.

Command Code: 0x5056_504b ("PVPK")

Table: MC_PROVISION_VENDOR_PK_HASH input arguments

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.

Command Code: 0x504F_504B ("POPK")

Table: MC_PROVISION_OWNER_PK_HASH input arguments

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.

Command Code: 0x4D52_564B ("MRVK")

Table: MC_FUSE_REVOKE_VENDOR_PUB_KEY input arguments

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.

Command Code: 0x5256_4b48 ("RVKH")

Table: MC_FUSE_REVOKE_VENDOR_PK_HASH input arguments

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