| @@ -1,9 +1,9 @@ |
| 1 | 1 | <div style="font-size: 0.85em; color: #656d76; margin-bottom: 1em; padding: 0.5em; background: #f6f8fa; border-radius: 4px;"> |
| 2 | | -📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/e56467181b5313e53cf6cdc92f705a4127480fc2/rom/dev/README.md" target="_blank">chipsalliance/caliptra-sw/rom/dev/README.md</a> @ <code>e564671</code> |
| 2 | +📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/9248d7956e8f6c9514eff3136fa532392d9ac5c1/rom/dev/README.md" target="_blank">chipsalliance/caliptra-sw/rom/dev/README.md</a> @ <code>9248d79</code> |
| 3 | 3 | </div> |
| 4 | 4 | |
| 5 | 5 | |
| 6 | | -# Caliptra - ROM Specification v2.0.1 |
| 6 | +# Caliptra - ROM Specification v2.1 |
| 7 | 7 | |
| 8 | 8 | *Spec Version: 1.0* |
| 9 | 9 | |
| @@ -707,16 +707,16 @@ |
| 707 | 707 | |
| 708 | 708 | #### Handling commands from mailbox |
| 709 | 709 | |
| 710 | | -ROM supports the following set of commands before handling the FW_DOWNLOAD command in PASSIVE mode (described in section 9.6) or RI_DOWNLOAD_FIRMWARE command in SUBSYSTEM mode. Once the FW_DOWNLOAD or RI_DOWNLOAD_FIRMWARE is issued, ROM stops processing any additional mailbox commands. |
| 710 | +ROM supports the following set of commands before handling the FW_DOWNLOAD command in PASSIVE mode (described in section 9.6) or RI_DOWNLOAD_FIRMWARE/RI_DOWNLOAD_ENCRYPTED_FIRMWARE command in SUBSYSTEM mode. Once the FW_DOWNLOAD, RI_DOWNLOAD_FIRMWARE, or RI_DOWNLOAD_ENCRYPTED_FIRMWARE is issued, ROM stops processing any additional mailbox commands. |
| 711 | 711 | |
| 712 | 712 | 1. **STASH_MEASUREMENT**: Up to eight measurements can be sent to the ROM for recording. Sending more than eight measurements will result in an FW_PROC_MAILBOX_STASH_MEASUREMENT_MAX_LIMIT fatal error. Format of a measurement is documented at [Stash Measurement command](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#stash_measurement). |
| 713 | 713 | 2. **VERSION**: Get version info about the module. [Version command](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#version). |
| 714 | 714 | 3. **SELF_TEST_START**: This command is used to invoke the FIPS Known-Answer-Tests (aka KAT) on demand. [Self Test Start command](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#self_test_start). |
| 715 | 715 | 4. **SELF_TEST_GET_RESULTS**: This command is used to check if a SELF_TEST command is in progress. [Self Test Get Results command](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#self_test_get_results). |
| 716 | 716 | 5. **SHUTDOWN**: This command is used clear the hardware crypto blocks including the keyvault. [Shutdown command](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#shutdown). |
| 717 | | -6. **CAPABILITIES**: This command is used to query the ROM capabilities. Capabilities is a 128-bit value with individual bits indicating a specific capability. Currently, the only capability supported is ROM_BASE (bit 0). [Capabilities command](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#capabilities). |
| 717 | +6. **CAPABILITIES**: This command is used to query the ROM capabilities. Capabilities is a 128-bit value with individual bits indicating a specific capability. Capabilities are documented in the [Capabilities command](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#capabilities). |
| 718 | 718 | 7. **GET_IDEVID_CSR**: This command is used to fetch the IDevID CSR from ROM. [Fetch IDevIDCSR command](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#get_idevid_csr). |
| 719 | | -8. **CM_DERIVE_STABLE_KEY**: This command is used to derive a stable key for Device Ownership Transfer or other flows. Note that in Caliptra 2.0 in subsystem mode, derived stable keys, their derivatives, and commands using them will be marked with a FIPS status of invalid since the UDS and FE cannot be completely zeroized. See [CM_DERIVE_STABLE_KEY](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#cm_derive_stable_key). |
| 719 | +8. **CM_DERIVE_STABLE_KEY**: This command is used to derive a stable key for Device Ownership Transfer or other flows. [CM_DERIVE_STABLE_KEY](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#cm_derive_stable_key) |
| 720 | 720 | 9. **CM_HMAC**: This command uses derived stable keys for Device Ownership Transfer or other flows. [CM_HMAC](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#cm_hmac) |
| 721 | 721 | 10. **ECDSA384_SIGNATURE_VERIFY**: This command verifies ECDSA384 signatures for Device Ownership Transfer or other flows. [ECDSA384_SIGNATURE_VERIFY](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#ecdsa384_signature_verify) |
| 722 | 722 | 11. **MLDSA87_SIGNATURE_VERIFY**: This command verifies MLDSA87 signatures for Device Ownership Transfer or other flows. [MLDSA87_SIGNATURE_VERIFY](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#mldsa87_signature_verify) |
| @@ -726,6 +726,45 @@ |
| 726 | 726 | 15. **GET_LDEV_MLDSA87_CERT**: This command fetches an LDevID MLDSA87 certificate signed by the MLDSA87 IDevID private key. [GET_LDEV_MLDSA87_CERT](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime#get_ldev_mldsa87_cert) |
| 727 | 727 | 16. **INSTALL_OWNER_PK_HASH**: This command saves the owner public key hash to persistent data. [INSTALL_OWNER_PK_HASH](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime#install_owner_pk_hash) |
| 728 | 728 | |
| 729 | +17. **ZEROIZE_UDS_FE** |
| 730 | + |
| 731 | +Zeroizes (sets to 0xFFFFFFFF) the UDS (Unique Device Secret) and/or FE (Field Entropy) partitions in the OTP fuse controller. This command is typically used during device decommissioning or ownership transfer flows. |
| 732 | + |
| 733 | +The command accepts a flags field where each bit controls a specific partition. Multiple partitions can be zeroized in a single command by setting multiple flag bits. |
| 734 | + |
| 735 | +The zeroization process follows these steps for each partition: |
| 736 | +1. Clears the zeroization marker first to mask potential ECC errors during power failures |
| 737 | +2. Zeroizes the seed data |
| 738 | +3. Clears the partition digest |
| 739 | + |
| 740 | +All operations are verified to return 0xFFFFFFFF before proceeding. |
| 741 | + |
| 742 | +Command Code: `0x5A45_5546` ("ZEUF") |
| 743 | + |
| 744 | +*Table: `ZEROIZE_UDS_FE` input arguments* |
| 745 | + |
| 746 | +| **Name** | **Type** | **Description** |
| 747 | +| -------- | -------- | --------------- |
| 748 | +| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
| 749 | +| flags | u32 | Partition flags. See ZEROIZE_UDS_FE_FLAGS below. |
| 750 | + |
| 751 | +*Table: `ZEROIZE_UDS_FE_FLAGS` input flags* |
| 752 | + |
| 753 | +| **Name** | **Value** | **Description** |
| 754 | +| ------------------ | --------- | --------------- |
| 755 | +| ZEROIZE_UDS_FLAG | 1 << 0 | Zeroize UDS partition |
| 756 | +| ZEROIZE_FE0_FLAG | 1 << 1 | Zeroize FE partition 0 |
| 757 | +| ZEROIZE_FE1_FLAG | 1 << 2 | Zeroize FE partition 1 |
| 758 | +| ZEROIZE_FE2_FLAG | 1 << 3 | Zeroize FE partition 2 |
| 759 | +| ZEROIZE_FE3_FLAG | 1 << 4 | Zeroize FE partition 3 |
| 760 | + |
| 761 | +*Table: `ZEROIZE_UDS_FE` output arguments* |
| 762 | + |
| 763 | +| **Name** | **Type** | **Description** |
| 764 | +| -------- | -------- | --------------- |
| 765 | +| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
| 766 | +| dpe_result | u32 | Result code, 0 on success. |
| 767 | + |
| 729 | 768 | #### CM_SHA |
| 730 | 769 | |
| 731 | 770 | This ROM-only command computes a SHA-384 or SHA-512 hash of input data in a single one-shot operation. This command is designed for MCU ROM to verify signatures and hashes (e.g., against Vendor PK hash) without requiring its own hash implementation. |
| @@ -740,7 +779,7 @@ |
| 740 | 779 | | -------------- | ------------- | --------------- |
| 741 | 780 | | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
| 742 | 781 | | hash_algorithm | u32 | Hash algorithm: 1 = SHA-384, 2 = SHA-512. Value 0 is reserved and will return an error. |
| 743 | | -| input_size | u32 | Size of input data in bytes. Maximum 262,132 bytes (256 KB minus 12-byte header overhead). |
| 782 | +| input_size | u32 | Size of input data in bytes. Maximum 262,132 bytes (256 KB minus 12-byte header overhead) in passive mode, and 16,372 bytes in subsystem mode for 2.1 (16 KB minus overhead). |
| 744 | 783 | | input | u8[input_size]| Input data to hash. Variable size up to the mailbox capacity. |
| 745 | 784 | |
| 746 | 785 | *Table: `CM_SHA` output arguments* |
| @@ -769,7 +808,11 @@ |
| 769 | 808 | |
| 770 | 809 | Following is the sequence of steps that are performed to download the firmware image into the mailbox in SUBSYSTEM mode. |
| 771 | 810 | |
| 772 | | -1. On receiving the RI_DOWNLOAD_FIRMWARE mailbox command, set the RI PROT_CAP2 register version to 1.1 and the `Agent Capability` field bits: |
| 811 | +ROM supports two commands for firmware download in SUBSYSTEM mode: |
| 812 | +- **RI_DOWNLOAD_FIRMWARE** (Command Code: `0x5249_4644` / "RIFD"): Standard firmware download. After downloading and validating the firmware, the runtime will activate the MCU firmware immediately. |
| 813 | +- **RI_DOWNLOAD_ENCRYPTED_FIRMWARE** (Command Code: `0x5249_4645` / "RIFE"): Encrypted firmware download. Sets the boot mode to `EncryptedFirmware`, which signals to the runtime that the MCU firmware is encrypted and should not be activated until it has been decrypted using the `CM_AES_GCM_DECRYPT_DMA` command. |
| 814 | + |
| 815 | +1. On receiving the RI_DOWNLOAD_FIRMWARE or RI_DOWNLOAD_ENCRYPTED_FIRMWARE mailbox command, set the RI PROT_CAP2 register version to 1.1 and the `Agent Capability` field bits: |
| 773 | 816 | - `Device ID` |
| 774 | 817 | - `Device Status` |
| 775 | 818 | - `Push C-image support` |