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_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_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).

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

Verifies an ECDSA P-384 signature. The hash to be verified is taken from the input.

Command Code: 0x4D45_4356 ("MECV")

Table: MC_ECDSA384_SIG_VERIFY input arguments

Table: MC_ECDSA384_SIG_VERIFY output arguments

MC_LMS_SIG_VERIFY

Verifies an LMS signature. The hash to be verified is taken from the input.

Command Code: 0x4D4C_4D56 ("MLMV")

Table: MC_LMS_SIG_VERIFY input arguments

Table: MC_LMS_SIG_VERIFY output arguments

MC_ECDSA384_SIGN

Requests to sign SHA-384 digest with DPE leaf cert.

Command Code: 0x4D45_4353 ("MECS")

Table: MC_ECDSA384_SIGN input arguments

Table: MC_ECDSA384_SIGN output arguments

MC_MLDSA_SIGN

Request to sign the SHA-384 digest with DPE leaf cert.

Command Code: 0x4D4C_4D53 ("MMLS")

Table: MC_MLDSA_SIGN input arguments

Table: MC_MLDSA_SIGN output arguments

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_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_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 Mailbox Crypto Commands to Caliptra Crypto Mailbox Commands