Skip to content

Latest commit

 

History

History

runtime

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
doc
doc
 
 
src
src
 
 
test-fw
test-fw
 
 
tests/runtime_integration_tests
tests/runtime_integration_tests
 
 
Cargo.toml
Cargo.toml
 
 
README.md
README.md
 
 
bloat.sh
bloat.sh
 
 
build.rs
build.rs
 
 
build.sh
build.sh
 
 

README.md

Caliptra Runtime Firmware v1.1

This specification describes the Caliptra Runtime Firmware.

Runtime Firmware environment

This section provides an overview of the Runtime Firmware environment.

Boot and initialization

The Runtime Firmware main function SHALL perform the following on cold boot reset:

For behavior during other types of reset, see Runtime firmware updates.

If Runtime Firmware detects that Caliptra was reset during the execution of an operation, Runtime Firmware calls DISABLE_ATTESTATION because the internal state of Caliptra may be corrupted.

Main loop

After booting, Caliptra Runtime Firmware is responsible for the following.

  • Wait for mailbox interrupts. On mailbox interrupt, Runtime Firmware:
    • Reads command from mailbox
    • Executes command
    • Writes response to mailbox and sets necessary status registers
    • Sleeps until next interrupt
  • On panic, Runtime Firmware:
    • Saves diagnostic information

Callers must wait until Caliptra is no longer busy to call a mailbox command.

Fault handling

A mailbox command can fail to complete in the following ways:

  • Hang or timeout, which result in the watchdog firing
  • Unrecoverable panic

In both of these cases, the panic handler writes diagnostic panic information to registers that are readable by the SoC. Firmware then undergoes an impactless reset.

The caller is expected to check status registers upon reading responses from the mailbox.

Depending on the type of fault, the SoC may:

  • Resubmit the mailbox command
  • Attempt to update Runtime Firmware
  • Perform a full SoC reset
  • Some other SoC-specific behavior

Drivers

Caliptra Runtime Firmware will share driver code with ROM and FMC where possible; however, it will have its own copies of all of these drivers linked into the Runtime Firmware binary.

Maibox commands

All mailbox command codes are little endian.

Table: Mailbox command result codes

Name Value Description
SUCCESS 0x0000_0000 Mailbox command succeeded
BAD_VENDOR_SIG 0x5653_4947 ("VSIG") Vendor signature check failed
BAD_OWNER_SIG 0x4F53_4947 ("OSIG") Owner signature check failed
BAD_SIG 0x4253_4947 ("BSIG") Generic signature check failure (for crypto offload)
BAD_IMAGE 0x4249_4D47 ("BIMG") Malformed input image
BAD_CHKSUM 0x4243_484B ("BCHK") Checksum check failed on input arguments

Relevant registers:

  • mbox_csr -> COMMAND: Command code to execute.
  • mbox_csr -> DLEN: Number of bytes written to mailbox.
  • CPTRA_FW_ERROR_NON_FATAL: Status code of mailbox command. Any result other than SUCCESS signifies a mailbox command failure.

CALIPTRA_FW_LOAD

The CALIPTRA_FW_LOAD command is handled by both ROM and Runtime Firmware.

ROM behavior

On cold boot, ROM exposes the CALIPTRA_FW_LOAD mailbox command to accept the firmware image that ROM will boot. This image includes Manifest, FMC, and Runtime firmware.

Runtime Firmware behavior

Caliptra Runtime Firmware also exposes the CALIPTRA_FW_LOAD mailbox command for loading impactless updates. For more information, see Runtime Firmware updates.

Command Code: 0x4657_4C44 ("FWLD")

Table: CALIPTRA_FW_LOAD input arguments

Name Type Description
data u8[...] Firmware image to load.

CALIPTRA_FW_LOAD returns no output arguments.

CAPABILITIES

Exposes a command to retrieve firmware capabilities

Command Code: 0x4341_5053 ("CAPS")

Table: CAPABILITIES input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: CAPABILITIES output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
capabilities u8[16] Firmware capabilities

