csr hmac signing key (#630)

* csr hmac signing key implementation
uvm hmac collaterals updated to validate the new flow

* MICROSOFT AUTOMATED PIPELINE: Stamp 'user/dev/michnorris/csr_hmac_key' with updated timestamp and hash after successful run

* adding swwe to all control bits so they can only be set when ready

* MICROSOFT AUTOMATED PIPELINE: Stamp 'user/dev/michnorris/csr_hmac_key' with updated timestamp and hash after successful run

* updating specifications for csr hmac key and key vault changes

* details about csr mode in hw spec

* MICROSOFT AUTOMATED PIPELINE: Stamp 'user/dev/michnorris/csr_hmac_key' with updated timestamp and hash after successful run

.github/workflow_metadata/pr_hash

@@ -1 +1 @@
-4728a2efeb9500d84266322c96de495e0f68008b89cd1f904d80278204eb3c85f632cd345a024cd70b2374e236799542
+82be4e878bee59a14221f09dcddc6eb0a64c67ff0418a3e933e58973d94a5c7a2f5bc75fccf00fa98301a4ed55208e6e

.github/workflow_metadata/pr_timestamp

@@ -1 +1 @@
-1731535119
+1731604164

docs/CaliptraHardwareSpecification.md

@@ -33,6 +33,7 @@ For information on the Caliptra Core, see the [High level architecture](https://
     * Read logic for Secret Fuses
     * Streaming Boot Support
 * RISC-V core PMP support
+* CSR HMAC key for manufacturing flow
 
 ## Boot FSM
 
@@ -258,7 +259,7 @@ When Caliptra is in debug mode:
 
 * Caliptra JTAG is opened for the microcontroller and HW debug.
 
-* Device secrets (UDS, FE, key vault, and obfuscation key) are programmed to debug values.
+* Device secrets (UDS, FE, key vault, csr hmac key and obfuscation key) are programmed to debug values.
 
 If a transition to debug mode happens during ROM operation, any values computed from the use of device secrets may not match expected values.
 
@@ -269,6 +270,7 @@ Debug mode values may be set by integrators in the Caliptra configuration files.
 | Name                        | Default value |
 | :-------------------------- | :------------ |
 | Obfuscation Key Debug Value | All 0x1       |
+| CSR HMAC Key Debug Value    | All 0x1       |
 | UDS Debug Value             | All 0x1       |
 | Field Entropy Debug Value   | All 0x1       |
 | Key Vault Debug Value 0     | All 0xA       |
@@ -824,24 +826,30 @@ The HMAC architecture has the finite-state machine as shown in the following fig
 
 ![](./images/HMAC_FSM.png)
 
+### CSR Mode
+
+When the CSR Mode register is set, the HMAC512 core uses the value latched from the cptra_csr_hmac_key interface pins in place of the API key register. These pins are latched internally after powergood assertion during DEVICE_MANUFACTURING lifecycle state. During debug mode operation this value is overridden with all 1's, and during any other lifecycle state it has a value of zero.
+
 ### Signal descriptions
 
 The HMAC architecture inputs and outputs are described in the following table.
 
-| Name               | Input or output | Description  |
-| :----------------- | :-------------- | :----------- |
-| clk                | input           | All signal timings are related to the rising edge of clk.                                                                                                                   |
-| reset_n            | input           | The reset signal is active LOW and resets the core. This is the only active LOW signal.                                                                                     |
-| init               | input           | The core is initialized and processes the key and the first block of the message.                                                                                           |
-| next               | input           | The core processes the rest of the message blocks using the result from the previous blocks.                                                                                |
-| zeroize            | input           | The core clears all internal registers to avoid any SCA information leakage.                                                                                                |
-| mode               | input           | Indicates the hmac type of the function. This can be: <br>- HMAC384 <br>- HMAC512.                                                                                          |
-| key\[511:0\]       | input           | The input key.                                                                                                                                                              |
-| block\[1023:0\]    | input           | The input padded block of message.                                                                                                                                          |
-| LFSR_seed\[383:0\] | Input           | The input to seed PRNG to enable the masking countermeasure for SCA protection.                                                                                             |
-| ready              | output          | When HIGH, the signal indicates the core is ready.                                                                                                                          |
-| tag\[511:0\]       | output          | The HMAC value of the given key or block. For PRF-HMAC-SHA-512, a 512-bit tag is required. For HMAC-SHA-512-256, the host is responsible for reading 256 bits from the MSB. |
-| tag_valid          | output          | When HIGH, the signal indicates the result is ready.                                                                                                                        |
+| Name                        | Input or output | Description  |
+| :-------------------------- | :-------------- | :----------- |
+| clk                         | input           | All signal timings are related to the rising edge of clk.                                                                                                                   |
+| reset_n                     | input           | The reset signal is active LOW and resets the core. This is the only active LOW signal.                                                                                     |
+| init                        | input           | The core is initialized and processes the key and the first block of the message.                                                                                           |
+| next                        | input           | The core processes the rest of the message blocks using the result from the previous blocks.                                                                                |
+| zeroize                     | input           | The core clears all internal registers to avoid any SCA information leakage.                                                                                                |
+| csr_mode                    | input           | When set, the key comes from the cptra_csr_hmac_key interface pins. This key is valid only during MANUFACTURING mode.                                                       |
+| mode                        | input           | Indicates the hmac type of the function. This can be: <br>- HMAC384 <br>- HMAC512.                                                                                          |
+| cptra_csr_hmac_key\[511:0\] | input           | The key to be used during csr mode.                                                                                                                                         |
+| key\[511:0\]                | input           | The input key.                                                                                                                                                              |
+| block\[1023:0\]             | input           | The input padded block of message.                                                                                                                                          |
+| LFSR_seed\[383:0\]          | Input           | The input to seed PRNG to enable the masking countermeasure for SCA protection.                                                                                             |
+| ready                       | output          | When HIGH, the signal indicates the core is ready.                                                                                                                          |
+| tag\[511:0\]                | output          | The HMAC value of the given key or block. For PRF-HMAC-SHA-512, a 512-bit tag is required. For HMAC-SHA-512-256, the host is responsible for reading 256 bits from the MSB. |
+| tag_valid                   | output          | When HIGH, the signal indicates the result is ready.                                                                                                                        |
 
 ### Address map
 
@@ -1341,8 +1349,8 @@ Key Vault (KV) is a register file that stores the keys to be used by the microco
 
 | KV register                       | Description                                               |
 | :-------------------------------- | :-------------------------------------------------------- |
-| Key Control\[31:0\]               | 32 Control registers, 32 bits each                        |
-| Key Entry\[31:0\]\[11:0\]\[31:0\] | 32 Key entries, 384 bits each <br>No read or write access |
+| Key Control\[23:0\]               | 24 Control registers, 32 bits each                        |
+| Key Entry\[23:0\]\[15:0\]\[31:0\] | 24 Key entries, 512 bits each <br>No read or write access |
 
 ### Key vault functional block
 

docs/CaliptraIntegrationSpecification.md

@@ -161,7 +161,8 @@ The following tables describe the interface signals.
 
 | Signal name | Width | Driver  | Synchronous (as viewed from Caliptra’s boundary) | Description |
 | :--------- | :--------- | :--------- | :--------- | :--------- |
-| CPTRA_OBF_KEY | 256 | Input Strap | Asynchronous | Obfuscation key is driven by SoC at integration time. Ideally this occurs just before tape-in and the knowledge of this key must be protected unless PUF is driving this. The key is latched by Caliptra on caliptra powergood deassertion. It is cleared after its use and can only re-latched on a power cycle (powergood deassertion to assertion). |
+| CPTRA_OBF_KEY | 256 | Input Strap | Asynchronous | Obfuscation key is driven by SoC at integration time. Ideally this occurs just before tape-in and the knowledge of this key must be protected unless PUF is driving this. The key is latched by Caliptra on caliptra powergood assertion. It is cleared after its use and can only re-latched on a power cycle (powergood deassertion to assertion). |
+| CPTRA_CSR_HMAC_KEY | 512 | Input Strap | Asynchronous | CSR HMAC key is driven by SoC at integration time. Ideally this occurs just before tape-in and the knowledge of this key must be protected unless PUF is driving this. The key is latched by Caliptra on caliptra powergood assertion during DEVICE_MANUFACTURING lifecycle state. |
 | SECURITY_STATE | 3 | Input Strap | Synchronous to clk | Security state that Caliptra should take (for example, manufacturing, secure, unsecure, etc.). The key is latched by Caliptra on cptra_noncore_rst_b deassertion. Any time the state changes to debug mode, all keys, assets, and secrets stored in fuses or key vault are cleared. Cryptography core states are also flushed if they were being used. |
 | scan_mode | 1 | Input Strap | Synchronous to clk | Must be set before entering scan mode. This is a separate signal than the scan chain enable signal that goes into scan cells. This allows Caliptra to flush any assets or secrets present in key vault and flops if the transition is happening from a secure state. |
 | GENERIC_INPUT_WIRES | 64 | Input | Synchronous to clk | Placeholder of input wires for late binding features. These values are reflected into registers that are exposed to firmware. |
@@ -236,6 +237,14 @@ The key must follow the security rules defined in the[ Caliptra architectural sp
 
 SoC must ensure that there are no SCAN cells on the flops that latch this key internally to Caliptra.
 
+### CSR HMAC key
+
+SoC drives the key at the tape-in time of the SoC using an Engineering Change Order (ECO) and must be protected from common knowledge. For a given SoC construction, this can be driven using a PUF too.
+
+The key must follow the security rules defined in the[ Caliptra architectural specification](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html).
+
+SoC must ensure that there are no SCAN cells on the flops that latch this key internally to Caliptra.
+
 ## Late binding interface signals
 
 The interface signals GENERIC\_INPUT\_WIRES and GENERIC\_OUTPUT\_WIRES are placeholders on the SoC interface reserved for late binding features. This may include any feature that is required for correct operation of the design in the final integrated SoC and that may not be accommodated through existing interface signaling (such as the mailbox).

src/hmac/rtl/hmac.sv

@@ -34,6 +34,9 @@ module hmac
         input wire           reset_n,
         input wire           cptra_pwrgood,
 
+        //csr key
+        input logic [`CLP_CSR_HMAC_KEY_DWORDS-1:0][31:0] cptra_csr_hmac_key,
+
         // Control.
         input wire           cs,
         input wire           we,
@@ -230,6 +233,11 @@ always_comb begin
   hwif_in.HMAC512_NAME[1].NAME.next = HMAC_CORE_NAME[63:32];
   hwif_in.HMAC512_VERSION[0].VERSION.next = HMAC_CORE_VERSION[31:0];
   hwif_in.HMAC512_VERSION[1].VERSION.next = HMAC_CORE_VERSION[63:32];
+  //Only allow setting CSR MODE when ready is set
+  hwif_in.HMAC512_CTRL.CSR_MODE.swwe = ready_reg;
+  hwif_in.HMAC512_CTRL.INIT.swwe = ready_reg;
+  hwif_in.HMAC512_CTRL.NEXT.swwe = ready_reg;
+  hwif_in.HMAC512_CTRL.MODE.swwe = ready_reg;
 
   //assign hardware readable registers to drive hmac core
   //mask the command until kv clients are idle
@@ -280,7 +288,7 @@ always_comb begin
   hwif_in.HMAC512_KV_WR_CTRL.write_en.hwclr = ~kv_write_ready;
   //assign hardware readable registers to drive hmac core
   for (int dword=0; dword < KEY_NUM_DWORDS; dword++) begin
-    key_reg[dword] = hwif_out.HMAC512_KEY[dword].KEY.value;
+    key_reg[dword] = hwif_out.HMAC512_CTRL.CSR_MODE.value ? cptra_csr_hmac_key[dword] : hwif_out.HMAC512_KEY[dword].KEY.value;
   end
   for (int dword=0; dword < BLOCK_NUM_DWORDS; dword++)begin
     block_reg[dword] = hwif_out.HMAC512_BLOCK[dword].BLOCK.value;
@@ -293,8 +301,8 @@ end
 
 always_comb begin
   unique case (mode_reg)
-    1'b0 :     get_mask = {{12{32'hffffffff}}, {4{32'h00000000}}};  //SHA384
-    default :  get_mask = {16{32'hffffffff}};                       //SHA512
+    1'b0 :     get_mask = {{12{32'hffffffff}}, {4{32'h00000000}}};  //HMAC384
+    default :  get_mask = {16{32'hffffffff}};                       //HMAC512
   endcase
 end
 

src/hmac/rtl/hmac_ctrl.sv

@@ -37,6 +37,9 @@ module hmac_ctrl
     input wire           reset_n,
     input wire           cptra_pwrgood,
 
+    //csr key
+    input logic [`CLP_CSR_HMAC_KEY_DWORDS-1:0][31:0] cptra_csr_hmac_key,
+
     // from SLAVES PORT
     input logic [AHB_ADDR_WIDTH-1:0] haddr_i,
     input logic [AHB_DATA_WIDTH-1:0] hwdata_i,
@@ -81,6 +84,7 @@ module hmac_ctrl
         .clk(clk),
         .reset_n(reset_n),
         .cptra_pwrgood(cptra_pwrgood),
+        .cptra_csr_hmac_key(cptra_csr_hmac_key),
         .cs(hmac_cs),
         .we(hmac_we),
         .address(hmac_address),

src/hmac/rtl/hmac_reg.rdl

@@ -72,18 +72,19 @@ addrmap hmac_reg {
                                 processing for the key and the first padded 
                                 message block.
                                 [br] Software write generates only a single-cycle pulse on the 
-                                hardware interface and then will be erased"; singlepulse;} INIT = 1'b0;
+                                hardware interface and then will be erased"; singlepulse; swwe;} INIT = 1'b0;
         field {desc = "Control next command bit: ​Trigs the HMAC512 core to start the 
                                 processing for the remining padded message block.
                                 [br] Software write generates only a single-cycle pulse on the 
-                                hardware interface and then will be erased"; singlepulse;} NEXT = 1'b0;
+                                hardware interface and then will be erased"; singlepulse; swwe;} NEXT = 1'b0;
         field {desc = "Zeroize all internal registers: Zeroize all internal registers after HMAC process, to avoid SCA leakage.
                                 [br] Software write generates only a single-cycle pulse on the 
                                 hardware interface and then will be erased"; singlepulse;} ZEROIZE = 1'b0;
         field {desc = "Control mode command bits: Indicates the HMAC512 core to set dynamically
                                  the type of hashing algorithm. This can be:
                                  0 for HMAC384
-                                 1 for HMAC512";} MODE = 1'b1;
+                                 1 for HMAC512"; swwe;} MODE = 1'b1;
+        field {desc = "CSR Mode: Indicates to the HMAC512 core to use the CSR HMAC key"; swwe;} CSR_MODE = 1'b0;
         field {desc = "Reserved";} Reserved = 1'b0;                                 
 
     } HMAC512_CTRL @0x00000010;