[doc] Byte orientation documentation for prod debug unlock fuses (#3635)

Author: mhatrevi

auth-manifest/README.md

@@ -9,7 +9,7 @@ The Caliptra SOC manifest has two main components: [Preamble](#preamble) and [Im
   Those signatures are also stored in the Preamble.
   The Caliptra firmware's ECC and PQC private keys endorse the manifest's public keys, and these endorsements (signatures) are part of the Preamble as well.
 
-  *Note: All fields are little endian unless specified*
+  *Note: Do not treat the entire manifest as little endian. Scalar `u32` fields use little-endian layout. ECC key and signature fields are stored as big-endian `u32` words. Raw byte-array fields, such as image hashes, use the exact byte sequence produced by standard tools like OpenSSL unless a field description explicitly says otherwise.*
 
 | Field                              | Size (bytes) | Description |
 | ---------------------------------- | ------------ | ----------- |

hw-model/src/lib.rs

@@ -251,8 +251,14 @@ pub struct InitParams<'a> {
 
     pub otp_direct_access_cmd_reg_offset: u32,
 
-    // Keypairs for production debug unlock levels, from low to high
-    // ECC384 and MLDSA87 keypairs (in hardware format i.e. little-endian)
+    // Keypairs for production debug unlock levels, from low to high.
+    // These byte slices must match the exact bytes hashed into the production debug unlock
+    // public-key-hash fuses and sent in AUTH_DEBUG_UNLOCK_TOKEN.
+    // ECC384: 96 bytes in mailbox byte order, i.e. X||Y with each 4-byte group byte-reversed
+    // relative to the standard big-endian coordinate bytes. Example: if the raw ECC bytes begin
+    // `ab cd ef 01 23 45 67 89`, store them here as `01 ef cd ab 89 67 45 23`.
+    // MLDSA87: 2592 raw public-key bytes copied exactly as produced by the MLDSA implementation.
+    // Example: if the MLDSA bytes begin `72 c0 f1 3b 7d 93 7e 22`, store them here unchanged.
     pub prod_dbg_unlock_keypairs: Vec<(&'a [u8; 96], &'a [u8; 2592])>,
 
     // Whether or not to set the debug_intent signal.

rom/dev/README.md

@@ -366,18 +366,18 @@ The following flows are conducted when the ROM is operating in the production mo
 | Unlock Level             | 1            | Debug unlock Level (Number 1-8).                                                      |
 | Reserved                 | 3            | Reserved field.                                                                       |
 | Challenge                | 48           | Random number sent in `AUTH_DEBUG_UNLOCK_CHALLENGE` mailbox command payload.          |
-| 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). |
-| 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). |
-| 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). |
-| 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). |
+| 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). |
+| 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). |
+| 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). |
+| 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). |
 
 7. On receiving this payload, ROM performs the following validations:
     - Ensures the value in the `Length` field matches the size of the payload.
     - Confirms that the `Debug unlock level` is not zero and does not exceed the value specified in the `SS_NUM_OF_PROD_DEBUG_UNLOCK_AUTH_PK_HASHES` register.
     - Calculates the address of the public key hash fuse as follows: <br>
         **SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK_OFFSET register value + ( (Debug Unlock Level - 1) * SHA2-384 hash size (48 bytes) )**
     - Retrieves the SHA2-384 hash (48 bytes) from the calculated address using DMA assist.
-    - Computes the SHA2-384 hash of the message formed by concatenating the ECC and MLDSA public keys in the payload.
+    - 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.
     - 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.
     - Upon hash comparison failure, the ROM exits the payload validation flow and completes the mailbox command.
 
@@ -1296,7 +1296,7 @@ and are also **not** subject to dword reversal.
 
 For a detailed description of byte ordering conventions for all mailbox cryptographic fields
 (including ECC, ML-DSA, and SHA digest fields with OpenSSL examples), see the
