| @@ -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/88512eb6b83b7503625cd319668d30dc3bff6012/rom/dev/README.md" target="_blank">chipsalliance/caliptra-sw/rom/dev/README.md</a> @ <code>88512eb</code> |
| 2 | +📄 Source: <a href="https://github.com/chipsalliance/caliptra-sw/blob/7f309f2a7f90971caf698c6ba76275642f3923c4/rom/dev/README.md" target="_blank">chipsalliance/caliptra-sw/rom/dev/README.md</a> @ <code>7f309f2</code> |
| 3 | 3 | </div> |
| 4 | 4 | |
| 5 | 5 | |
| 6 | | -# Caliptra - ROM Specification v2.0.2 |
| 6 | +# Caliptra - ROM Specification v2.1 |
| 7 | 7 | |
| 8 | 8 | *Spec Version: 1.0* |
| 9 | 9 | |
| @@ -59,23 +59,28 @@ |
| 59 | 59 | ### Fuse Registers |
| 60 | 60 | | Register | Width (bits) | Description | |
| 61 | 61 | | :------------------------------ | :------------ | :----------------------------------------------------- | |
| 62 | | -| FUSE_UDS_SEED | 512 | Obfuscated UDS | |
| 63 | | -| FUSE_FIELD_ENTROPY | 256 | Obfuscated Field Entropy | |
| 64 | | -| FUSE_VENDOR_PK_HASH | 384 | Hash of the ECC and LMS or MLDSA Manufacturer Public Key Descriptors | |
| 62 | +| FUSE_UDS_SEED | 512 | Obfuscated UDS. Stored as `[u32; 16]` — see [Fuse value byte ordering](#fuse-value-byte-ordering). | |
| 63 | +| FUSE_FIELD_ENTROPY | 256 | Obfuscated Field Entropy. Stored as `[u32; 8]` — see [Fuse value byte ordering](#fuse-value-byte-ordering). | |
| 64 | +| FUSE_VENDOR_PK_HASH | 384 | Hash of the ECC and LMS or MLDSA Manufacturer Public Key Descriptors. Stored as `[u32; 12]` — see [Public key hash byte ordering](#public-key-hash-byte-ordering-dword-reversal). | |
| 65 | 65 | | FUSE_ECC_REVOCATION | 4 | Manufacturer ECC Public Key Revocation Mask | |
| 66 | 66 | | FUSE_LMS_REVOCATION | 32 | Manufacturer LMS Public Key Revocation Mask | |
| 67 | 67 | | FUSE_MLDSA_REVOCATION | 4 | Manufacturer MLDSA Public Key Revocation Mask | |
| 68 | | -| FUSE_FIRMWARE_SVN | 128 | Firmware Security Version Number | |
| 68 | +| FUSE_FIRMWARE_SVN | 128 | Firmware Security Version Number. 128-bit bitmap — see [Fuse value byte ordering](#fuse-value-byte-ordering). | |
| 69 | 69 | | FUSE_ANTI_ROLLBACK_DISABLE | 1 | Disable SVN checking for firmware when bit is set | |
| 70 | | -| FUSE_IDEVID_CERT_ATTR | 768 | FUSE containing information for generating IDEVID CSR <br> **Word 0:bits[0-2]**: ECDSA X509 Key Id Algorithm (3 bits) 0: SHA1, 1: SHA256, 2: SHA384, 3: SHA512, 4: Fuse <br> **Word 0:bits[3-5]**: MLDSA X509 Key Id Algorithm (3 bits) 0: SHA1, 1: SHA256, 2: SHA384, 3: SHA512, 4: Fuse <br> **Word 1,2,3,4,5**: ECDSA Subject Key Id <br> **Word 6,7,8,9,10**: MLDSA Subject Key Id <br> **Words 11**: UEID type as defined in [IETF RATS specification](https://www.ietf.org/archive/id/draft-ietf-rats-eat-21.html#section-4.2.1.1) <br> **Words 12,13,14,15**: Manufacturer Serial Number | |
| 71 | | -| FUSE_MANUF_DEBUG_UNLOCK_TOKEN | 512 | SHA-512 digest of secret value for manufacturing debug unlock authorization | |
| 70 | +| FUSE_IDEVID_CERT_ATTR | 768 | FUSE containing information for generating IDEVID CSR <br> **Word 0:bits[0-2]**: ECDSA X509 Key Id Algorithm (3 bits) 0: SHA1, 1: SHA256, 2: SHA384, 3: SHA512, 4: Fuse <br> **Word 0:bits[3-5]**: MLDSA X509 Key Id Algorithm (3 bits) 0: SHA1, 1: SHA256, 2: SHA384, 3: SHA512, 4: Fuse <br> **Word 1,2,3,4,5**: ECDSA Subject Key Id <br> **Word 6,7,8,9,10**: MLDSA Subject Key Id <br> **Words 11**: UEID type as defined in the [IETF EAT specification](https://www.rfc-editor.org/rfc/rfc9711.html#section-4.2.1.1) <br> **Words 12,13,14,15**: Manufacturer Serial Number | |
| 71 | +| FUSE_MANUF_DEBUG_UNLOCK_TOKEN | 512 | SHA-512 digest of secret value for manufacturing debug unlock authorization. Stored as `[u32; 16]` — see [Fuse value byte ordering](#fuse-value-byte-ordering). | |
| 72 | 72 | | FUSE_PQC_KEY_TYPE | 2 | One-hot encoded selection of PQC key type for firmware validation. <br> **Bit 0**: MLDSA <br> **Bit 1**: LMS | |
| 73 | +| FUSE_HEK_SEED | 256 | OCP HEK Seed. Stored as `[u32; 8]` — see [Fuse value byte ordering](#fuse-value-byte-ordering). | |
| 74 | +| FUSE_SOC_MANIFEST_SVN | 128 | SoC Manifest Security Version Number. 128-bit bitmap — see [Fuse value byte ordering](#fuse-value-byte-ordering). | |
| 75 | +| FUSE_SOC_MANIFEST_MAX_SVN | 8 | Maximum SoC Manifest Security Version Number | |
| 76 | +| FUSE_SOC_STEPPING_ID | 16 | SoC Stepping Identifier | |
| 77 | +| FUSE_IDEVID_MANUF_HSM_ID | 128 | Manufacturer HSM Identifier. Stored as `[u32; 4]` — see [Fuse value byte ordering](#fuse-value-byte-ordering). | |
| 73 | 78 | |
| 74 | 79 | |
| 75 | 80 | ### Architectural Registers |
| 76 | 81 | | Register | Width (bits) | Description | |
| 77 | 82 | | :------------------------------ | :------------ | :----------------------------------------------------- | |
| 78 | | -| CPTRA_OWNER_PK_HASH | 384 | Owner ECC and LMS or MLDSA Public Key Hash | |
| 83 | +| CPTRA_OWNER_PK_HASH | 384 | Owner ECC and LMS or MLDSA Public Key Hash. Stored as `[u32; 12]` — see [Public key hash byte ordering](#public-key-hash-byte-ordering-dword-reversal). | |
| 79 | 84 | |
| 80 | 85 | |
| 81 | 86 | ### Entropy Source Configuration Registers |
| @@ -84,19 +89,40 @@ |
| 84 | 89 | |
| 85 | 90 | | Register | Field/Bits | Description | |
| 86 | 91 | | :------------------------------- | :------------ | :------------------------------------------------------ | |
| 87 | | -| SS_STRAP_GENERIC[2] | [15:0] | Health test window size for FIPS mode (default: 512). This is the window size for all health tests when entropy is tested in FIPS mode. | |
| 92 | +| SS_STRAP_GENERIC[2] | [15:0] | Health test window size for FIPS mode (default: 1024). This is the window size for all health tests when entropy is tested in FIPS mode. In single-bit mode entropy_src internally tests four times this many samples on the selected lane. | |
| 93 | +| SS_STRAP_GENERIC[2] | [16] | Entropy source single-bit mode. When set to 1, ROM enables `rng_bit_enable` and clears `threshold_scope`. | |
| 94 | +| SS_STRAP_GENERIC[2] | [18:17] | Entropy source single-bit mode `rng_bit_sel`. Selects which RNG bit stream to process when single-bit mode is enabled. | |
| 88 | 95 | | SS_STRAP_GENERIC[2] | [31] | Entropy bypass mode. When set to 1, enables bypass mode (`es_type`) to allow entropy characterization directly without passing through conditioning. | |
| 89 | | -| CPTRA_I_TRNG_ENTROPY_CONFIG_0 | [15:0] | Adaptive Proportion test high threshold (default: 1536). The test fails if any window has more than this threshold of 1's. | |
| 90 | | -| CPTRA_I_TRNG_ENTROPY_CONFIG_0 | [31:16] | Adaptive Proportion test low threshold (default: 512). The test fails if any window has less than this threshold of 1's. | |
| 96 | +| CPTRA_I_TRNG_ENTROPY_CONFIG_0 | [15:0] | Adaptive Proportion test high threshold (default: 75% of the FIPS window, i.e. 768 for the default window). The test fails if any window has more than this threshold of 1's. | |
| 97 | +| CPTRA_I_TRNG_ENTROPY_CONFIG_0 | [31:16] | Adaptive Proportion test low threshold (default: 25% of the FIPS window, i.e. 256 for the default window). The test fails if any window has less than this threshold of 1's. | |
| 91 | 98 | | CPTRA_I_TRNG_ENTROPY_CONFIG_1 | [15:0] | Repetition Count test threshold (default: 41). The test fails if an RNG wire repeats the same bit this many times in a row. | |
| 92 | 99 | | CPTRA_I_TRNG_ENTROPY_CONFIG_1 | [31:16] | Alert threshold (default: 2). Number of health check failures before an alert is triggered. | |
| 93 | 100 | |
| 94 | 101 | |
| 95 | 102 | **Notes:** |
| 96 | 103 | - If any threshold value is set to 0, the ROM uses the default value specified above. |
| 104 | +- The Adaptive Proportion default thresholds are derived from the FIPS window (75% high, 25% low). In single-bit mode entropy_src scales the health-test window by four, so when the default window is used the ROM scales these defaults to match (high: 3072, low: 1024). An explicit threshold or window supplied by the SoC is used as-is. |
| 97 | 105 | - These configuration values are stored in persistent storage after first read to prevent malicious modification (reloaded on cold reset). |
| 98 | 106 | - In debug mode (`debug_locked == false`), entropy source configuration registers remain unlocked for characterization. |
| 99 | 107 | - In production mode, ROM locks the entropy source configuration after programming to prevent modification. |
| 108 | + |
| 109 | +### Stable Owner Key Root Derivation |
| 110 | + |
| 111 | +The Stable Owner Key feature is only available in subsystem mode when OCP LOCK is disabled and the following subsystem strap is set: |
| 112 | + |
| 113 | +| Register | Field/Bits | Description | |
| 114 | +| :------------------------------- | :--------- | :------------------------------------------------------ | |
| 115 | +| SS_STRAP_GENERIC[3] | [0] | Stable Owner Key enable. When set to 1, ROM derives the Stable Owner Root Key from the HEK seed and allows `CM_DERIVE_STABLE_KEY` with `key_type = OwnerKey` when the other availability requirements are met. When clear, Stable Owner Key derivation is disabled. | |
| 116 | + |
| 117 | + |
| 118 | +When the feature is available, ROM derives the Stable Owner Root Key during the IDevID stage before clearing DOE secrets: |
| 119 | + |
| 120 | +1. DOE decrypts the obfuscated HEK seed into `KEY_ID_HEK_SEED` (`KeyId14`) with HMAC block usage. |
| 121 | +2. HKDF-Extract uses HMAC-SHA512 with salt `stable_owner_root_key`, zero-padded to 64 bytes, and reads `KEY_ID_HEK_SEED` as HMAC block data. The resulting PRK overwrites `KEY_ID_HEK_SEED` with HMAC key usage. |
| 122 | +3. HKDF-Expand uses HMAC-SHA512 with the PRK and label `stable_owner_root_key` to populate `KEY_ID_STABLE_OWNER` (`KeyId15`) with AES key usage. |
| 123 | +4. ROM write-locks `KEY_ID_STABLE_OWNER` and erases the temporary `KEY_ID_HEK_SEED` slot. |
| 124 | + |
| 125 | +If subsystem mode is not active, the strap is clear, or OCP LOCK is enabled, ROM skips this derivation and `CM_DERIVE_STABLE_KEY` with `key_type = OwnerKey` is unavailable. |
| 100 | 126 | |
| 101 | 127 | For a comprehensive overview of the SOC interface registers, please refer to the following link:: |
| 102 | 128 | https://chipsalliance.github.io/caliptra-rtl/main/external-regs/?p=caliptra_top_reg.generic_and_fuse_reg |
| @@ -159,7 +185,7 @@ |
| 159 | 185 | | Key Descriptor Version | 2 | Version of the Key Descriptor. The value must be 0x1 for Caliptra 2.x | |
| 160 | 186 | | Reserved | 1 | Reserved | |
| 161 | 187 | | Key Hash Count | 1 | Number of valid public key hashes | |
| 162 | | -| Public Key Hash(es) | 48 * n | List of valid and invalid (if any) SHA2-384 public key hashes. ECDSA: n = 4 | |
| 188 | +| Public Key Hash(es) | 48 * n | List of valid and invalid (if any) SHA2-384 public key hashes. ECDSA: n = 4. Each hash is stored in reversed-dword format (see [Public key hash byte ordering](#public-key-hash-byte-ordering-dword-reversal)). | |
| 163 | 189 | |
| 164 | 190 | |
| 165 | 191 | #### PQC Manufacturer Public Key Descriptor |
| @@ -169,7 +195,7 @@ |
| 169 | 195 | | Key Descriptor Version | 2 | Version of the Key Descriptor. The value must be 0x1 for Caliptra 2.x | |
| 170 | 196 | | Key Type | 1 | Type of the key in the descriptor <br> 0x1 - MLDSA <br> 0x3 - LMS | |
| 171 | 197 | | Key Hash Count | 1 | Number of valid public key hashes | |
| 172 | | -| Public Key Hash(es) | 48 * n | List of valid and invalid (if any) SHA2-384 public key hashes. LMS: n = 32, MLDSA: n = 4 | |
| 198 | +| Public Key Hash(es) | 48 * n | List of valid and invalid (if any) SHA2-384 public key hashes. n = 32 for both LMS and MLDSA (the struct always allocates 32 slots; for MLDSA only the first 4 are populated and the rest are zero). Each hash is stored in reversed-dword format (see [Public key hash byte ordering](#public-key-hash-byte-ordering-dword-reversal)). | |
| 173 | 199 | |
| 174 | 200 | |
| 175 | 201 | #### Header |
| @@ -292,11 +318,12 @@ |
| 292 | 318 | 3. ROM then retrieves the UDS granularity from the `CPTRA_GENERIC_INPUT_WIRES` register0 Bit31 to learn if the fuse row is accessible with 32-bit or 64-bit granularity. If the bit is reset, it indicates 64-bit granularity; otherwise, it indicates 32-bit granularity. |
| 293 | 319 | |
| 294 | 320 | 4. ROM computes the following values: |
| 295 | | - - DAI_IDLE bit offset: (`SS_STRAP_GENERIC` register0 >> 16) & 0xFFFF |
| 296 | | - - `DIRECT_ACCESS_CMD` offset: (`SS_STRAP_GENERIC` register1) & 0xFFFF + Fuse Controller's base address. |
| 321 | + - `STATUS` register address: Fuse Controller's base address + ((`SS_STRAP_GENERIC` register0) & 0xFFFF). |
| 322 | + - DAI_IDLE bit index within the `STATUS` register: (`SS_STRAP_GENERIC` register0 >> 16) & 0xFFFF. |
| 323 | + - `DIRECT_ACCESS_CMD` register address: Fuse Controller's base address + ((`SS_STRAP_GENERIC` register1) & 0xFFFF). |
| 297 | 324 | |
| 298 | 325 | 4. ROM then performs the following steps until all the 512 bits of the UDS seed are programmed: |
| 299 | | - 1. The ROM verifies the idle state of the DAI by reading the `STATUS` register `DAI_IDLE` bit (offset retrieved above) of the Fuse Controller, located at offset 0x10 from the Fuse Controller's base address. |
| 326 | + 1. The ROM verifies the idle state of the DAI by reading the `STATUS` register `DAI_IDLE` bit using the offset retrieved above. |
| 300 | 327 | 2. If the granularity is 32-bit, the ROM writes the next word from the UDS seed to the `DIRECT_ACCESS_WDATA_0` register. If the granularity is 64-bit, the ROM writes the next two words to `the DIRECT_ACCESS_WDATA_0` and `DIRECT_ACCESS_WDATA_1` registers, located at offsets 0x8 and 0xC respectively from the `DIRECT_ACCESS_CMD` register. |
| 301 | 328 | 3. The ROM writes the lower 32 bits of the UDS Seed programming base address to the `DIRECT_ACCESS_ADDRESS` register, located at offset 0x4 from the `DIRECT_ACCESS_CMD` register. |
| 302 | 329 | 4. The ROM triggers the UDS seed write command by writing 0x2 to the `DIRECT_ACCESS_CMD` register.. |
| @@ -380,10 +407,10 @@ |
| 380 | 407 | | Unlock Level | 1 | Debug unlock Level (Number 1-8). | |
| 381 | 408 | | Reserved | 3 | Reserved field. | |
| 382 | 409 | | Challenge | 48 | Random number sent in `AUTH_DEBUG_UNLOCK_CHALLENGE` mailbox command payload. | |
| 383 | | -| ECC Public Key | 96 | ECC P-384 public key used to verify the Message Signature <br> **X-Coordinate:** Public Key X-Coordinate (48 bytes, big endian) <br> **Y-Coordinate:** Public Key Y-Coordinate (48 bytes, big endian) | |
| 384 | | -| MLDSA Public Key | 2592 | MLDSA-87 public key used to verify the Message Signature. | |
| 385 | | -| ECC Signature | 96 | ECC P-384 signature of the Message hashed using SHA2-384. <br> **R-Coordinate:** Random Point (48 bytes) <br> **S-Coordinate:** Proof (48 bytes). | |
| 386 | | -| MLDSA Signature | 4628 | MLDSA signature of the Message hashed using SHA2-512. (4627 bytes + 1 Reserved byte). | |
| 410 | +| ECC Public Key | 96 | ECC P-384 public key used to verify the Message Signature <br> **X-Coordinate:** Public Key X-Coordinate (48 bytes) <br> **Y-Coordinate:** Public Key Y-Coordinate (48 bytes). See [Byte order of cryptographic fields](../../runtime/README.md#byte-order-of-cryptographic-fields). | |
| 411 | +| MLDSA Public Key | 2592 | MLDSA-87 public key used to verify the Message Signature. See [Byte order of cryptographic fields](../../runtime/README.md#byte-order-of-cryptographic-fields). | |
| 412 | +| ECC Signature | 96 | ECC P-384 signature of the Message hashed using SHA2-384. <br> **R-Coordinate:** Random Point (48 bytes) <br> **S-Coordinate:** Proof (48 bytes). See [Byte order of cryptographic fields](../../runtime/README.md#byte-order-of-cryptographic-fields). | |
| 413 | +| MLDSA Signature | 4628 | MLDSA-87 signature of the Message hashed using SHA2-512 (4627 bytes + 1 Reserved byte). See [Byte order of cryptographic fields](../../runtime/README.md#byte-order-of-cryptographic-fields). | |
| 387 | 414 | |
| 388 | 415 | |
| 389 | 416 | 7. On receiving this payload, ROM performs the following validations: |
| @@ -392,7 +419,7 @@ |
| 392 | 419 | - Calculates the address of the public key hash fuse as follows: <br> |
| 393 | 420 | **SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK_OFFSET register value + ( (Debug Unlock Level - 1) * SHA2-384 hash size (48 bytes) )** |
| 394 | 421 | - Retrieves the SHA2-384 hash (48 bytes) from the calculated address using DMA assist. |
| 395 | | - - Computes the SHA2-384 hash of the message formed by concatenating the ECC and MLDSA public keys in the payload. |
| 422 | + - Computes the SHA2-384 hash of the message formed by concatenating the ECC and MLDSA public keys in the payload. See [Production debug unlock public key hashes: byte ordering](#production-debug-unlock-public-key-hashes-byte-ordering) for the exact byte order and fuse programming details. |
| 396 | 423 | - Compares the retrieved and computed hashes. It the comparison fails, the ROM blocks the debug unlock request by setting the registers outlined in step 3. |
| 397 | 424 | - Upon hash comparison failure, the ROM exits the payload validation flow and completes the mailbox command. |
| 398 | 425 | |
| @@ -422,6 +449,7 @@ |
| 422 | 449 | - SHA2-384 |
| 423 | 450 | - SHA2-512 |
| 424 | 451 | - SHA2-512-ACC |
| 452 | + - CSRNG (CTR_DRBG-AES-256) |
| 425 | 453 | - ECC-384 |
| 426 | 454 | - ECDH |
| 427 | 455 | - HMAC-384Kdf |
| @@ -589,6 +617,105 @@ |
| 589 | 617 | | 🔒IDevID MLDSA Pub Key | |
| 590 | 618 | |
| 591 | 619 | |
| 620 | +#### UEID (Unique Endpoint Identifier) |
| 621 | + |
| 622 | +The UEID is a 17-byte identifier that is embedded (as an X.509 extension) in the |
| 623 | +IDevID CSR, the LDevID certificate, and the FMC Alias certificate. Its value is |
| 624 | +derived entirely from fuses. |
| 625 | + |
| 626 | +##### Source fuses |
| 627 | + |
| 628 | +The UEID is assembled from 5 consecutive 32-bit words of the |
| 629 | +`FUSE_IDEVID_CERT_ATTR` fuse bank (see the [Fuse Registers](#fuse-registers) |
| 630 | +table): |
| 631 | + |
| 632 | +| Fuse word | `IdevidCertAttr` variant | Usage in UEID | |
| 633 | +| ----------- | ------------------------------- | ----------------------------------------- | |
| 634 | +| 11 | `UeidType` | UEID type byte (see RFC 9711 §4.2.1.1) | |
| 635 | +| 12 | `ManufacturerSerialNumber1` | First 4 bytes of the endpoint serial | |
| 636 | +| 13 | `ManufacturerSerialNumber2` | Next 4 bytes of the endpoint serial | |
| 637 | +| 14 | `ManufacturerSerialNumber3` | Next 4 bytes of the endpoint serial | |
| 638 | +| 15 | `ManufacturerSerialNumber4` | Last 4 bytes of the endpoint serial | |
| 639 | + |
| 640 | + |
| 641 | +Only the low byte of word 11 is used; the high 3 bytes of that word are |
| 642 | +discarded. Each of the four serial-number words is written to the UEID buffer |
| 643 | +in **little-endian** order (the natural byte order of the u32 register). |
| 644 | + |
| 645 | +##### Byte layout |
| 646 | + |
| 647 | +``` |
| 648 | + byte 0 byte 1 ─ byte 4 byte 5 ─ byte 8 byte 9 ─ byte 12 byte 13 ─ byte 16 |
| 649 | + ┌──────────┐ ┌────────────────┐ ┌────────────────┐ ┌─────────────────┐ ┌─────────────────┐ |
| 650 | + │ UeidType │ │ MfgSerialNum1 │ │ MfgSerialNum2 │ │ MfgSerialNum3 │ │ MfgSerialNum4 │ |
| 651 | + │ (byte 0) │ │ (LE u32) │ │ (LE u32) │ │ (LE u32) │ │ (LE u32) │ |
| 652 | + └──────────┘ └────────────────┘ └────────────────┘ └─────────────────┘ └─────────────────┘ |
| 653 | +``` |
| 654 | + |
| 655 | +This assembly is implemented in `caliptra_drivers::FuseBank::ueid` in |
| 656 | +`drivers/src/fuse_bank.rs`, returning a `[u8; 17]`. |
| 657 | + |
| 658 | +##### Placement in the certificate / CSR |
| 659 | + |
| 660 | +The 17-byte UEID is placed in the TCG DICE "Ueid" X.509 extension (OID |
| 661 | +`2.23.133.5.4.4`, not marked critical). The extension's `extnValue` |
| 662 | +`OCTET STRING` contains a DER-encoded `SEQUENCE { ueid OCTET STRING }`, as |
| 663 | +defined by the TCG DICE specification. The DER bytes written into the TBS |
| 664 | +template are: |
| 665 | + |
| 666 | +| DER bytes | Meaning | |
| 667 | +| --------------------------- | --------------------------------------------------------- | |
| 668 | +| `30 1F` | `SEQUENCE`, length 31 — the `Extension` | |
| 669 | +| `06 06 67 81 05 05 04 04` | `OID 2.23.133.5.4.4` (`tcg-dice-Ueid`) | |
| 670 | +| `04 15` | `OCTET STRING`, length 21 — the `extnValue` wrapper | |
| 671 | +| `30 13` | inner `SEQUENCE`, length 19 — the `TcgUeid` structure | |
| 672 | +| `04 11` | inner `OCTET STRING`, length 17 — the UEID value | |
| 673 | +| `XX XX … XX` (17 B) | the 17 UEID bytes assembled above | |
| 674 | + |
| 675 | + |
| 676 | +The template slot for the 17 UEID bytes sits at a fixed offset in the TBS |
| 677 | +template (e.g. `UEID_OFFSET = 312` for `InitDevIdCsrTbsEcc384`); the ROM copies |
| 678 | +the UEID returned by `FuseBank::ueid` directly into that slot with no further |
| 679 | +transformation. See `x509/gen/src/x509.rs::make_tcg_ueid_ext` for the generator |
| 680 | +and `x509/build/*` for the resulting pre-baked templates. |
| 681 | + |
| 682 | +##### End-to-end example |
| 683 | + |
| 684 | +Given the following example fuse values (as programmed by the integration test |
| 685 | +`cert_test_with_ueid` in `rom/dev/tests/rom_integration_tests/test_image_validation.rs`): |
| 686 | + |
| 687 | +| Fuse word | Field | Value | |
| 688 | +| ----------- | -------------------------------- | --------------- | |
| 689 | +| 11 | `UeidType` | `0x0000_0001` | |
| 690 | +| 12 | `ManufacturerSerialNumber1` | `0x0403_0201` | |
| 691 | +| 13 | `ManufacturerSerialNumber2` | `0x0807_0605` | |
| 692 | +| 14 | `ManufacturerSerialNumber3` | `0x0C0B_0A09` | |
| 693 | +| 15 | `ManufacturerSerialNumber4` | `0x100F_0E0D` | |
| 694 | + |
| 695 | + |
| 696 | +Step-by-step: |
| 697 | + |
| 698 | +1. `FuseBank::ueid` reads the five fuse words and takes the low byte of word 11: |
| 699 | + `ueid_type = 0x01`. |
| 700 | +2. Each serial-number word is converted to little-endian bytes: |
| 701 | + - `0x04030201 → 01 02 03 04` |
| 702 | + - `0x08070605 → 05 06 07 08` |
| 703 | + - `0x0C0B0A09 → 09 0A 0B 0C` |
| 704 | + - `0x100F0E0D → 0D 0E 0F 10` |
| 705 | +3. The 17-byte UEID is: |
| 706 | + `01 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10` |
| 707 | + (byte 0 is the type; bytes 1–16 are the endpoint serial). |
| 708 | +4. The UEID is wrapped in the DER framing shown above and emitted verbatim in |
| 709 | + the IDevID CSR, LDevID certificate, and FMC Alias certificate. The resulting |
| 710 | + bytes on the wire for the Ueid extension are: |
| 711 | + `30 1F 06 06 67 81 05 05 04 04 04 15 30 13 04 11 01 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10`. |
| 712 | + |
| 713 | +The `cert_test_with_ueid` test programs exactly these fuses, boots the ROM, |
| 714 | +retrieves the IDevID ECC CSR, LDevID cert, and FMC Alias cert from the UART |
| 715 | +log, and asserts that the hex-encoded bytes |
| 716 | +`010102030405060708090A0B0C0D0E0F10` appear in all three — confirming both the |
| 717 | +fuse-to-UEID assembly and the DER placement described here. |
| 718 | + |
| 592 | 719 | ### Local Device ID DICE layer |
| 593 | 720 | |
| 594 | 721 | Local Device ID Layer derives the Owner CDI, ECC and MLDSA Keys. This layer represents the owner DICE Identity as it is mixed with the Field Entropy programmed by the Owner. |
| @@ -707,24 +834,63 @@ |
| 707 | 834 | |
| 708 | 835 | #### Handling commands from mailbox |
| 709 | 836 | |
| 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. |
| 711 | | - |
| 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 | | -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 | | -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 | | -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 | | -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). |
| 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). |
| 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 | | -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 | | -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) |
| 723 | | -12. **CM_RANDOM_GENERATE**: This command returns random numbers from Caliptra's RNG for Device Ownership Transfer or other flows. [CM_RANDOM_GENERATE](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#cm_random_generate) |
| 837 | +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. |
| 838 | + |
| 839 | +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/runtime/README.md#stash_measurement). |
| 840 | +2. **VERSION**: Get version info about the module. [Version command](https://github.com/chipsalliance/caliptra-sw/blob/main/runtime/README.md#version). |
| 841 | +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/runtime/README.md#self_test_start). |
| 842 | +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/runtime/README.md#self_test_get_results). |
| 843 | +5. **SHUTDOWN**: This command is used clear the hardware crypto blocks including the keyvault. [Shutdown command](https://github.com/chipsalliance/caliptra-sw/blob/main/runtime/README.md#shutdown). |
| 844 | +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/runtime/README.md#capabilities). |
| 845 | +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/runtime/README.md#get_idevid_csr). |
| 846 | +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/runtime/README.md#cm_derive_stable_key) |
| 847 | +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/runtime/README.md#cm_hmac) |
| 848 | +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/runtime/README.md#ecdsa384_signature_verify) |
| 849 | +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/runtime/README.md#mldsa87_signature_verify) |
| 850 | +12. **CM_RANDOM_GENERATE**: This command returns random numbers from Caliptra's RNG for Device Ownership Transfer or other flows. [CM_RANDOM_GENERATE](https://github.com/chipsalliance/caliptra-sw/blob/main/runtime/README.md#cm_random_generate) |
| 724 | 851 | 13. **CM_SHA**: This ROM-only command (ROM 2.0.1+ only) computes a SHA-384 or SHA-512 hash of input data in a single operation. This is useful for MCU ROM to verify signatures and hashes against Vendor PK hash without needing its own hash implementation. Unlike the runtime CM_SHA_INIT/CM_SHA_UPDATE/CM_SHA_FINAL commands, this is a one-shot operation that does not support streaming or contexts. See [CM_SHA](#cm_sha) below for details. |
| 725 | | -14. **GET_LDEV_ECC384_CERT**: This command fetches an LDevID ECC384 certificate signed by the ECC384 IDevID private key. [GET_LDEV_ECC384_CERT](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime#get_ldev_ecc384_cert) |
| 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 | | -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) |
| 852 | +14. **GET_LDEV_ECC384_CERT**: This command fetches an LDevID ECC384 certificate signed by the ECC384 IDevID private key. [GET_LDEV_ECC384_CERT](https://github.com/chipsalliance/caliptra-sw/blob/main/runtime#get_ldev_ecc384_cert) |
| 853 | +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/runtime#get_ldev_mldsa87_cert) |
| 854 | +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/runtime#install_owner_pk_hash) |
| 855 | +17. **OCP_LOCK_REPORT_HEK_METADATA**: This command allows the MCU to report HEK seed state and metadata to the ROM, which determines if the HEK is available. See the [OCP LOCK specification](https://github.com/chipsalliance/Caliptra/blob/main/doc/ocp_lock/releases/OCP_LOCK_Specification_v1.0_RC2.pdf) for details. |
| 856 | +18. **ZEROIZE_UDS_FE** |
| 857 | + |
| 858 | +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. |
| 859 | + |
| 860 | +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. |
| 861 | + |
| 862 | +The zeroization process follows these steps for each partition: |
| 863 | +1. Clears the zeroization marker first to mask potential ECC errors during power failures |
| 864 | +2. Zeroizes the seed data |
| 865 | +3. Clears the partition digest |
| 866 | + |
| 867 | +All operations are verified to return 0xFFFFFFFF before proceeding. |
| 868 | + |
| 869 | +Command Code: `0x5A45_5546` ("ZEUF") |
| 870 | + |
| 871 | +*Table: `ZEROIZE_UDS_FE` input arguments* |
| 872 | + |
| 873 | +| **Name** | **Type** | **Description** |
| 874 | +| -------- | -------- | --------------- |
| 875 | +| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
| 876 | +| flags | u32 | Partition flags. See ZEROIZE_UDS_FE_FLAGS below. |
| 877 | + |
| 878 | +*Table: `ZEROIZE_UDS_FE_FLAGS` input flags* |
| 879 | + |
| 880 | +| **Name** | **Value** | **Description** |
| 881 | +| ------------------ | --------- | --------------- |
| 882 | +| ZEROIZE_UDS_FLAG | 1 << 0 | Zeroize UDS partition |
| 883 | +| ZEROIZE_FE0_FLAG | 1 << 1 | Zeroize FE partition 0 |
| 884 | +| ZEROIZE_FE1_FLAG | 1 << 2 | Zeroize FE partition 1 |
| 885 | +| ZEROIZE_FE2_FLAG | 1 << 3 | Zeroize FE partition 2 |
| 886 | +| ZEROIZE_FE3_FLAG | 1 << 4 | Zeroize FE partition 3 |
| 887 | + |
| 888 | +*Table: `ZEROIZE_UDS_FE` output arguments* |
| 889 | + |
| 890 | +| **Name** | **Type** | **Description** |
| 891 | +| -------- | -------- | --------------- |
| 892 | +| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. |
| 893 | +| dpe_result | u32 | Result code, 0 on success. |
| 728 | 894 | |
| 729 | 895 | #### CM_SHA |
| 730 | 896 | |
| @@ -740,7 +906,7 @@ |
| 740 | 906 | | -------------- | ------------- | --------------- |
| 741 | 907 | | chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. |
| 742 | 908 | | 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). |
| 909 | +| input_size | u32 | Size of input data in bytes. Maximum 16,372 bytes in subsystem mode (16 KB minus 12-byte header overhead). Passive mode supports up to 262,132 bytes (256 KB minus overhead) when using a passive-mode mailbox. |
| 744 | 910 | | input | u8[input_size]| Input data to hash. Variable size up to the mailbox capacity. |
| 745 | 911 | |
| 746 | 912 | *Table: `CM_SHA` output arguments* |
| @@ -769,7 +935,11 @@ |
| 769 | 935 | |
| 770 | 936 | Following is the sequence of steps that are performed to download the firmware image into the mailbox in SUBSYSTEM mode. |
| 771 | 937 | |
| 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: |
| 938 | +ROM supports two commands for firmware download in SUBSYSTEM mode: |
| 939 | +- **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. |
| 940 | +- **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. |
| 941 | + |
| 942 | +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 | 943 | - `Device ID` |
| 774 | 944 | - `Device Status` |
| 775 | 945 | - `Push C-image support` |
| @@ -1023,7 +1193,7 @@ |
| 1023 | 1193 | - **ICCM** |
| 1024 | 1194 | |
| 1025 | 1195 | ### Launch FMC |
| 1026 | | -The ROM initializes and populates the Firmware Handoff Table (FHT) to relay essential parameters to the FMC. The format of the FHT is documented [here](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/fmc/README.md#firmware-handoff-table). Upon successful population, the ROM transfers execution control to the FMC. |
| 1196 | +The ROM initializes and populates the Firmware Handoff Table (FHT) to relay essential parameters to the FMC. The format of the FHT is documented [here](https://github.com/chipsalliance/caliptra-sw/blob/main/fmc/README.md#firmware-handoff-table). Upon successful population, the ROM transfers execution control to the FMC. |
| 1027 | 1197 | |
| 1028 | 1198 | ## Warm reset flow |
| 1029 | 1199 | ROM does not perform any DICE derivations or firmware validation during warm reset. |
| @@ -1136,11 +1306,12 @@ |
| 1136 | 1306 | ### Preamble validation: Manufacturing key validation |
| 1137 | 1307 | |
| 1138 | 1308 | - fuse_ecc_revocation serves as the bitmask for revoking ECC keys. |
| 1139 | | - - If bit-n is set, the nth key is disabled. All other higher bits that are zeros indicate the keys are still enabled. |
| 1309 | + - If bit-n is set, the nth key is disabled. All other bits that are zeros indicate the keys are still enabled. |
| 1140 | 1310 | - If all the bits are zeros, all ECC keys remain enabled. |
| 1141 | 1311 | - Ensure that the Active Key Index in the preamble is not disabled by the fuse_ecc_revocation fuse. |
| 1142 | 1312 | - If the key is disabled, the validation process fails. |
| 1143 | | -- Repeat the above procedure for LMS or MLDSA keys using the fuse_lms_revocation or fuse_mldsa_revocation fuses, respectively, for key revocation. |
| 1313 | + - **Note: The last key index is never revoked, regardless of the fuse value.** |
| 1314 | +- Repeat the above procedure for LMS or MLDSA keys using the fuse_lms_revocation or fuse_mldsa_revocation fuses, respectively, for key revocation. The last key index for PQC keys is also never revoked. |
| 1144 | 1315 | |
| 1145 | 1316 | ### Preamble validation: Validate the Owner key |
| 1146 | 1317 | |
| @@ -1149,6 +1320,755 @@ |
| 1149 | 1320 | - The validation process for owner public keys involves generating a SHA2-384 hash from the owner public keys within the preamble and comparing it to the hash stored in the fuse_owner_pk_hash register. |
| 1150 | 1321 | - If the computed hash matches the value in fuse_owner_pk_hash, the owner public keys are deemed valid. |
| 1151 | 1322 | - If there is a hash mismatch, the image validation process fails. |
| 1323 | + |
| 1324 | +### Public key hash byte ordering (dword reversal) |
| 1325 | + |
| 1326 | +**Important:** Hashes and ECC key coordinates stored in the firmware manifest and fuse registers use |
| 1327 | +a **reversed-dword format** rather than the standard byte order defined by the SHA specification. |
| 1328 | + |
| 1329 | +In standard byte order, a SHA2-384 hash is a sequence of 48 bytes exactly as output by tools like |
| 1330 | +OpenSSL or Python's `hashlib`. In reversed-dword format, the same 48 bytes are grouped into 12 |
| 1331 | +four-byte words (dwords) and the bytes within each dword are reversed. |
| 1332 | + |
| 1333 | +For example, if the standard SHA2-384 hash begins with `b1 7c a8 77 66 66 57 cc d1 00 e6 92 ...`: |
| 1334 | + |
| 1335 | +| Standard byte order | → | Reversed-dword format | |
| 1336 | +| ---------------------- | --- | ----------------------- | |
| 1337 | +| `b1 7c a8 77` || `77 a8 7c b1` | |
| 1338 | +| `66 66 57 cc` || `cc 57 66 66` | |
| 1339 | +| `d1 00 e6 92` || `92 e6 00 d1` | |
| 1340 | +| ... || ... | |
| 1341 | + |
| 1342 | + |
| 1343 | +This reversed-dword format applies to: |
| 1344 | +- **Individual public key hashes** in the ECC and PQC key descriptors within the preamble |
| 1345 | +- **FUSE_VENDOR_PK_HASH** and **CPTRA_OWNER_PK_HASH** fuse/register values (which are `[u32; 12]` arrays) |
| 1346 | +- **ECC public key coordinates** (X and Y), which are stored as `[u32; 12]` arrays in the preamble |
| 1347 | + |
| 1348 | +Note: LMS public key fields (`tree_type`, `otstype`, `id`, `digest`) follow the LMS specification |
| 1349 | +encoding and are **not** subject to dword reversal. MLDSA public keys are stored as raw byte arrays |
| 1350 | +and are also **not** subject to dword reversal. |
| 1351 | + |
| 1352 | +For a detailed description of byte ordering conventions for all mailbox cryptographic fields |
| 1353 | +(including ECC, ML-DSA, and SHA digest fields with OpenSSL examples), see the |
| 1354 | +[Byte order of cryptographic fields](../../runtime/README.md#byte-order-of-cryptographic-fields) |
| 1355 | +section in the Runtime README. |
| 1356 | + |
| 1357 | +### Computing public key hashes: step-by-step example |
| 1358 | + |
| 1359 | +The following example walks through the computation of the **vendor PK descriptor hash** |
| 1360 | +using the test public keys from `image/fake-keys/src/lib.rs` with PQC key type **LMS (type 3)**. |
| 1361 | + |
| 1362 | +#### Step 1: Hash each vendor ECC public key |
| 1363 | + |
| 1364 | +Each ECC-384 public key has X and Y coordinates, each stored as `[u32; 12]`. To hash a key, |
| 1365 | +serialize the struct to 96 bytes by writing each `u32` word in reversed-dword format, then |
| 1366 | +compute SHA2-384 of those 96 bytes. |
| 1367 | + |
| 1368 | +**ECC Key 0:** |
| 1369 | +``` |
| 1370 | +X (standard byte order): c69fe67f 97ea3e42 21a7a603 6c2e070d 1657327b c3f1e7c1 |
| 1371 | + 8dccb9e4 ffda5c3f 4db0a1c0 567e0973 17bf4484 39696a07 |
| 1372 | +Y (standard byte order): c126b913 5fc82572 8f1cd403 19109430 994fe3e8 74a8b026 |
| 1373 | + be14794d 27789964 7735fde8 328afd84 cd4d4aa8 72d40b42 |
| 1374 | + |
| 1375 | +X (reversed-dword): 7fe69fc6 423eea97 03a6a721 0d072e6c 7b325716 c1e7f1c3 |
| 1376 | + e4b9cc8d 3f5cdaff c0a1b04d 73097e56 8444bf17 076a6939 |
| 1377 | +Y (reversed-dword): 13b926c1 7225c85f 03d41c8f 30941019 e8e34f99 26b0a874 |
| 1378 | + 4d7914be 64997827 e8fd3577 84fd8a32 a84a4dcd 420bd472 |
| 1379 | + |
| 1380 | +Input to SHA384 = X_reversed || Y_reversed (96 bytes) |
| 1381 | +SHA384 (standard): 84facd34 227de869 1fbb7d33 49306e0f 250a3659 53a6cc6b |
| 1382 | + 629d4616 32f73cfd 768152bb 8a03a255 5a1b1f1f c3923faa |
| 1383 | +SHA384 (reversed-dword): 34cdfa84 69e87d22 337dbb1f 0f6e3049 59360a25 6bcca653 |
| 1384 | + 16469d62 fd3cf732 bb528176 55a2038a 1f1f1b5a aa3f92c3 |
| 1385 | +``` |
| 1386 | + |
| 1387 | +**ECC Key 1:** |
| 1388 | +``` |
| 1389 | +X (standard): a6309750 f0a05ddb 956a7f86 2812ec4f ec454e95 3b53dbfb |
| 1390 | + 9eb54140 15ea7507 084af93c b7fa33fe 51811ad5 e754232e |
| 1391 | +Y (standard): ef5a5987 7a0ce0be 2621d2a9 8bf3c5df af7b3d6d 97f24183 |
| 1392 | + a4a42038 58c39b86 272ef548 e572b937 1ecf1994 1b8d4ea7 |
| 1393 | + |
| 1394 | +SHA384 (standard): fe89195f 7fab8ebb 2818d935 837493c2 378525ef 686ed220 |
| 1395 | + 09b9a399 f23f1f42 2f5ae1f3 ba1c3083 1a68a456 9c01fc96 |
| 1396 | +SHA384 (reversed-dword): 5f1989fe bb8eab7f 35d91828 c2937483 ef258537 20d26e68 |
| 1397 | + 99a3b909 421f3ff2 f3e15a2f 83301cba 56a4681a 96fc019c |
| 1398 | +``` |
| 1399 | + |
| 1400 | +**ECC Key 2:** |
| 1401 | +``` |
| 1402 | +X (standard): a0d25693 c4251e48 185615b0 a6c27f6d e62c39f5 a9a32f75 |
| 1403 | + 9553226a 4d1926c1 7928910f b7adc1b6 89996733 10134881 |
| 1404 | +Y (standard): bbdf72d7 07c08100 d54fcdad b1567bb0 0522762b 76b8dc4a |
| 1405 | + 846c175a 3fbd0501 9bdc8118 4be5f33c bb21b41d 93a8c523 |
| 1406 | + |
| 1407 | +SHA384 (standard): f397ba45 b5801ddf b732078d ffdf792f b584a73f b055acaf |
| 1408 | + ef39f31d 5b88c7d5 2753a45a 0c76b098 90d8e335 7be87f26 |
| 1409 | +SHA384 (reversed-dword): 45ba97f3 df1d80b5 8d0732b7 2f79dfff 3fa784b5 afac55b0 |
| 1410 | + 1df339ef d5c7885b 5aa45327 98b0760c 35e3d890 267fe87b |
| 1411 | +``` |
| 1412 | + |
| 1413 | +**ECC Key 3:** |
| 1414 | +``` |
| 1415 | +X (standard): 002a82b6 8e03e9a0 fd3b4c14 ca2cb3e8 14350a71 0e43956d |
| 1416 | + 21694fb4 f34485e8 f0e33583 f7ea142d 50e16f8b 0225bb95 |
| 1417 | +Y (standard): 5802641c 7c45a4a2 408e03a6 a4100a92 50fcc468 d238cd0d |
| 1418 | + 449cc3e5 1abc25e7 0b05c426 843dcd6f 944ef6ff fa53ec5b |
| 1419 | + |
| 1420 | +SHA384 (standard): 8ba8acb6 b98da9dc 8ffce0bc eba86454 4acbbd6e 3f31466e |
| 1421 | + 5d532565 0bfc9e3b c8afb2b5 c33e20f5 06992143 83f33bc1 |
| 1422 | +SHA384 (reversed-dword): b6aca88b dca98db9 bce0fc8f 5464a8eb 6ebdcb4a 6e46313f |
| 1423 | + 6525535d 3b9efc0b b5b2afc8 f5203ec3 43219906 c13bf383 |
| 1424 | +``` |
| 1425 | + |
| 1426 | +#### Step 2: Hash each vendor LMS public key |
| 1427 | + |
| 1428 | +Each LMS public key is a 48-byte struct: `tree_type` (u32), `otstype` (u32), `id` (16 bytes), |
| 1429 | +`digest` (24 bytes). The binary serialization is hashed directly. |
| 1430 | + |
| 1431 | +**LMS Key 0:** |
| 1432 | +``` |
| 1433 | +tree_type=0x0000000c, otstype=0x00000007 |
| 1434 | +id: 4908a17b cadb1829 1e289058 d5a8e3e8 |
| 1435 | +digest: 64ad3eb8 be6864f1 7ccda38b de35edaa 6c0da527 645407c6 |
| 1436 | + |
| 1437 | +Serialized (48 bytes): 0000000c 00000007 4908a17b cadb1829 1e289058 d5a8e3e8 |
| 1438 | + 64ad3eb8 be6864f1 7ccda38b de35edaa 6c0da527 645407c6 |
| 1439 | +SHA384 (standard): fc2c1b6f 56f732d1 fd876f3f ef757cbb a2b1c64b cc148298 |
| 1440 | + d7508262 4bdf27cb 23d6b5b6 7169c46f 50b7fc19 92068fec |
| 1441 | +SHA384 (reversed-dword): 6f1b2cfc d132f756 3f6f87fd bb7c75ef 4bc6b1a2 988214cc |
| 1442 | + 628250d7 cb27df4b b6b5d623 6fc46971 19fcb750 ec8f0692 |
| 1443 | +``` |
| 1444 | + |
| 1445 | +**LMS Key 1:** |
| 1446 | +``` |
| 1447 | +tree_type=0x0000000c, otstype=0x00000007 |
| 1448 | +id: 7cb5369d 64e4281d 046e977c 70d4d0a3 |
| 1449 | +digest: 8ea4701d adf7d700 0564b7d6 1d1c9587 9dd6475c 9c3aae0b |
| 1450 | + |
| 1451 | +SHA384 (standard): 7b5811fd 8d2b0cf8 9851f12d d2a7c239 f4f3abc5 d928dcc0 |
| 1452 | + 3b4b891d abbdc67f c7b88436 432e1544 a408bc9c bb503f6b |
| 1453 | +SHA384 (reversed-dword): fd11587b f80c2b8d 2df15198 39c2a7d2 c5abf3f4 c0dc28d9 |
| 1454 | + 1d894b3b 7fc6bdab 3684b8c7 44152e43 9cbc08a4 6b3f50bb |
| 1455 | +``` |
| 1456 | + |
| 1457 | +**LMS Key 2:** |
| 1458 | +``` |
| 1459 | +tree_type=0x0000000c, otstype=0x00000007 |
| 1460 | +id: 2bbb4b72 c5b41e05 d2fabe76 f41704bd |
| 1461 | +digest: dcb53f96 24d4c7b3 c9ae4d4c 0e41e08e 3b159396 0fe6a277 |
| 1462 | + |
| 1463 | +SHA384 (standard): 7e08a494 6933d35a 42c0d7b0 0236b10b db14c100 3f82f6a9 |
| 1464 | + 7d401cb8 e420a7fa 5aab12b3 c4e96bec 49aec770 225a8f88 |
| 1465 | +SHA384 (reversed-dword): 94a4087e 5ad33369 b0d7c042 0bb13602 00c114db a9f6823f |
| 1466 | + b81c407d faa720e4 b312ab5a ec6be9c4 70c7ae49 888f5a22 |
| 1467 | +``` |
| 1468 | + |
| 1469 | +**LMS Key 3:** |
| 1470 | +``` |
| 1471 | +tree_type=0x0000000c, otstype=0x00000007 |
| 1472 | +id: 42cba2e5 575b5235 7ea7aead ef54074c |
| 1473 | +digest: 5aa60e27 69251599 3ae8e21f 27ccdded 8ffcd3d2 8efbdec2 |
| 1474 | + |
| 1475 | +SHA384 (standard): d3734fbc ee2893a3 b1b6519b 6ec78fb8 d7425327 cde1f7aa |
| 1476 | + 23012c64 c635219f d4ab1c4d 1b023252 00042884 2e463dbb |
| 1477 | +SHA384 (reversed-dword): bc4f73d3 a39328ee 9b51b6b1 b88fc76e 275342d7 aaf7e1cd |
| 1478 | + 642c0123 9f2135c6 4d1cabd4 5232021b 84280400 bb3d462e |
| 1479 | +``` |
| 1480 | + |
| 1481 | +#### Step 3: Build the ECC key descriptor (196 bytes) |
| 1482 | + |
| 1483 | +Concatenate the 4-byte header with the 4 key hashes (each in reversed-dword format): |
| 1484 | + |
| 1485 | +``` |
| 1486 | +Header (4 bytes): 01 00 00 04 (version=1, reserved=0, key_hash_count=4) |
| 1487 | +ECC key 0 hash (48 bytes, reversed-dword): 34cdfa84 69e87d22 ... aa3f92c3 |
| 1488 | +ECC key 1 hash (48 bytes, reversed-dword): 5f1989fe bb8eab7f ... 96fc019c |
| 1489 | +ECC key 2 hash (48 bytes, reversed-dword): 45ba97f3 df1d80b5 ... 267fe87b |
| 1490 | +ECC key 3 hash (48 bytes, reversed-dword): b6aca88b dca98db9 ... c13bf383 |
| 1491 | + |
| 1492 | +Total: 4 + (4 × 48) = 196 bytes |
| 1493 | +``` |
| 1494 | + |
| 1495 | +#### Step 4: Build the PQC (LMS) key descriptor (1540 bytes) |
| 1496 | + |
| 1497 | +``` |
| 1498 | +Header (4 bytes): 01 00 03 20 (version=1, key_type=3=LMS, key_hash_count=32) |
| 1499 | +LMS key 0 hash (48 bytes, reversed-dword): 6f1b2cfc d132f756 ... ec8f0692 |
| 1500 | +LMS key 1 hash (48 bytes, reversed-dword): fd11587b f80c2b8d ... 6b3f50bb |
| 1501 | +LMS key 2 hash (48 bytes, reversed-dword): 94a4087e 5ad33369 ... 888f5a22 |
| 1502 | +LMS key 3 hash (48 bytes, reversed-dword): bc4f73d3 a39328ee ... bb3d462e |
| 1503 | + ... (keys 0-3 repeated 8 times to fill all 32 slots) |
| 1504 | + |
| 1505 | +Total: 4 + (32 × 48) = 1540 bytes |
| 1506 | +``` |
| 1507 | + |
| 1508 | +#### Step 5: Compute the vendor PK descriptor hash |
| 1509 | + |
| 1510 | +``` |
| 1511 | +Input = ECC descriptor (196 bytes) || PQC descriptor (1540 bytes) = 1736 bytes |
| 1512 | + |
| 1513 | +SHA384 (standard byte order): |
| 1514 | + b17ca877 666657cc d100e692 6c7206b6 0c995cb6 8992c6c9 |
| 1515 | + baefce72 8af05441 dee1ff41 5adfc187 e1e4edb4 d3b2d909 |
| 1516 | + |
| 1517 | +As [u32; 12] fuse register value: |
| 1518 | + [0xb17ca877, 0x666657cc, 0xd100e692, 0x6c7206b6, |
| 1519 | + 0x0c995cb6, 0x8992c6c9, 0xbaefce72, 0x8af05441, |
| 1520 | + 0xdee1ff41, 0x5adfc187, 0xe1e4edb4, 0xd3b2d909] |
| 1521 | +``` |
| 1522 | + |
| 1523 | +### Computing public key hashes: MLDSA step-by-step example |
| 1524 | + |
| 1525 | +The following example walks through the same computation as the LMS example above, but |
| 1526 | +using PQC key type **MLDSA (type 1)** with the test keys from `image/fake-keys/src/lib.rs`. |
| 1527 | + |
| 1528 | +#### MLDSA Step 1: Hash each vendor ECC public key |
| 1529 | + |
| 1530 | +The ECC keys and their hashes are identical to the LMS example — see |
| 1531 | +[Step 1 above](#step-1-hash-each-vendor-ecc-public-key). The ECC key descriptor is |
| 1532 | +independent of the PQC key type. |
| 1533 | + |
| 1534 | +#### MLDSA Step 2: Hash each vendor MLDSA public key |
| 1535 | + |
| 1536 | +Each MLDSA-87 public key is a 2592-byte array (`[u32; 648]`). When serialized via |
| 1537 | +`as_bytes()`, each `u32` word is written in little-endian byte order — for example, the |
| 1538 | +Rust value `0x3bf1c072` becomes bytes `72 c0 f1 3b` in memory. Unlike LMS keys, MLDSA |
| 1539 | +keys are not subject to any additional encoding — these raw bytes are hashed directly |
| 1540 | +with SHA2-384. |
| 1541 | + |
| 1542 | +**MLDSA Key 0:** |
| 1543 | +``` |
| 1544 | +Size: 2592 bytes (648 u32 words) |
| 1545 | +First 24 bytes: 72c0f13b 7d937e22 69b6988d 6daadc3a e78acd11 940cfc0d ... |
| 1546 | + |
| 1547 | +SHA384 (standard): f1097978 0adae470 dcd4eeb8 5749a2e4 2e70c055 ebac46e4 |
| 1548 | + 07c2c404 b46473d8 189117ed 8c83dde4 9f941e6a 1b6c6d4c |
| 1549 | +SHA384 (reversed-dword): 787909f1 70e4da0a b8eed4dc e4a24957 55c0702e e446aceb |
| 1550 | + 04c4c207 d87364b4 ed179118 e4dd838c 6a1e949f 4c6d6c1b |
| 1551 | +``` |
| 1552 | + |
| 1553 | +**MLDSA Key 1:** |
| 1554 | +``` |
| 1555 | +Size: 2592 bytes (648 u32 words) |
| 1556 | +First 24 bytes: f432346c 096d0ec9 04f8d925 1512236b e3fd1ccb bda9ed3a ... |
| 1557 | + |
| 1558 | +SHA384 (standard): a57b6f71 ffab9844 de49e9f7 ad61476b 7446e140 517d07b1 |
| 1559 | + 81447acb a6d7166f 7b89f199 b6e36174 2d0ab01c 540d26de |
| 1560 | +SHA384 (reversed-dword): 716f7ba5 4498abff f7e949de 6b4761ad 40e14674 b1077d51 |
| 1561 | + cb7a4481 6f16d7a6 99f1897b 7461e3b6 1cb00a2d de260d54 |
| 1562 | +``` |
| 1563 | + |
| 1564 | +**MLDSA Key 2:** |
| 1565 | +``` |
| 1566 | +Size: 2592 bytes (648 u32 words) |
| 1567 | +First 24 bytes: 2bc91a00 7d3e5a4f e6b3f2ec cb1aaa0d 278d9786 44b25fed ... |
| 1568 | + |
| 1569 | +SHA384 (standard): 7f2f3c55 e8dd2481 bbee17c1 5d5773a8 01a9c0a6 84b30e47 |
| 1570 | + 0ae67ecd 1ec3e7ac 19273c71 feb6bb99 10d26dd0 4ace4298 |
| 1571 | +SHA384 (reversed-dword): 553c2f7f 8124dde8 c117eebb a873575d a6c0a901 470eb384 |
| 1572 | + cd7ee60a ace7c31e 713c2719 99bbb6fe d06dd210 9842ce4a |
| 1573 | +``` |
| 1574 | + |
| 1575 | +**MLDSA Key 3:** |
| 1576 | +``` |
| 1577 | +Size: 2592 bytes (648 u32 words) |
| 1578 | +First 24 bytes: 378dcb02 a6db3481 d51e9913 14da1567 a211290e f4c3d02f ... |
| 1579 | + |
| 1580 | +SHA384 (standard): 79fbeb0a 6ebc354b ccf48dd1 5b6c9142 a62af0c5 198c0de1 |
| 1581 | + 365fbcb0 b2463ee5 103ccae3 4504ab83 04b37886 5c9a28ae |
| 1582 | +SHA384 (reversed-dword): 0aebfb79 4b35bc6e d18df4cc 42916c5b c5f02aa6 e10d8c19 |
| 1583 | + b0bc5f36 e53e46b2 e3ca3c10 83ab0445 8678b304 ae289a5c |
| 1584 | +``` |
| 1585 | + |
| 1586 | +#### MLDSA Step 3: Build the ECC key descriptor (196 bytes) |
| 1587 | + |
| 1588 | +Same as the LMS example — the ECC descriptor is independent of PQC key type. See |
| 1589 | +[Step 3 above](#step-3-build-the-ecc-key-descriptor-196-bytes). |
| 1590 | + |
| 1591 | +#### MLDSA Step 4: Build the PQC (MLDSA) key descriptor (1540 bytes) |
| 1592 | + |
| 1593 | +The PQC key descriptor struct always has 32 hash slots (`VENDOR_PQC_MAX_KEY_COUNT`). |
| 1594 | +For MLDSA, only 4 keys are populated; the remaining 28 slots are zero-filled. |
| 1595 | + |
| 1596 | +``` |
| 1597 | +Header (4 bytes): 01 00 01 04 (version=1, key_type=1=MLDSA, key_hash_count=4) |
| 1598 | +MLDSA key 0 hash (48 bytes, reversed-dword): 787909f1 70e4da0a ... 4c6d6c1b |
| 1599 | +MLDSA key 1 hash (48 bytes, reversed-dword): 716f7ba5 4498abff ... de260d54 |
| 1600 | +MLDSA key 2 hash (48 bytes, reversed-dword): 553c2f7f 8124dde8 ... 9842ce4a |
| 1601 | +MLDSA key 3 hash (48 bytes, reversed-dword): 0aebfb79 4b35bc6e ... ae289a5c |
| 1602 | + ... (keys 4-31 are zero-filled) |
| 1603 | + |
| 1604 | +Total: 4 + (32 × 48) = 1540 bytes |
| 1605 | +``` |
| 1606 | + |
| 1607 | +#### MLDSA Step 5: Compute the vendor PK descriptor hash |
| 1608 | + |
| 1609 | +``` |
| 1610 | +Input = ECC descriptor (196 bytes) || PQC descriptor (1540 bytes) = 1736 bytes |
| 1611 | + |
| 1612 | +SHA384 (standard byte order): |
| 1613 | + 30399676 a17e3e97 3677b3ff 862f4bf2 d1932d88 4778453c |
| 1614 | + 376fe00d c93fb8aa 0770f3eb f3411a08 53e9c57e ce8a2980 |
| 1615 | + |
| 1616 | +As [u32; 12] fuse register value: |
| 1617 | + [0x30399676, 0xa17e3e97, 0x3677b3ff, 0x862f4bf2, |
| 1618 | + 0xd1932d88, 0x4778453c, 0x376fe00d, 0xc93fb8aa, |
| 1619 | + 0x0770f3eb, 0xf3411a08, 0x53e9c57e, 0xce8a2980] |
| 1620 | +``` |
| 1621 | + |
| 1622 | +#### Owner PK hash |
| 1623 | + |
| 1624 | +The owner PK hash is SHA2-384 over the serialized `ImageOwnerPubKeys` struct, which contains: |
| 1625 | +- `ecc_pub_key`: `{ x: [u32; 12], y: [u32; 12] }` — 96 bytes (in reversed-dword format) |
| 1626 | +- `pqc_pub_key`: raw byte array of 2592 bytes (for LMS, only the first 48 bytes are meaningful; |
| 1627 | + the rest are zero-padded) |
| 1628 | + |
| 1629 | +Total: 2688 bytes. The SHA2-384 of these bytes is the owner PK hash. |
| 1630 | + |
| 1631 | +#### Summary of expected hash values using test keys |
| 1632 | + |
| 1633 | +Using the test keys from `image/fake-keys/src/lib.rs`: |
| 1634 | + |
| 1635 | +| Hash | PQC Type | Standard byte order (hex) | |
| 1636 | +| ------ | ---------- | --------------------------- | |
| 1637 | +| Vendor PK descriptor hash | LMS (type 3) | `b17ca877666657ccd100e6926c7206b60c995cb68992c6c9baefce728af05441dee1ff415adfc187e1e4edb4d3b2d909` | |
| 1638 | +| Vendor PK descriptor hash | MLDSA (type 1) | `30399676a17e3e973677b3ff862f4bf2d1932d884778453c376fe00dc93fb8aa0770f3ebf3411a0853e9c57ece8a2980` | |
| 1639 | +| Owner PK hash | LMS (type 3) | `1b179390e4e6c44422ed553e256c7d675cd93190cb49d88d485aa4ef3906cd492ab3ee3d3ba5f2c990ad13390fed4de5` | |
| 1640 | +| Owner PK hash | MLDSA (type 1) | `48afdb073c5e0d4ee46490468ef81f2cf57249b6e76a28f5fca4de696a7d3e2ed3efc4e6774318543e95307a54988bd7` | |
| 1641 | + |
| 1642 | + |
| 1643 | +To convert any of these standard byte order hashes to the `[u32; 12]` fuse register format, group |
| 1644 | +the hex string into 8-character (4-byte) chunks and interpret each as a 32-bit word: |
| 1645 | +- `b17ca877666657cc...` → `[0xb17ca877, 0x666657cc, 0xd100e692, ...]` |
| 1646 | + |
| 1647 | +#### Python script to compute vendor and owner PK hashes |
| 1648 | + |
| 1649 | +The following Python script computes the vendor PK descriptor hash and owner PK hash from |
| 1650 | +ECC PEM files and LMS or MLDSA binary key files: |
| 1651 | + |
| 1652 | +```python |
| 1653 | +#!/usr/bin/env python3 |
| 1654 | +""" |
| 1655 | +Compute the Caliptra vendor PK descriptor hash and owner PK hash |
| 1656 | +from ECC (.pem) and LMS/MLDSA (.bin) public key files. |
| 1657 | + |
| 1658 | +Usage: |
| 1659 | + python3 compute_pk_hashes.py --pqc-key-type <1|3> \\ |
| 1660 | + --vendor-ecc-pub-keys key0.pem key1.pem key2.pem key3.pem \\ |
| 1661 | + --vendor-pqc-pub-keys pqc0.bin pqc1.bin ... \\ |
| 1662 | + --owner-ecc-pub-key owner.pem \\ |
| 1663 | + --owner-pqc-pub-key owner_pqc.bin |
| 1664 | + |
| 1665 | +PQC key type: 1 = MLDSA, 3 = LMS |
| 1666 | + |
| 1667 | +ECC public keys are PEM files (P-384). |
| 1668 | +LMS public keys are 48-byte binary files (tree_type, otstype, id, digest). |
| 1669 | +MLDSA public keys are 2592-byte binary files. |
| 1670 | +""" |
| 1671 | +import argparse |
| 1672 | +import hashlib |
| 1673 | +import struct |
| 1674 | +import sys |
| 1675 | + |
| 1676 | +from cryptography.hazmat.primitives.serialization import load_pem_public_key |
| 1677 | + |
| 1678 | +# Sizes |
| 1679 | +ECC_PUB_KEY_BYTES = 96 # 2 x 48-byte coordinates |
| 1680 | +PQC_PUB_KEY_SLOT_BYTES = 2592 # MLDSA key size; LMS keys are 48 bytes, zero-padded |
| 1681 | +LMS_PUB_KEY_BYTES = 48 |
| 1682 | +MLDSA_PUB_KEY_BYTES = 2592 |
| 1683 | +HASH_BYTES = 48 # SHA2-384 |
| 1684 | + |
| 1685 | +VENDOR_ECC_MAX_KEYS = 4 |
| 1686 | +VENDOR_LMS_MAX_KEYS = 32 |
| 1687 | +VENDOR_MLDSA_MAX_KEYS = 32 # struct always allocates 32 slots; only first 4 are populated |
| 1688 | +KEY_DESCRIPTOR_VERSION = 1 |
| 1689 | + |
| 1690 | + |
| 1691 | +def ecc_pub_key_to_reversed_dwords(pem_path: str) -> bytes: |
| 1692 | + """Read an ECC P-384 PEM public key and return 96 bytes in reversed-dword format.""" |
| 1693 | + with open(pem_path, 'rb') as f: |
| 1694 | + pub_key = load_pem_public_key(f.read()) |
| 1695 | + nums = pub_key.public_numbers() |
| 1696 | + x_bytes = nums.x.to_bytes(48, 'big') |
| 1697 | + y_bytes = nums.y.to_bytes(48, 'big') |
| 1698 | + return to_reversed_dwords(x_bytes) + to_reversed_dwords(y_bytes) |
| 1699 | + |
| 1700 | + |
| 1701 | +def to_reversed_dwords(standard_bytes: bytes) -> bytes: |
| 1702 | + """Convert bytes from standard byte order to reversed-dword format. |
| 1703 | + |
| 1704 | + Groups the input into 4-byte dwords and reverses the bytes within each dword. |
| 1705 | + """ |
| 1706 | + assert len(standard_bytes) % 4 == 0 |
| 1707 | + result = bytearray() |
| 1708 | + for i in range(0, len(standard_bytes), 4): |
| 1709 | + result.extend(standard_bytes[i:i+4][::-1]) |
| 1710 | + return bytes(result) |
| 1711 | + |
| 1712 | + |
| 1713 | +def sha384_reversed_dwords(data: bytes) -> bytes: |
| 1714 | + """Compute SHA2-384 and return the hash in reversed-dword format.""" |
| 1715 | + h = hashlib.sha384(data).digest() |
| 1716 | + return to_reversed_dwords(h) |
| 1717 | + |
| 1718 | + |
| 1719 | +def build_ecc_key_descriptor(ecc_pem_paths: list) -> bytes: |
| 1720 | + """Build the ECC key descriptor: header + key hashes.""" |
| 1721 | + n = len(ecc_pem_paths) |
| 1722 | + header = struct.pack('<HBB', KEY_DESCRIPTOR_VERSION, 0, n) |
| 1723 | + hashes = b'' |
| 1724 | + for path in ecc_pem_paths: |
| 1725 | + key_bytes = ecc_pub_key_to_reversed_dwords(path) |
| 1726 | + hashes += sha384_reversed_dwords(key_bytes) |
| 1727 | + # Pad to VENDOR_ECC_MAX_KEYS slots |
| 1728 | + hashes += b'\x00' * (HASH_BYTES * (VENDOR_ECC_MAX_KEYS - n)) |
| 1729 | + return header + hashes |
| 1730 | + |
| 1731 | + |
| 1732 | +def build_pqc_key_descriptor(pqc_bin_paths: list, pqc_key_type: int) -> bytes: |
| 1733 | + """Build the PQC key descriptor: header + key hashes.""" |
| 1734 | + n = len(pqc_bin_paths) |
| 1735 | + max_keys = VENDOR_LMS_MAX_KEYS if pqc_key_type == 3 else VENDOR_MLDSA_MAX_KEYS |
| 1736 | + header = struct.pack('<HBB', KEY_DESCRIPTOR_VERSION, pqc_key_type, n) |
| 1737 | + hashes = b'' |
| 1738 | + for path in pqc_bin_paths: |
| 1739 | + with open(path, 'rb') as f: |
| 1740 | + key_bytes = f.read() |
| 1741 | + hashes += sha384_reversed_dwords(key_bytes) |
| 1742 | + # Pad to max slots |
| 1743 | + hashes += b'\x00' * (HASH_BYTES * (max_keys - n)) |
| 1744 | + return header + hashes |
| 1745 | + |
| 1746 | + |
| 1747 | +def build_owner_pub_keys(ecc_pem_path: str, pqc_bin_path: str) -> bytes: |
| 1748 | + """Build the serialized ImageOwnerPubKeys struct.""" |
| 1749 | + ecc_bytes = ecc_pub_key_to_reversed_dwords(ecc_pem_path) |
| 1750 | + with open(pqc_bin_path, 'rb') as f: |
| 1751 | + pqc_bytes = f.read() |
| 1752 | + # Pad PQC key to full slot size |
| 1753 | + pqc_padded = pqc_bytes + b'\x00' * (PQC_PUB_KEY_SLOT_BYTES - len(pqc_bytes)) |
| 1754 | + return ecc_bytes + pqc_padded |
| 1755 | + |
| 1756 | + |
| 1757 | +def hash_to_fuse_words(standard_hash: bytes) -> list: |
| 1758 | + """Convert a standard byte order hash to [u32; 12] fuse word format.""" |
| 1759 | + return [int.from_bytes(standard_hash[i:i+4], 'big') for i in range(0, 48, 4)] |
| 1760 | + |
| 1761 | + |
| 1762 | +def main(): |
| 1763 | + parser = argparse.ArgumentParser( |
| 1764 | + description='Compute Caliptra vendor PK descriptor hash and owner PK hash') |
| 1765 | + parser.add_argument('--pqc-key-type', type=int, required=True, choices=[1, 3], |
| 1766 | + help='PQC key type: 1=MLDSA, 3=LMS') |
| 1767 | + parser.add_argument('--vendor-ecc-pub-keys', nargs='+', required=True, |
| 1768 | + help='Vendor ECC P-384 public key PEM files') |
| 1769 | + parser.add_argument('--vendor-pqc-pub-keys', nargs='+', required=True, |
| 1770 | + help='Vendor PQC (LMS .bin or MLDSA .bin) public key files') |
| 1771 | + parser.add_argument('--owner-ecc-pub-key', |
| 1772 | + help='Owner ECC P-384 public key PEM file') |
| 1773 | + parser.add_argument('--owner-pqc-pub-key', |
| 1774 | + help='Owner PQC (LMS .bin or MLDSA .bin) public key file') |
| 1775 | + args = parser.parse_args() |
| 1776 | + |
| 1777 | + pqc_name = {1: 'MLDSA', 3: 'LMS'}[args.pqc_key_type] |
| 1778 | + |
| 1779 | + # Build descriptors |
| 1780 | + ecc_desc = build_ecc_key_descriptor(args.vendor_ecc_pub_keys) |
| 1781 | + pqc_desc = build_pqc_key_descriptor(args.vendor_pqc_pub_keys, args.pqc_key_type) |
| 1782 | + vendor_pub_key_info = ecc_desc + pqc_desc |
| 1783 | + |
| 1784 | + # Vendor PK descriptor hash (standard byte order) |
| 1785 | + vendor_hash = hashlib.sha384(vendor_pub_key_info).digest() |
| 1786 | + vendor_hex = vendor_hash.hex() |
| 1787 | + vendor_words = hash_to_fuse_words(vendor_hash) |
| 1788 | + |
| 1789 | + print(f"PQC key type: {args.pqc_key_type} ({pqc_name})") |
| 1790 | + print() |
| 1791 | + print(f"Vendor PK descriptor hash (standard byte order):") |
| 1792 | + print(f" {vendor_hex}") |
| 1793 | + print(f"Vendor PK descriptor hash (fuse [u32; 12]):") |
| 1794 | + print(f" {['0x{:08x}'.format(w) for w in vendor_words]}") |
| 1795 | + |
| 1796 | + if args.owner_ecc_pub_key and args.owner_pqc_pub_key: |
| 1797 | + owner_bytes = build_owner_pub_keys(args.owner_ecc_pub_key, args.owner_pqc_pub_key) |
| 1798 | + owner_hash = hashlib.sha384(owner_bytes).digest() |
| 1799 | + owner_hex = owner_hash.hex() |
| 1800 | + owner_words = hash_to_fuse_words(owner_hash) |
| 1801 | + |
| 1802 | + print() |
| 1803 | + print(f"Owner PK hash (standard byte order):") |
| 1804 | + print(f" {owner_hex}") |
| 1805 | + print(f"Owner PK hash (fuse [u32; 12]):") |
| 1806 | + print(f" {['0x{:08x}'.format(w) for w in owner_words]}") |
| 1807 | + |
| 1808 | + |
| 1809 | +if __name__ == '__main__': |
| 1810 | + main() |
| 1811 | +``` |
| 1812 | + |
| 1813 | +### Fuse value byte ordering |
| 1814 | + |
| 1815 | +This section documents the byte ordering convention for every multi-word fuse |
| 1816 | +register. It uses the same style as the |
| 1817 | +[Byte order of cryptographic fields](../../runtime/README.md#byte-order-of-cryptographic-fields) |
| 1818 | +section in the Runtime README: examples show the relationship between standard |
| 1819 | +tool output (e.g. OpenSSL, Python `hashlib`) and the `u32` word values written |
| 1820 | +to fuse registers. |
| 1821 | + |
| 1822 | +> **When adding a new multi-word fuse**, add an entry to the appropriate |
| 1823 | +> category below so that SoC integrators have a single reference for all fuse |
| 1824 | +> byte ordering. |
| 1825 | + |
| 1826 | +#### SHA digest fuses (big-endian words / reversed-dword) |
| 1827 | + |
| 1828 | +The following fuse registers store SHA digest values as `[u32; N]` arrays using |
| 1829 | +the same **reversed-dword format** described in |
| 1830 | +[Public key hash byte ordering](#public-key-hash-byte-ordering-dword-reversal). |
| 1831 | +Each 4-byte group from the standard hash output (as produced by `openssl dgst` |
| 1832 | +or Python's `hashlib`) is byte-reversed when stored as a `u32` word. |
| 1833 | + |
| 1834 | +| Fuse Register | Array Type | Hash Algorithm | |
| 1835 | +| --- | --- | --- | |
| 1836 | +| FUSE_VENDOR_PK_HASH | `[u32; 12]` | SHA2-384 of vendor public key descriptors | |
| 1837 | +| FUSE_MANUF_DEBUG_UNLOCK_TOKEN | `[u32; 16]` | SHA-512 of the manufacturing debug unlock token | |
| 1838 | + |
| 1839 | + |
| 1840 | +Example — suppose `openssl dgst -sha512` produces a digest starting with: |
| 1841 | + |
| 1842 | +``` |
| 1843 | +openssl output: 86 9B A8 D5 AD 0F CF 82 02 E5 60 80 ... |
| 1844 | + ~~~~~~~~~~~ ~~~~~~~~~~~ ~~~~~~~~~~~ |
| 1845 | +Fuse register[0]: 0x869BA8D5 [1]: 0xAD0FCF82 [2]: 0x02E56080 ... |
| 1846 | +``` |
| 1847 | + |
| 1848 | +Each 4-byte group from the OpenSSL output maps directly to one fuse register |
| 1849 | +word as a big-endian `u32` — the first byte of the group is the most-significant |
| 1850 | +byte of the word. |
| 1851 | + |
| 1852 | +On the little-endian RISC-V bus the bytes within each register word appear |
| 1853 | +reversed at byte addresses: |
| 1854 | + |
| 1855 | +``` |
| 1856 | +Fuse byte address: 0 1 2 3 4 5 6 7 8 9 A B ... |
| 1857 | +Byte value: D5 A8 9B 86 82 CF 0F AD 80 60 E5 02 ... |
| 1858 | + ── register[0] ── ─── register[1] ── ── register[2] ── |
| 1859 | +``` |
| 1860 | + |
| 1861 | +##### Manufacturing debug unlock token: step-by-step |
| 1862 | + |
| 1863 | +1. Choose a 32-byte random secret (the raw token). This is what the SoC sends |
| 1864 | + over the mailbox to unlock debug. |
| 1865 | + |
| 1866 | +2. Compute SHA-512 of the raw token: |
| 1867 | + ``` |
| 1868 | + $ printf '\xd8\x92\x2c\x55\x79\x2b\x73\x7f\x29\x13\xf3\xe5\xcb\xe6\x54\x75' \ |
| 1869 | + '\x62\x52\x01\x6e\xae\xe9\x63\xa1\xdd\x4e\x75\x3a\xf7\x87\xf0\x96' \ |
| 1870 | + | openssl dgst -sha512 -binary | xxd -p -c 64 |
| 1871 | + 869ba8d5ad0fcf8202e560803281da659812ffa2fc28c2d5154cb645ee0c38ec |
| 1872 | + 4fd9dd8bb0be7deb193f625381383a91ab40bd920fcd9425919e63723c0bf7a8 |
| 1873 | + ``` |
| 1874 | + |
| 1875 | +3. Split into 4-byte groups and interpret each as a big-endian `u32` to get the |
| 1876 | + fuse word values: |
| 1877 | + ``` |
| 1878 | + Fuse [u32; 16] = { |
| 1879 | + 0x869BA8D5, 0xAD0FCF82, 0x02E56080, 0x3281DA65, |
| 1880 | + 0x9812FFA2, 0xFC28C2D5, 0x154CB645, 0xEE0C38EC, |
| 1881 | + 0x4FD9DD8B, 0xB0BE7DEB, 0x193F6253, 0x81383A91, |
| 1882 | + 0xAB40BD92, 0x0FCD9425, 0x919E6372, 0x3C0BF7A8, |
| 1883 | + } |
| 1884 | + ``` |
| 1885 | + |
| 1886 | +4. MCU or SoC manager writes these 16 words into the `FUSE_MANUF_DEBUG_UNLOCK_TOKEN` registers from fuses. |
| 1887 | + |
| 1888 | +#### Architectural register: CPTRA_OWNER_PK_HASH (big-endian words) |
| 1889 | + |
| 1890 | +**CPTRA_OWNER_PK_HASH** (`[u32; 12]`) uses the same reversed-dword format as |
| 1891 | +FUSE_VENDOR_PK_HASH. See |
| 1892 | +[Public key hash byte ordering](#public-key-hash-byte-ordering-dword-reversal) |
| 1893 | +for details and worked examples. |
| 1894 | + |
| 1895 | +##### Production debug unlock public key hashes: byte ordering |
| 1896 | + |
| 1897 | +The production debug unlock flow uses SHA2-384 hashes of the concatenated |
| 1898 | +ECC and MLDSA public keys to authenticate debug unlock tokens. These hashes |
| 1899 | +are stored in the MCI register bank at addresses computed from |
| 1900 | +`SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK_OFFSET`. |
| 1901 | + |
| 1902 | +**Hash input construction:** |
| 1903 | + |
| 1904 | +The hash is SHA2-384 over the raw mailbox wire bytes of the concatenated |
| 1905 | +ECC and MLDSA public keys from the `AUTH_DEBUG_UNLOCK_TOKEN` payload. |
| 1906 | +The mailbox wire format for each key type is: |
| 1907 | + |
| 1908 | +- **ECC public key (96 bytes)**: Each 4-byte group of the X and Y |
| 1909 | + coordinates is **dword-reversed** from the standard OpenSSL output. |
| 1910 | + |
| 1911 | + ``` |
| 1912 | + openssl ec output: AB CD EF 01 23 45 67 89 ... (X, 48 bytes) |
| 1913 | + 11 22 33 44 55 66 77 88 ... (Y, 48 bytes) |
| 1914 | + |
| 1915 | + Hash input (= mailbox wire bytes): |
| 1916 | + 01 EF CD AB 89 67 45 23 ... (X, dword-reversed) |
| 1917 | + 44 33 22 11 88 77 66 55 ... (Y, dword-reversed) |
| 1918 | + ``` |
| 1919 | + |
| 1920 | +- **MLDSA public key (2592 bytes)**: The native MLDSA key bytes are |
| 1921 | + used **as-is** — no conversion. |
| 1922 | + |
| 1923 | + ``` |
| 1924 | + MLDSA keygen output: 72 C0 F1 3B 7D 93 7E 22 ... |
| 1925 | + |
| 1926 | + Hash input (= mailbox wire bytes): |
| 1927 | + 72 C0 F1 3B 7D 93 7E 22 ... (identical) |
| 1928 | + ``` |
| 1929 | + |
| 1930 | +To compute the same hash offline for fuse provisioning, reconstruct the |
| 1931 | +mailbox wire bytes: dword-reverse the ECC coordinates, keep MLDSA native, |
| 1932 | +concatenate, and hash: |
| 1933 | + |
| 1934 | +``` |
| 1935 | +ECC dword-reversed: 01 EF CD AB 89 67 45 23 ... (96 bytes) |
| 1936 | +MLDSA native: 72 C0 F1 3B 7D 93 7E 22 ... (2592 bytes) |
| 1937 | + |
| 1938 | +hash_input = ECC_dword_reversed || MLDSA_native_bytes (2688 bytes) |
| 1939 | + |
| 1940 | +$ openssl dgst -sha384 -binary combined.bin | xxd -p -c 48 |
| 1941 | +→ 3f7a2b91c4e8d0f5... |
| 1942 | +``` |
| 1943 | + |
| 1944 | +**Provisioning: OpenSSL example** |
| 1945 | + |
| 1946 | +To prepare `combined_keys.bin`, dword-reverse the ECC raw coordinates |
| 1947 | +and concatenate with the native MLDSA key bytes. Then compute the hash: |
| 1948 | + |
| 1949 | +``` |
| 1950 | +$ openssl dgst -sha384 -binary combined_keys.bin | xxd -p -c 48 |
| 1951 | +3f7a2b91c4e8d0f5a1b2c3d4e5f60718293a4b5c6d7e8f90a0b1c2d3e4f5061728394a5b6c |
| 1952 | +``` |
| 1953 | + |
| 1954 | +Map the digest output to fuse register words — each 4-byte group becomes |
| 1955 | +one `u32` fuse word (same convention as all other SHA digest fuses): |
| 1956 | + |
| 1957 | +``` |
| 1958 | +openssl output: 3f 7a 2b 91 c4 e8 d0 f5 a1 b2 c3 d4 ... |
| 1959 | + ~~~~~~~~~~~ ~~~~~~~~~~~ ~~~~~~~~~~~ |
| 1960 | +Fuse word[0]: 0x3F7A2B91 [1]: 0xC4E8D0F5 [2]: 0xA1B2C3D4 ... |
| 1961 | +``` |
| 1962 | + |
| 1963 | +Write these 12 words to the MCI register bank at offset: |
| 1964 | + |
| 1965 | +``` |
| 1966 | +SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK_OFFSET + ((level - 1) * 48) |
| 1967 | +``` |
| 1968 | + |
| 1969 | +**Mailbox payload: preparing fields from OpenSSL output** |
| 1970 | + |
| 1971 | +The `AUTH_DEBUG_UNLOCK_TOKEN` mailbox command fields use the byte order |
| 1972 | +conventions described in |
| 1973 | +[Byte order of cryptographic fields](../../runtime/README.md#byte-order-of-cryptographic-fields). |
| 1974 | +The table below summarizes how to convert OpenSSL tool output into the |
| 1975 | +mailbox payload bytes for each field: |
| 1976 | + |
| 1977 | +- **ECC P-384 public key (big-endian words)**: Extract the raw X and Y |
| 1978 | + coordinates (48 bytes each) from the PEM key, then **dword-reverse** |
| 1979 | + each 4-byte group before writing to the mailbox. |
| 1980 | + |
| 1981 | + ``` |
| 1982 | + # Extract raw X||Y from PEM (96 bytes, big-endian): |
| 1983 | + $ openssl ec -pubin -in key.pem -outform DER 2>/dev/null \ |
| 1984 | + | tail -c 96 | xxd -p -c 48 |
| 1985 | + |
| 1986 | + OpenSSL raw bytes: AB CD EF 01 23 45 67 89 ... (X, 48 bytes) |
| 1987 | + 11 22 33 44 55 66 77 88 ... (Y, 48 bytes) |
| 1988 | + |
| 1989 | + Mailbox bytes: 01 EF CD AB 89 67 45 23 ... (X, dword-reversed) |
| 1990 | + 44 33 22 11 88 77 66 55 ... (Y, dword-reversed) |
| 1991 | + ``` |
| 1992 | + |
| 1993 | +- **MLDSA-87 public key (little-endian words)**: Copy the raw key bytes |
| 1994 | + produced by an MLDSA implementation (e.g. OpenSSL 3.5+, `fips204` crate) |
| 1995 | + **directly** into the mailbox — no conversion needed. |
| 1996 | + |
| 1997 | + ``` |
| 1998 | + MLDSA key bytes: 72 C0 F1 3B 7D 93 7E 22 ... (2592 bytes) |
| 1999 | + Mailbox bytes: 72 C0 F1 3B 7D 93 7E 22 ... (identical) |
| 2000 | + ``` |
| 2001 | + |
| 2002 | +- **ECC P-384 signature (big-endian words)**: Same treatment as the public |
| 2003 | + key — dword-reverse each 4-byte group of the R and S coordinates. |
| 2004 | + |
| 2005 | +- **MLDSA-87 signature (little-endian words)**: Copy raw signature bytes |
| 2006 | + directly — no conversion needed. The trailing byte (byte 4628) is |
| 2007 | + reserved and should be zero. |
| 2008 | + |
| 2009 | +**Note:** The hash used for fuse provisioning is computed over the exact |
| 2010 | +same bytes that appear on the mailbox wire. There is no additional |
| 2011 | +transformation — the SHA accelerator's internal endianness handling is |
| 2012 | +transparent and produces `SHA384(wire_bytes)`. Therefore the provisioning |
| 2013 | +hash and the runtime verification hash are both computed over |
| 2014 | +`ECC_dword_reversed || MLDSA_native`. |
| 2015 | + |
| 2016 | +#### SVN fuses (little-endian 128-bit bitmap) |
| 2017 | + |
| 2018 | +**FUSE_FIRMWARE_SVN** and **FUSE_SOC_MANIFEST_SVN** are 128-bit one-hot encoded bitmaps stored |
| 2019 | +as `[u32; 4]`. These are **not** cryptographic values — the security version |
| 2020 | +number equals the bit position of the highest set bit. |
| 2021 | + |
| 2022 | +The four words form a little-endian 128-bit integer: word\[0\] contains bits |
| 2023 | +0–31, word\[1\] contains bits 32–63, and so on. |
| 2024 | + |
| 2025 | +Example — to program SVN 7, set bits 0 through 6: |
| 2026 | + |
| 2027 | +``` |
| 2028 | +FUSE_FIRMWARE_SVN[0] = 0x0000007F (bits 0-6 set) |
| 2029 | +FUSE_FIRMWARE_SVN[1] = 0x00000000 |
| 2030 | +FUSE_FIRMWARE_SVN[2] = 0x00000000 |
| 2031 | +FUSE_FIRMWARE_SVN[3] = 0x00000000 |
| 2032 | +``` |
| 2033 | + |
| 2034 | +Example — SVN 40 means bits 0 through 39 are set: |
| 2035 | + |
| 2036 | +``` |
| 2037 | +FUSE_FIRMWARE_SVN[0] = 0xFFFFFFFF (bits 0-31 set) |
| 2038 | +FUSE_FIRMWARE_SVN[1] = 0x000000FF (bits 32-39 set) |
| 2039 | +FUSE_FIRMWARE_SVN[2] = 0x00000000 |
| 2040 | +FUSE_FIRMWARE_SVN[3] = 0x00000000 |
| 2041 | +``` |
| 2042 | + |
| 2043 | +#### Obfuscated seed fuses (big-endian words) |
| 2044 | + |
| 2045 | +**FUSE_UDS_SEED** (`[u32; 16]`), **FUSE_FIELD_ENTROPY** (`[u32; 8]`), and |
| 2046 | +**FUSE_HEK_SEED** (`[u32; 8]`) are obfuscated secret values. They use the same |
| 2047 | +**big-endian word** ordering as SHA digest fuses — each `u32` word maps to 4 |
| 2048 | +bytes in big-endian order. |
| 2049 | + |
| 2050 | +These values are consumed through an AES de-obfuscation step and are typically |
| 2051 | +programmed by the manufacturing toolchain. If replicating values for test or |
| 2052 | +simulation, use the same big-endian word convention when converting between byte |
| 2053 | +arrays and `[u32; N]` arrays. |
| 2054 | + |
| 2055 | +#### Scalar and per-word fuses (no byte-ordering concern) |
| 2056 | + |
| 2057 | +The following fuse registers are single words or per-word indexed values with no |
| 2058 | +multi-word byte ordering: |
| 2059 | + |
| 2060 | +| Register | Width | Notes | |
| 2061 | +| --- | --- | --- | |
| 2062 | +| FUSE_ECC_REVOCATION | 4 bits | Bitmask | |
| 2063 | +| FUSE_LMS_REVOCATION | 32 bits | Bitmask | |
| 2064 | +| FUSE_MLDSA_REVOCATION | 4 bits | Bitmask | |
| 2065 | +| FUSE_ANTI_ROLLBACK_DISABLE | 1 bit | Boolean | |
| 2066 | +| FUSE_PQC_KEY_TYPE | 2 bits | One-hot encoded | |
| 2067 | +| FUSE_SOC_STEPPING_ID | 16 bits | Scalar | |
| 2068 | +| FUSE_SOC_MANIFEST_MAX_SVN | 8 bits | Scalar | |
| 2069 | +| FUSE_IDEVID_CERT_ATTR | 24 × u32 | Per-word indexed; each word accessed individually | |
| 2070 | +| FUSE_IDEVID_MANUF_HSM_ID | 4 × u32 | Opaque identifier, used as-is | |
| 2071 | + |
| 1152 | 2072 | |
| 1153 | 2073 | ## Preamble validation steps |
| 1154 | 2074 | |