GET_IDEV_CERT

Exposes a command to reconstruct the IDEVID CERT.

Command Code: 0x4944_4543 ("IDEC")

Table: GET_IDEV_CERT input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
signature_r u8[48] R portion of signature of the cert.
signature_s u8[48] S portion of signature of the cert.
tbs_size u32 Size of the TBS.
tbs u8[916] TBS, with a maximum size of 916. Only bytes up to tbs_size are used.

Table: GET_IDEV_CERT output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
cert_size u32 Length in bytes of the cert field in use for the IDevId certificate.
cert u8[1024] DER-encoded IDevID CERT.

POPULATE_IDEV_CERT

Exposes a command that allows the SoC to provide a DER-encoded IDevId certificate on every boot. The IDevId certificate is added to the start of the certificate chain.

Command Code: 0x4944_4550 ("IDEP")

Table: POPULATE_IDEV_CERT input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
cert_size u32 Size of the DER-encoded IDevId certificate.
cert u8[1024] DER-encoded IDevID CERT.

Table: POPULATE_IDEV_CERT output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.

GET_IDEV_INFO

Exposes a command to get an IDEVID public key.

Command Code: 0x4944_4549 ("IDEI")

Table: GET_IDEV_INFO input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: GET_IDEV_INFO output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
idev_pub_x u8[48] X portion of ECDSA IDevId key.
idev_pub_y u8[48] Y portion of ECDSA IDevId key.

GET_LDEV_CERT

Exposes a command to get a self-signed LDevID certificate signed by IDevID.

Command Code: 0x4C44_4556 ("LDEV")

Table: GET_LDEV_CERT input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: GET_LDEV_CERT output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
data_size u32 Length in bytes of the valid data in the data field.
data u8[...] DER-encoded LDevID certificate.

GET_FMC_ALIAS_CERT

Exposes a command to get a self-signed FMC alias certificate signed by LDevID.

Command Code: 0x4345_5246 ("CERF")

Table: GET_FMC_ALIAS_CERT input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: GET_FMC_ALIAS_CERT output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
data_size u32 Length in bytes of the valid data in the data field.
data u8[...] DER-encoded FMC alias certificate.

GET_RT_ALIAS_CERT

Exposes a command to get a self-signed Runtime alias certificate signed by the FMC alias.

Command Code: 0x4345_5252 ("CERR")

Table: GET_RT_ALIAS_CERT input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: GET_RT_ALIAS_CERT output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
data_size u32 Length in bytes of the valid data in the data field.
data u8[...] DER-encoded Runtime alias certificate.

ECDSA384_SIGNATURE_VERIFY

Verifies an ECDSA P-384 signature. The hash to be verified is taken from Caliptra's SHA384 accelerator peripheral.

In the event of an invalid signature, the mailbox command will report CMD_FAILURE and the cause will be logged as a non-fatal error.

Command Code: 0x5349_4756 ("SIGV")

Table: ECDSA384_SIGNATURE_VERIFY input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
pub_key_x u8[48] X portion of ECDSA verification key.
pub_key_y u8[48] Y portion of ECDSA verification key.
signature_r u8[48] R portion of signature to verify.
signature_s u8[48] S portion of signature to verify.

Table: ECDSA384_SIGNATURE_VERIFY output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.

LMS_SIGNATURE_VERIFY

Verifies an LMS signature. The hash to be verified is taken from Caliptra's SHA384 accelerator peripheral.

In the event of an invalid signature, the mailbox command will report CMD_FAILURE and the cause will be logged as a non-fatal error.

The supported parameter set is limited to those used for the caliptra image signature: Table: LMS parameters

Param Name Value Description
LMS algorithm type 12 12 = LmsSha256N24H15
LM-OTS algorithm type 7 7 = LmotsSha256N24W4
n 24 Bytes of output from sha256/192 hash function
w 4 Width (in bits) of the Winternitz coefficient
h 15 Height of the tree

Command Code: 0x4C4D_5356 ("LMSV")