-[Byte order of cryptographic fields](../runtime/README.md#byte-order-of-cryptographic-fields)
+[Byte order of cryptographic fields](../../runtime/README.md#byte-order-of-cryptographic-fields)
 section in the Runtime README.
 
 ### Computing public key hashes: step-by-step example
@@ -1835,6 +1835,127 @@ FUSE_VENDOR_PK_HASH. See
 [Public key hash byte ordering](#public-key-hash-byte-ordering-dword-reversal)
 for details and worked examples.
 
+##### Production debug unlock public key hashes: byte ordering
+
+The production debug unlock flow uses SHA2-384 hashes of the concatenated
+ECC and MLDSA public keys to authenticate debug unlock tokens. These hashes
+are stored in the MCI register bank at addresses computed from
+`SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK_OFFSET`.
+
+**Hash input construction:**
+
+The hash is SHA2-384 over the raw mailbox wire bytes of the concatenated
+ECC and MLDSA public keys from the `AUTH_DEBUG_UNLOCK_TOKEN` payload.
+The mailbox wire format for each key type is:
+
+- **ECC public key (96 bytes)**: Each 4-byte group of the X and Y
+  coordinates is **dword-reversed** from the standard OpenSSL output.
+
+  ```
+  openssl ec output:  AB CD EF 01  23 45 67 89  ...  (X, 48 bytes)
+                      11 22 33 44  55 66 77 88  ...  (Y, 48 bytes)
+
+  Hash input (= mailbox wire bytes):
+                      01 EF CD AB  89 67 45 23  ...  (X, dword-reversed)
+                      44 33 22 11  88 77 66 55  ...  (Y, dword-reversed)
+  ```
+
+- **MLDSA public key (2592 bytes)**: The native MLDSA key bytes are
+  used **as-is** — no conversion.
+
+  ```
+  MLDSA keygen output: 72 C0 F1 3B  7D 93 7E 22  ...
+
+  Hash input (= mailbox wire bytes):
+                       72 C0 F1 3B  7D 93 7E 22  ...  (identical)
+  ```
+
+To compute the same hash offline for fuse provisioning, reconstruct the
+mailbox wire bytes: dword-reverse the ECC coordinates, keep MLDSA native,
+concatenate, and hash:
+
+```
+ECC dword-reversed:      01 EF CD AB  89 67 45 23  ...  (96 bytes)
+MLDSA native:            72 C0 F1 3B  7D 93 7E 22  ...  (2592 bytes)
+
+hash_input = ECC_dword_reversed || MLDSA_native_bytes  (2688 bytes)
+
+$ openssl dgst -sha384 -binary combined.bin | xxd -p -c 48
+→ 3f7a2b91c4e8d0f5...
+```
+
+**Provisioning: OpenSSL example**
+
+To prepare `combined_keys.bin`, dword-reverse the ECC raw coordinates
+and concatenate with the native MLDSA key bytes. Then compute the hash:
+
+```
+$ openssl dgst -sha384 -binary combined_keys.bin | xxd -p -c 48
+3f7a2b91c4e8d0f5a1b2c3d4e5f60718293a4b5c6d7e8f90a0b1c2d3e4f5061728394a5b6c
+```
+
+Map the digest output to fuse register words — each 4-byte group becomes
+one `u32` fuse word (same convention as all other SHA digest fuses):
+
+```
+openssl output:     3f 7a 2b 91  c4 e8 d0 f5  a1 b2 c3 d4  ...
+                    ~~~~~~~~~~~  ~~~~~~~~~~~  ~~~~~~~~~~~
+Fuse word[0]:       0x3F7A2B91   [1]: 0xC4E8D0F5   [2]: 0xA1B2C3D4   ...
+```
+
+Write these 12 words to the MCI register bank at offset:
+
+```
+SS_PROD_DEBUG_UNLOCK_AUTH_PK_HASH_REG_BANK_OFFSET + ((level - 1) * 48)
+```
+
+**Mailbox payload: preparing fields from OpenSSL output**
+
+The `AUTH_DEBUG_UNLOCK_TOKEN` mailbox command fields use the byte order
+conventions described in
+[Byte order of cryptographic fields](../../runtime/README.md#byte-order-of-cryptographic-fields).
+The table below summarizes how to convert OpenSSL tool output into the
+mailbox payload bytes for each field:
+
+- **ECC P-384 public key (big-endian words)**: Extract the raw X and Y
+  coordinates (48 bytes each) from the PEM key, then **dword-reverse**
+  each 4-byte group before writing to the mailbox.
+
+  ```
+  # Extract raw X||Y from PEM (96 bytes, big-endian):
+  $ openssl ec -pubin -in key.pem -outform DER 2>/dev/null \
+      | tail -c 96 | xxd -p -c 48
+
+  OpenSSL raw bytes:  AB CD EF 01  23 45 67 89  ...  (X, 48 bytes)
+                      11 22 33 44  55 66 77 88  ...  (Y, 48 bytes)
+
+  Mailbox bytes:      01 EF CD AB  89 67 45 23  ...  (X, dword-reversed)
+                      44 33 22 11  88 77 66 55  ...  (Y, dword-reversed)
+  ```
+
+- **MLDSA-87 public key (little-endian words)**: Copy the raw key bytes
+  produced by an MLDSA implementation (e.g. OpenSSL 3.5+, `fips204` crate)
+  **directly** into the mailbox — no conversion needed.
+
+  ```
+  MLDSA key bytes:    72 C0 F1 3B  7D 93 7E 22  ...  (2592 bytes)
+  Mailbox bytes:      72 C0 F1 3B  7D 93 7E 22  ...  (identical)
+  ```
+
+- **ECC P-384 signature (big-endian words)**: Same treatment as the public
+  key — dword-reverse each 4-byte group of the R and S coordinates.
+
+- **MLDSA-87 signature (little-endian words)**: Copy raw signature bytes
+  directly — no conversion needed. The trailing byte (byte 4628) is
+  reserved and should be zero.
+
+**Note:** The hash used for fuse provisioning is computed over the exact
+same bytes that appear on the mailbox wire. There is no additional
+transformation — the SHA accelerator's internal endianness handling is
+transparent and produces `SHA384(wire_bytes)`. Therefore the provisioning
+hash and the runtime verification hash are both computed over
+`ECC_dword_reversed || MLDSA_native`.
+
 #### SVN fuses (little-endian 128-bit bitmap)
 
 **FUSE_FIRMWARE_SVN** and **FUSE_SOC_MANIFEST_SVN** are 128-bit one-hot encoded bitmaps stored

rom/dev/tests/rom_integration_tests/test_debug_unlock.rs

@@ -406,11 +406,11 @@ fn test_dbg_unlock_prod_success() {
     sha512.update(challenge.challenge);
     let sha512_digest = sha512.finalize();
 
-    // Sign the digest in the little endian format, as required by the hardware.
+    // Sign the raw SHA-512 digest bytes; MLDSA mailbox encoding happens when packing the signature.
     let mldsa_signature = signing_mldsa_key
         .try_sign_with_seed(&[0; 32], &sha512_digest, &[])
         .unwrap();
-    // Convert the signature slice to little endian dwords, as required by the hardware.
+    // Pack the signature bytes into little-endian u32 words for the mailbox field.
     let mldsa_signature = {
         let mut sig = [0; 4628];
         sig[..4627].copy_from_slice(&mldsa_signature);
@@ -580,13 +580,14 @@ fn test_dbg_unlock_prod_invalid_token_challenge() {
         pk[48..].copy_from_slice(ecc_key.y().unwrap());
         pk
     };
-    // Convert to hardware format i.e. little endian.
+    // Convert to hardware format i.e. big endian for ECC.
     let ecc_pub_key = u8_to_u32_be(&ecc_pub_key_bytes);
     let ecc_pub_key_bytes = ecc_pub_key.as_bytes();
 
     let (verifying_mldsa_key, _signing_mldsa_key) = fips204::ml_dsa_87::try_keygen().unwrap();
     let mldsa_pub_key_bytes = verifying_mldsa_key.into_bytes();
-    let mldsa_pub_key = u8_to_u32_be(&mldsa_pub_key_bytes);
+    // Convert to hardware format i.e. little endian for MLDSA.
+    let mldsa_pub_key = u8_to_u32_le(&mldsa_pub_key_bytes);
     let mldsa_pub_key_bytes = mldsa_pub_key.as_bytes();
 
     let security_state = *SecurityState::default()
@@ -710,15 +711,15 @@ fn test_dbg_unlock_prod_invalid_signature() {
         pk[48..].copy_from_slice(ecc_key.y().unwrap());
         pk
     };
-    // Convert to hardware format i.e. little endian.
+    // Convert to hardware format i.e. big endian for ECC.
     let ecc_pub_key = u8_to_u32_be(&ecc_pub_key_bytes);
     let ecc_pub_key_bytes = ecc_pub_key.as_bytes();
 
     let (verifying_mldsa_key, signing_mldsa_key) = fips204::ml_dsa_87::try_keygen().unwrap();
     let mldsa_pub_key_bytes = verifying_mldsa_key.into_bytes();
 
-    // Convert to hardware format i.e. little endian.
-    let mldsa_pub_key = u8_to_u32_be(&mldsa_pub_key_bytes);
+    // Convert to hardware format i.e. little endian for MLDSA.
+    let mldsa_pub_key = u8_to_u32_le(&mldsa_pub_key_bytes);
     let mldsa_pub_key_bytes = mldsa_pub_key.as_bytes();
 
     let security_state = *SecurityState::default()
@@ -878,7 +879,7 @@ fn test_dbg_unlock_prod_wrong_public_keys() {
 
     let (different_verifying_mldsa_key, _) = fips204::ml_dsa_87::try_keygen().unwrap();
     let different_mldsa_pub_key_bytes = different_verifying_mldsa_key.into_bytes();
-    let different_mldsa_pub_key = u8_to_u32_be(&different_mldsa_pub_key_bytes);
+    let different_mldsa_pub_key = u8_to_u32_le(&different_mldsa_pub_key_bytes);
 
     let security_state = *SecurityState::default()
         .set_debug_locked(true)
@@ -995,14 +996,14 @@ fn test_dbg_unlock_prod_wrong_cmd() {
         pk[48..].copy_from_slice(ecc_key.y().unwrap());
         pk
     };
-    // Convert to hardware format i.e. little endian.
+    // Convert to hardware format i.e. big endian for ECC.
     let ecc_pub_key = u8_to_u32_be(&ecc_pub_key_bytes);
     let ecc_pub_key_bytes = ecc_pub_key.as_bytes();
 
     let (verifying_mldsa_key, _signing_mldsa_key) = fips204::ml_dsa_87::try_keygen().unwrap();
     let mldsa_pub_key_bytes = verifying_mldsa_key.into_bytes();
-    // Convert to hardware format i.e. little endian.
-    let mldsa_pub_key = u8_to_u32_be(&mldsa_pub_key_bytes);
+    // Convert to hardware format i.e. little endian for MLDSA.
+    let mldsa_pub_key = u8_to_u32_le(&mldsa_pub_key_bytes);
     let mldsa_pub_key_bytes = mldsa_pub_key.as_bytes();
 
     let security_state = *SecurityState::default()
@@ -1170,9 +1171,7 @@ fn test_dbg_unlock_prod_unlock_levels_success() {
         sha512.update(challenge.challenge);
         let sha512_digest = sha512.finalize();
 
-        // Convert to hardware format i.e. big endian before signing for MLDSA.
-        // let binding = u8_to_u32_be(&sha512_digest);
-        // let msg = binding.as_bytes();
+        // No byte swapping is needed before MLDSA signing; sign the raw SHA-512 digest bytes.
 
         let mldsa_signature = signing_mldsa_key
             .try_sign_with_seed(&[0; 32], &sha512_digest, &[])

runtime/README.md

@@ -2880,8 +2880,8 @@ Command Code: `0x5357_4545` ("SWEE")
 | **Name**             | **Type** | **Description** |
 | --------             | -------- | --------------- |
 | chksum               | u32      | Checksum over other input arguments, computed by the caller. Little endian.         |
-| exported_cdi_handle  | u8[32]   | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
-| tbs                  | u8[48]   | The bytes to be signed. Little endian.                                              |
+| exported_cdi_handle  | u8[32]   | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
+| tbs                  | u8[48]   | The 48-byte SHA-384 digest to be signed. Raw byte array; no byte swapping is required. |
 
 *Table: `SIGN_WITH_EXPORTED_ECDSA` output arguments*
 | **Name**           | **Type** | **Description** |
@@ -2904,7 +2904,7 @@ Command Code: `5256_4348` ("RVCH")
 | **Name**             | **Type** | **Description** |
 | --------             | -------- | --------------- |
 | chksum               | u32      | Checksum over other input arguments, computed by the caller. Little endian.         |
-| exported_cdi_handle  | u8[32]   | The Exported CDI handle returned by the DPE `DeriveContext` command. Little endian. |
+| exported_cdi_handle  | u8[32]   | The exported CDI handle returned by the DPE `DeriveContext` command. Opaque byte array; copy the bytes exactly as returned. |
 
 The `exported_cdi` can be created by calling `DeriveContext` with the `export-cdi` and `create-certificate` flags.
 

runtime/tests/runtime_integration_tests/test_debug_unlock.rs

@@ -580,7 +580,7 @@ fn test_dbg_unlock_prod_wrong_public_keys() {
 
     let (different_verifying_mldsa_key, _) = fips204::ml_dsa_87::try_keygen().unwrap();
     let different_mldsa_pub_key_bytes = different_verifying_mldsa_key.into_bytes();
-    let different_mldsa_pub_key = u8_to_u32_be(&different_mldsa_pub_key_bytes);
+    let different_mldsa_pub_key = u8_to_u32_le(&different_mldsa_pub_key_bytes);
 
     let security_state = *SecurityState::default()
         .set_debug_locked(true)

sw-emulator/lib/periph/src/mci.rs

@@ -359,7 +359,7 @@ impl MciRegs {
                     // Copy hash into fuses array (64 bytes / 16 u32s)
                     let base_idx = i * (SS_MANUF_DBG_UNLOCK_FUSE_SIZE / size_of::<u32>());
                     hash.chunks(4).enumerate().for_each(|(j, chunk)| {
-                        // Program the hash in hardware format i.e. little endian.
+                        // Program the hash as big-endian u32 words; the bus presents each word's bytes little-endian at byte addresses.
                         let value = u32::from_be_bytes(chunk.try_into().unwrap());
                         fuses[base_idx + j] = value;
                     });