Table: LMS_SIGNATURE_VERIFY input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
pub_key_tree_type u8[4] LMS public key algorithm type. Must equal 12.
pub_key_ots_type u8[4] LM-OTS algorithm type. Must equal 7.
pub_key_id u8[16] "I" Private key identifier
pub_key_digest u8[24] "T[1]" Public key hash value
signature_q u8[4] Leaf of the Merkle tree where the OTS public key appears
signature_ots u8[1252] LM-OTS signature
signature_tree_type u8[4] LMS signature Algorithm type. Must equal 12.
signature_tree_path u8[360] Path through the tree from the leaf associated with the LM-OTS signature to the root

Table: LMS_SIGNATURE_VERIFY output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.

STASH_MEASUREMENT

Makes a measurement into the DPE default context. This command is intended for callers who update infrequently and cannot tolerate a changing DPE API surface.

  • Call the DPE DeriveContext command with the DefaultContext in the locality of the PL0 PAUSER.
  • Extend the measurement into PCR31 (PCR_ID_STASH_MEASUREMENT).
  • Note: This command can only be called in the locality of the PL0 PAUSER.

Command Code: 0x4D45_4153 ("MEAS")

Table: STASH_MEASUREMENT input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
metadata u8[4] 4-byte measurement identifier.
measurement u8[48] Data to measure into DPE.
context u8[48] Context field for svn; e.g., a hash of the public key that authenticated the SVN.
svn u32 SVN passed to the DPE to be used in the derived child.

Table: STASH_MEASUREMENT output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
dpe_result u32 Result code of DPE DeriveContext command. Little endian.

DISABLE_ATTESTATION

Disables attestation by erasing the CDI and DICE key. This command is intended for callers who update infrequently and cannot tolerate a changing DPE API surface. It is intended for situations where Caliptra firmware cannot be loaded and the SoC must proceed with boot.

Upon receipt of this command, Caliptra's current CDI is replaced with zeroes, and the associated DICE key is re-derived from the zeroed CDI.

This command is intended to allow the SoC to continue booting for diagnostic and error reporting. All attestations produced in this mode are expected to fail certificate chain validation. Caliptra MUST undergo a cold reset in order to re-enable attestation.

Command Code: 0x4453_424C ("DSBL")

Table: DISABLE_ATTESTATION input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: DISABLE_ATTESTATION output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.

INVOKE_DPE_COMMAND

Invokes a serialized DPE command.

Command Code: 0x4450_4543 ("DPEC")

Table: INVOKE_DPE_COMMAND input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
data_size u32 Length in bytes of the valid data in the data field.
data u8[...] DPE command structure as defined in the DPE iRoT profile.

Table: INVOKE_DPE_COMMAND output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
data_size u32 Length in bytes of the valid data in the data field.
data u8[...] DPE response structure as defined in the DPE iRoT profile.

QUOTE_PCRS

Generates a signed quote over all Caliptra hardware PCRs that are using the Caliptra PCR quoting key. All PCR values are hashed together with the nonce to produce the quote.

Command Code: 0x5043_5251 ("PCRQ")

Table: QUOTE_PCRS input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
nonce u8[32] Caller-supplied nonce to be included in signed data.

PcrValue is defined as u8[48]

Table: QUOTE_PCRS output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
PCRs PcrValue[32] Values of all PCRs.
nonce u8[32] Return the nonce used as input for convenience.
digest u8[48] Return the digest over the PCR values and the nonce.
reset_ctrs u32[32] Reset counters for all PCRs.
signature_r u8[48] R portion of the signature over the PCR quote.
signature_s u8[48] S portion of the signature over the PCR quote.

EXTEND_PCR

Extends a Caliptra hardware PCR.

Command Code: 0x5043_5245 ("PCRE")

Table: EXTEND_PCR input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
index u32 Index of the PCR to extend.
value u8[..] Value to extend into the PCR at index.

Table: EXTEND_PCR output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.

Note that extensions made into Caliptra's PCRs are not appended to Caliptra's internal PCR log.

GET_PCR_LOG

Gets Caliptra's internal PCR log.

Command Code: 0x504C_4F47 ("PLOG")

Table: GET_PCR_LOG input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: GET_PCR_LOG output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
data_size u32 Length in bytes of the valid data in the data field.
data u8[...] Internal PCR event log.

See pcr_log.rs for the format of the log.

Note: the log contents reflect PCR extensions that are made autonomously by Caliptra during boot. The log contents are not preserved across cold or update resets. Callers who wish to verify PCRs that are autonomously extended during update reset should cache the log before triggering an update reset.

INCREMENT_PCR_RESET_COUNTER

Increments the reset counter for a PCR.

Command Code: 0x5043_5252 ("PCRR")

Table: INCREMENT_PCR_RESET_COUNTER input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
index u32 Index of the PCR for which to increment the reset counter.

Table: INCREMENT_PCR_RESET_COUNTER output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.

DPE_TAG_TCI

Associates a unique tag with a DPE context.

Command Code: 0x5451_4754 ("TAGT")

Table: DPE_TAG_TCI input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
handle u8[16] DPE context handle.
tag u32 A unique tag that the handle will be associated with.

Table: DPE_TAG_TCI output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.

DPE_GET_TAGGED_TCI

Retrieves the TCI measurements corresponding to the tagged DPE context.

Command Code: 0x4754_4744 ("GTGD")

Table: DPE_GET_TAGGED_TCI input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
tag u32 A unique tag corresponding to a DPE context.

Table: DPE_GET_TAGGED_TCI output arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
tci_cumulative u8[48] Hash of all of the input data provided to the context.
tci_current u8[48] Most recent measurement made into the context.

FW_INFO

Retrieves information about the current Runtime Firmware, FMC, and ROM.

NOTE: Additional fields and info may be appended to the response in subsequent FW versions.

Command Code: 0x494E_464F ("INFO")

Table: FW_INFO input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: FW_INFO output arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
pl0_pauser u32 PAUSER with PL0 privileges (from image header).
runtime_svn u32 Runtime SVN.
min_runtime_svn u32 Min Runtime SVN.
fmc_manifest_svn u32 FMC SVN.
attestation_disabled u32 State of attestation disable.
rom_revision u8[20] Revision (Git commit ID) of ROM build.
fmc_revision u8[20] Revision (Git commit ID) of FMC build.
runtime_revision u8[20] Revision (Git commit ID) of runtime build.
rom_sha256_digest u32[8] Digest of ROM binary.
fmc_sha384_digest u32[12] Digest of FMC binary.
runtime_sha384_digest u32[12] Digest of runtime binary.
owner_pub_key_hash u32[12] Hash of the owner public keys provided in the image bundle manifest.

VERSION

FIPS command to get version info for the module

Command Code: 0x4650_5652 ("FPVR")

Table: VERSION input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: VERSION output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error
mode u32 Mode identifier
fips_rev u32[3] [31:0] HW rev ID, [47:32] ROM version, [63:48] FMC version, [95:64] FW version
name u8[12] 12 character module name "Caliptra RTM"

SELF_TEST_START

FIPS command to start the self tests

Command Code: 0x4650_4C54

Table: SELF_TEST_START input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: SELF_TEST_START output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error

SELF_TEST_GET_RESULTS

FIPS command to get the results of the self tests. Mailbox command will return a failure if still active.

Command Code: 0x4650_4C67

Table: SELF_TEST_GET_RESULTS input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: SELF_TEST_GET_RESULTS output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error

SHUTDOWN

FIPS command to zeroize and shut down the module

Command Code: 0x4650_5344 ("FPSD")

Table: SHUTDOWN input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: SHUTDOWN output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error

ADD_SUBJECT_ALT_NAME

Provides a subject alternative name otherName. Whenever CERTIFY_KEY_EXTENDED is called with the DMTF_OTHER_NAME flag after ADD_SUBJECT_ALT_NAME is called, the resulting DPE CSR or leaf certificate will contain a subject alternative name extension containing the provided otherName, which must be a DMTF device info. All such certificates produced by CERTIFY_KEY_EXTENDED will continue to have the DMTF otherName subject alternative name extension until reset.

Command Code: 0x414C_544E ("ALTN")

Table: ADD_SUBJECT_ALT_NAME input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
dmtf_device_info_size u32 The size of the DMTF Device Info UTF8String.
dmtf_device_info u8[128] The DMTF Device Info UTF8String.

Table: ADD_SUBJECT_ALT_NAME output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.

CERTIFY_KEY_EXTENDED

Produces a DPE leaf certificate or CSR containing custom extensions provided by the SoC.

Command Code: 0x434B_4558 ("CKEX")

Table: CERTIFY_KEY_EXTENDED input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
certify_key_req u8[72] Certify Key Request.
flags u32 Flags determining which custom extensions to include in the certificate.

Table: CERTIFY_KEY_EXTENDED input flags

Name Offset
DMTF_OTHER_NAME 1 << 31

Table: CERTIFY_KEY_EXTENDED output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
certify_key_resp u8[2176] Certify Key Response.

SET_AUTH_MANIFEST

Command Code: 0x4154_4D4E ("ATMN")

Table: SET_AUTH_MANIFEST input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
manifest size u32 The size of the full Authentication Manifest
preamble_marker u32 Marker needs to be 0x4154_4D4E for the preamble to be valid
preamble_size u32 Size of the preamble
preamble_version u32 Version of the preamble
preamble_flags u32 Manifest flags. See AUTH_MANIFEST_FLAGS below
preamble_vendor_ecc384_key u32[24] Vendor ECC384 key with X and Y coordinates in that order
preamble_vendor_lms_key u32[6] Vendor LMS-SHA192-H15 key
preamble_vendor_ecc384_sig u32[24] Vendor ECC384 signature
preamble_vendor_LMS_sig u32[1344] Vendor LMOTS-SHA192-W4 signature
preamble_owner_ecc384_key u32[24] Owner ECC384 key with X and Y coordinates in that order
preamble_owner_lms_key u32[6] Owner LMS-SHA192-H15 key
preamble_owner_ecc384_sig u32[24] Owner ECC384 signature
preamble_owner_LMS_sig u32[1344] Owner LMOTS-SHA192-W4 signature
metadata_vendor_ecc384_sig u32[24] Metadata Vendor ECC384 signature
metadata_vendor_LMS_sig u32[1344] Metadata Vendor LMOTS-SHA192-W4 signature
metadata_owner_ecc384_sig u32[24] Metadata Owner ECC384 signature
metadata_owner_LMS_sig u32[1344] Metadata Owner LMOTS-SHA192-W4 signature
metadata_entry_entry_count u32 number of metadata entries
metadata_entries Metadata[127] The max number of metadata entries is 127 but less can be used

Table: AUTH_MANIFEST_FLAGS input flags

Name Value
VENDOR_SIGNATURE_REQUIRED 1 << 0

Table: AUTH_MANIFEST_METADATA_ENTRY digest entries

Name Type Description
fw_id u32 Id of the image
flags u32 See METADATA_ENTRY_FLAGS below
digest u32[48] Digest of the image

Table: METADATA_ENTRY_FLAGS input flags

Name Size (Bits) Description
image_source 2 1: InRequest
ignore_auth_check 1 If set, the image digest is not compared for the firmware id

Table: SET_AUTH_MANIFEST output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.

AUTHORIZE_AND_STASH

Command Code: 0x4154_5348 ("ATSH")

Table: AUTHORIZE_AND_STASH input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.
fw_id u8[4] Firmware id of the image, in little-endian format
measurement u8[48] Digest of the image requested for authorization
context u8[48] Context field for svn; e.g., a hash of the public key that authenticated the SVN.
svn u32 SVN
flags u32 See AUTHORIZE_AND_STASH_FLAGS below
source u32 Enumeration values: { InRequest(1), ShaAcc (2) }

Table: AUTHORIZE_AND_STASH_FLAGS input flags

Name Value
SKIP_STASH 1 << 0

Table: AUTHORIZE_AND_STASH output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
fips_status u32 Indicates if the command is FIPS approved or an error.
auth_req_result u32 AUTHORIZE_IMAGE (0xDEADC0DE), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB)

GET_IDEVID_CSR

Command Code: 0x4944_4352 ("IDCR")

Table: GET_IDEVID_CSR input arguments

Name Type Description
chksum u32 Checksum over other input arguments, computed by the caller. Little endian.

Table: GET_IDEVID_CSR output arguments

Name Type Description
chksum u32 Checksum over other output arguments, computed by Caliptra. Little endian.
data_size u32 Length in bytes of the valid data in the data field.
data u8[...] DER-encoded IDevID certificate signing request.

The mfg_flag_gen_idev_id_csr manufacturing flag MUST have been set to generate a CSR.

When called from ROM, if the CSR was not previously provisioned this command will return FW_PROC_MAILBOX_UNPROVISIONED_CSR(0x0102000A).

When called from runtime, if the CSR was not previously provisioned this command will return RUNTIME_GET_IDEV_ID_UNPROVISIONED(0x000E0051). If the ROM did not support CSR generation, this command will return RUNTIME_GET_IDEV_ID_UNSUPPORTED_ROM(0x000E0052).

When the mfg_flag_gen_idev_id_csr flag has been set, the SoC MUST wait for the flow_status_set_idevid_csr_ready bit to be set by Caliptra. Once set, the SoC MUST clear the mfg_flag_gen_idev_id_csr flag for Caliptra to progress.

Checksum

For every command except for FW_LOAD, the request and response feature a checksum. This mitigates glitches between clients and Caliptra.

The checksum is a little-endian 32-bit value, defined as:

0 - (SUM(command code bytes) + SUM(request/response bytes))

The sum of all bytes in a request/response body, and command code, should be zero.

If Caliptra detects an invalid checksum in input parameters, it returns BAD_CHKSUM as the result.

Caliptra also computes a checksum over all of the responses and writes it to the chksum field.

FIPS status

For every command, the firmware responds with a FIPS status of FIPS approved. There is currently no use case for any other responses or error values.

Table: FIPS status codes

Name Value Description
FIPS_APPROVED 0x0000_0000 Status of command is FIPS approved
RESERVED 0x0000_0001 - 0xFFFF_FFFF Other values reserved, will not be sent by Caliptra

Runtime Firmware updates

Caliptra Runtime Firmware accepts impactless updates that update Caliptra’s firmware without resetting other cores in the SoC.

Applying updates

A Runtime Firmware update is triggered by the CALIPTRA_FW_LOAD command. Upon receiving this command, Runtime Firmware does the following:

  1. Locks the mailbox to writes
  2. Invokes impactless reset

After impactless reset is invoked, FMC loads the hash of the image from the verified Manifest into the necessary PCRs:

  1. Runtime Journey PCR
  2. Runtime Latest PCR

If ROM validation of the image fails:

  • ROM SHALL NOT clear the Runtime Latest PCR. It SHALL still re-lock this PCR with the existing value.
  • FMC SHALL NOT extend either of the Runtime PCRs.

Boot process after update

After an impactless update is applied, the new Runtime Firmware is able to sample a register to determine if it has undergone an Impactless Reset. In this case, the new Runtime Firmware must:

  1. Validate DPE state in SRAM
    1. Ensure the TCI tree is well-formed
    2. Ensure all nodes chain to the root (TYPE = RTJM, “Internal TCI” flag is set)
  2. Verify that the “Latest TCI” field of the TCI Node that contains the Runtime Journey PCR (TYPE = RTJM, “Internal TCI” flag is set) matches the “Latest” Runtime PCR value from PCRX
    1. Ensure SHA384_HASH(0x00..00, TCI from SRAM) == RT_FW_JOURNEY_PCR
  3. Check that retired and inactive contexts do not have tags
  4. If any validations fail, Runtime Firmware executes the DISABLE_ATTESTATION command

DICE Protection Environment (DPE)

Caliptra Runtime Firmware SHALL implement a profile of the DICE Protection Environment (DPE) API.

PAUSER privilege levels

Caliptra uses PAUSER as a HW mechanism to distinguish DPE Client localities. Caliptra models PAUSER callers to its mailbox as having 1 of 2 privilege levels:

  • PL0 - High privilege. Only 1 PAUSER in the SoC may be at PL0. The PL0 PAUSER is denoted in the signed Caliptra firmware image. The PL0 PAUSER may call any supported DPE commands. Only PL0 can use the CertifyKey command. Success of the CertifyKey command signifies to the caller that it is at PL0. Only PL0 can use the POPULATE_IDEV_CERT mailbox command.
  • PL1 - Restricted privilege. All other PAUSERs in the SoC are PL1. Caliptra SHALL fail any calls to the DPE CertifyKey with format=X509 by PL1 callers. PL1 callers should use the CSR format instead.

PAUSER and Locality map 1:1. Consequently, only the single DPE Client associated with PL0 level, is authorized to invoke CertifyKey DPE command with format=x509. All other DPE Clients have instead restricted privileges associated to PL1 (as described above).

PAUSER privilege level active context limits

Each active context in DPE is activated from either PL0 or PL1 through the InvokeDpe mailbox command calling the DeriveContext or InitializeContext DPE commands. However, a caller could easily exhaust space in DPE's context array by repeatedly calling the aforementioned DPE commands with certain flags set.

To prevent this, we establish active context limits for each PAUSER privilege level:

  • PL0 - 16 active contexts
  • PL1 - 16 active contexts

If a DPE command were to activate a new context such that the total number of active contexts in a privilege level is above its active context limit, the InvokeDpe command should fail.

At boot Caliptra Runtime FW consumes part of the PL0 active contexts (initially 16) to DeriveContext for:

  • RTFW Journey (RTFJ) Measurement (1)
  • Mailbox Valid Pauser digest (MBVP) (1)
  • ROM Stashed Measurements (max 8)

Further, it is not allowed for PL1 to call DeriveContext with the intent to change locality to PL0's locality; this would increase the number of active contexts in PL0's locality, and hence allow PL1 to DOS PL0.

DPE profile implementation

The DPE iRoT profile leaves some choices up to implementers. This section describes specific requirements for the Caliptra DPE implementation.

Name Value Description
Profile Variant DPE_PROFILE_IROT_P384_SHA384 The profile variant that Caliptra implements.
KDF SP800-108 HMAC-CTR KDF to use for CDI (tcg.derive.kdf-sha384) and asymmetric key (tcg.derive.kdf-sha384-p384) derivation.
Simulation Context Support Yes Whether Caliptra implements the optional Simulation Contexts feature.
Supports ExtendTci Yes Whether Caliptra implements the optional ExtendTci command.
Supports Auto Init Yes Whether Caliptra will automatically initialize the default DPE context.
Supports Rotate Context Yes Whether Caliptra supports the optional RotateContextHandle command.
CertifyKey Alias Key Caliptra Runtime Alias Key The key that will be used to sign certificates that are produced by the DPE CertifyKey command.

Supported DPE commands

Caliptra DPE supports the following commands:

  • GetProfile
  • InitializeContext
  • DeriveContext
  • CertifyKey
    • Caliptra DPE supports two formats for CertifyKey: X.509 and PKCS#10 CSR. X.509 is only available to PL0 PAUSERs.
  • Sign
  • RotateContextHandle
  • DestroyContext
  • GetCertificateChain

DPE state atomicity

This implementation guarantees that no internal DPE state is changed if a command fails for any reason. This includes context handle rotation; single-use context handles are not rotated if a command fails.

On failure, DPE only returns a command header, with no additional command-specific response parameters. This is in line with the CBOR-based main DPE spec, which does not return a response payload on failure.

Initializing DPE

Caliptra Runtime Firmware is responsible for initializing DPE’s default context.

  • Runtime Firmware SHALL initialize the default context in “internal-cdi” mode.
  • Perform the following initial measurements:
    • Call DeriveContext with Caliptra Journey PCR
      • INPUT_DATA = PCRX (RT journey PCR as defined in the FHT)
      • TYPE = “RTJM”
      • CONTEXT_HANDLE = default context
      • TARGET_LOCALITY = Caliptra locality (0xFFFFFFFF)
    • Call DeriveContext with mailbox valid PAUSERS
    • Call DeriveContext for each STASH_MEASUREMENT call made during Caliptra ROM execution
      • INPUT_DATA = measurement parameter to STASH_MEASUREMENT
      • TYPE = type parameter to STASH_MEASUREMENT
      • CONTEXT_HANDLE = default context
      • TARGET_LOCALITY = PL0 PAUSER

CDI derivation

The DPE Sign and CertifyKey commands derive an asymmetric key for that handle.

DPE first collects measurements and concatenates them in a byte buffer, MEASUREMENT_DATA:

  • LABEL parameter passed to Sign or CertifyKey.
  • The TCI_NODE_DATA structures in the path from the current TCI node to the root, inclusive, starting with the current node.

To derive a CDI for a given context, DPE shall use KeyVault hardware with the following inputs:

  • CDI = Runtime Firmware CDI (from KeyVault)
  • Label = LABEL parameter provided to Sign or CertifyKey
  • Context = MEASUREMENT_DATA

The CDI shall be loaded into KeyVault slot 8.

Leaf key derivation

To derive an asymmetric key for Sign and CertifyKey, Runtime Firmware does the following:

  • Derives an ECC P384 keypair from KV slot 8 CDI into KV slot 9
  • For CertifyKey: Requests the public key
  • For Sign: Signs passed data
  • Erases KeyVault slots 8 and 9

Internal representation of TCI nodes

Byte offset Bits Name Description
0x00 383:0 TCI_CURRENT Current TCI measurement value
0x30 383:0 TCI_CUMULATIVE TCI measurement value
0x60 31:0 TYPE TYPE parameter to the DeriveContext call that created this node
0x64 31:0 LOCALITY TARGET_LOCALITY parameter to the DeriveContext call that created this node (PAUSER)

Certificate generation

The DPE Runtime Alias Key SHALL sign DPE leaf certificates and CSRs.

The DPE GET_CERTIFICATE_CHAIN command shall return the following certificates:

  • IDevID (optionally added by the SoC via POPULATE_IDEV_CERT)
  • LDevID
  • FMC Alias
  • Runtime Alias

DPE leaf certificate definition

Field Sub field Value
Version v3 2
Serial Number First 20 bytes of sha256 hash of DPE Alias public key
Issuer Name CN Caliptra Runtime Alias
serialNumber First 20 bytes of sha384 hash of Runtime Alias public key
Validity notBefore notBefore from firmware manifest
notAfter notAfter from firmware manifest
Subject Name CN Caliptra DPE Leaf
serialNumber SHA384 hash of Subject public key
Subject Public Key Info Algorithm ecdsa-with-SHA384
Parameters Named Curve = prime384v1
Public Key DPE Alias Public Key value
Signature Algorithm Identifier Algorithm ecdsa-with-SHA384
Parameters Named Curve = prime384v1
Signature Value Digital signature for the certificate
KeyUsage keyCertSign 1
Basic Constraints CA False
Policy OIDs id-tcg-kp-attestLoc
tcg-dice-MultiTcbInfo* FWIDs [0] "Journey" TCI Value
[1] "Current" TCI Value. Latest INPUT_DATA made by DeriveContext.
Type 4-byte TYPE field of TCI node
VendorInfo Locality of the caller (analog for PAUSER)

*MultiTcbInfo contains one TcbInfo for each TCI Node in the path from the current TCI Node to the root. Max of 32.