Changes to Hardware Specification

Comparing version 2.1 to 2.0
+1257 additions -235 deletions
@@ -1,12 +1,12 @@
11 <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-rtl/blob/35b0bc5691b2bd0fc180403914cfabe207379089/docs/CaliptraHardwareSpecification.md" target="_blank">chipsalliance/caliptra-rtl/docs/CaliptraHardwareSpecification.md</a> @ <code>35b0bc5</code>
2+📄 Source: <a href="https://github.com/chipsalliance/caliptra-rtl/blob/bcd1a0c2dd897c2f378ad068c28a3452342111d2/docs/CaliptraHardwareSpecification.md" target="_blank">chipsalliance/caliptra-rtl/docs/CaliptraHardwareSpecification.md</a> @ <code>bcd1a0c</code>
33 </div>
44
55 ![OCP Logo](../images/caliptra-rtl/docs/images/OCP_logo.png)
66
77 <p style="text-align: center;">Caliptra Hardware Specification</p>
88
9-<p style="text-align: center;">Revision 2.0.3</p>
9+<p style="text-align: center;">Revision 2.1</p>
1010
1111 <div style="page-break-after: always"></div>
1212
@@ -28,10 +28,10 @@
2828 * Caliptra uC may use internally in mailbox mode or via the Caliptra AXI DMA assist engine in streaming mode
2929 * SHA Accelerator adds new SHA save/restore functionality
3030 * Adams Bridge Dilithium/ML-DSA (refer to [Adams bridge spec](https://github.com/chipsalliance/adams-bridge/blob/main/docs/AdamsBridgeHardwareSpecification.md))
31-* Subsystem mode support (refer to [Subsystem Specification](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/Caliptra%202.0%20Subsystem%20Specification%201.pdf) for details)
31+* Subsystem mode support (refer to [Subsystem Specification](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSIntegrationSpecification.md) for details)
3232 * ECDH hardware support
3333 * HMAC512 hardware support
34- * AXI Manager with DMA support (refer to [DMA Specification](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSHardwareSpecification.md#caliptra-axi-manager--dma-assist))
34+ * AXI Manager with DMA support (refer to [DMA Specification](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSHardwareSpecification.md#caliptra-core-axi-manager--dma-assist))
3535 * Manufacturing and Debug Unlock
3636 * UDS programming
3737 * Read logic for Secret Fuses
@@ -39,29 +39,41 @@
3939 * RISC-V core PMP support
4040 * CSR HMAC key for manufacturing flow
4141
42+## Key Caliptra 2.1 Changes
43+* AXI Manager DMA AES feature for OCP L.O.C.K. support (refer to [DMA Specification](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSHardwareSpecification.md#caliptra-core-axi-manager--dma-assist))
44+* [AES Big Endian mode](#aes-endian)
45+* [External Staging Area](./CaliptraIntegrationSpecification.md#external-staging-area)
46+* [OCP LOCK Support](#ocp-lock-hardware-architecture)
47+* [SHA3](#sha3)
48+* [ML-KEM](#adams-bridge-kyber-ml-kem)
49+
50+## Pre-release Features
51+* [Key Vault Boot Flow Transition Enforcement](#key-vault-boot-flow-transition-enforcement) -- HW-enforced DICE key integrity monitoring and slot access control across boot phases
52+
53+
4254 ## Boot FSM
4355
4456 The Boot FSM detects that the SoC is bringing Caliptra out of reset. Part of this flow involves signaling to the SoC that Caliptra is awake and ready for fuses. After fuses are populated and the SoC indicates that it is done downloading fuses, Caliptra can wake up the rest of the IP by de-asserting the internal reset.
4557
46-The following figure shows the initial power-on arc of the Mailbox Boot FSM.
47-
48-*Figure 1: Mailbox Boot FSM state diagram*
49-
50-![](../images/caliptra-rtl/docs/images/HW_mbox_boot_fsm.png)
58+The following figure shows the state transitions and associated actions in Caliptra's boot state machine.
59+
60+*Figure: Caliptra Boot FSM state diagram*
61+
62+![](../images/caliptra-rtl/docs/images/Caliptra_boot_fsm.png)
5163
5264 The Boot FSM first waits for the SoC to assert cptra\_pwrgood and de-assert cptra\_rst\_b. In the BOOT\_FUSE state, Caliptra signals to the SoC that it is ready for fuses. After the SoC is done writing fuses, it sets the fuse done register and the FSM advances to BOOT\_DONE.
5365
54-BOOT\_DONE enables Caliptra reset de-assertion through a two flip-flop synchronizer.
55-
56-## FW update reset (Impactless FW update)
57-
58-When a firmware update is initiated, Runtime FW writes to fw\_update\_reset register to trigger the FW update reset. When this register is written, only the RISC-V core is reset using cptra\_uc\_fw\_rst\_b pin and all AHB targets are still active. All registers within the targets and ICCM/DCCM memories are intact after the reset. Reset is deasserted synchronously after a programmable number of cycles; the minimum allowed number of wait cycles is 5, which is also the default configured value. Reset de-assertion is done through a two flip-flop synchronizer. Since ICCM is locked during runtime, the boot FSM unlocks it when the RISC-V reset is asserted. Following FW update reset deassertion, normal boot flow updates the ICCM with the new FW from the mailbox SRAM. The boot flow is modified as shown in the following figure.
59-
60-*Figure 2: Mailbox Boot FSM state diagram for FW update reset*
61-
62-![](../images/caliptra-rtl/docs/images/mbox_boot_fsm_FW_update_reset.png)
66+Once in the BOOT\_DONE state, Caliptra de-asserts resets through a two flip-flop synchronizer.
67+
68+### FW update reset (Impactless FW update)
69+
70+When a firmware update is initiated, Runtime FW writes to fw\_update\_reset register to trigger the FW update reset. When this register is written, only the RISC-V core is reset using cptra\_uc\_rst\_b pin and all AHB targets are still active. All registers within the targets and ICCM/DCCM memories are intact after the reset. Reset is deasserted synchronously after a programmable number of cycles; the minimum allowed number of wait cycles is 5, which is also the default configured value. Reset de-assertion is done through a two flip-flop synchronizer. Since ICCM is locked during runtime, the boot FSM unlocks it when the RISC-V reset is asserted. Following FW update reset deassertion, normal boot flow updates the ICCM with the new FW from the mailbox SRAM.
6371
6472 Impactless firmware updates may be initiated by writing to the fw\_update\_reset register after Caliptra comes out of global reset and enters the BOOT\_DONE state. In the BOOT\_FWRST state, only the reset to the RISC-V core is asserted and the wait timer is initialized. After the timer expires, the FSM advances from the BOOT\_WAIT to BOOT\_DONE state where the reset is deasserted and ICCM is unlocked.
73+
74+### Breakpoints for Debug
75+
76+Integrators may connect a breakpoint input to Caliptra, which is intended to connect to a chip GPIO pin. When asserted, this pin causes the Caliptra boot FSM to follow a modified arc. Instead of transitioning immediately to the BOOT_DONE state upon completion of fuse programming, the state machine transitions from BOOT_FUSE to BOOT_WAIT. Here, the state machine halts until the Caliptra register [CPTRA_BOOTFSM_GO](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.CPTRA_BOOTFSM_GO) is set, either by AXI or TAP access.
6577
6678 ## RISC-V core
6779
@@ -81,6 +93,11 @@
8193 | Fast Interrupt Redirect | Enabled |
8294 | External Interrupts | 31 |
8395 | PMP | Enabled |
96+| Dual-Core Lockstep | Enabled |
97+| RF Read Port Comparison | Enabled |
98+| DCCM Write-Readback | Disabled |
99+| DCCM Address Infection | Disabled |
100+| ICCM Address Infection | Disabled |
84101
85102
86103 ### Embedded memory export
@@ -116,8 +133,9 @@
116133 | Data Vault | 5 | 8 KiB | 0x1001_C000 | 0x1001_DFFF |
117134 | SHA512 | 6 | 32 KiB | 0x1002_0000 | 0x1002_7FFF |
118135 | SHA256 | 10 | 32 KiB | 0x1002_8000 | 0x1002_FFFF |
119-| ML-DSA | 14 | 64 KiB | 0x1003_0000 | 0x1003_FFFF |
136+| ABR (MLDSA/MLKEM) | 14 | 64 KiB | 0x1003_0000 | 0x1003_FFFF |
120137 | AES | 15 | 4 KiB | 0x1001_1000 | 0x1001_1FFF |
138+| SHA3 | 16 | 4 KiB | 0x1004_0000 | 0x1004_0FFF |
121139
122140
123141 #### Peripherals subsystem
@@ -196,12 +214,44 @@
196214 | Mailbox (Notifications) | 20 | 7 |
197215 | SHA512 Accelerator (Errors) | 23 | 8 |
198216 | SHA512 Accelerator (Notifications) | 24 | 7 |
199-| MLDSA (Errors) | 23 | 8 |
200-| MLDSA (Notifications) | 24 | 7 |
217+| ABR (MLDSA/MLKEM) (Errors) | 23 | 8 |
218+| ABR (MLDSA/MLKEM) (Notifications) | 24 | 7 |
201219 | AXI DMA (Errors) | 25 | 8 |
202220 | AXI DMA (Notifications) | 26 | 7 |
203221
204222
223+### Fault tolerance and FI hardening
224+
225+The Caliptra VeeR EL2 configuration provides several fault-injection (FI) hardening features. These are compile-time properties of the delivered core configuration (enabled by defines in the auto-generated [common_defines.sv](../src/riscv_core/veer_el2/rtl/common_defines.sv)), not integrator-tunable options. Dual-core lockstep (DCLS) is enabled through `dcls_en` in both passive and subsystem profiles. The **DCCM write-readback** and **DCCM / ICCM address-XOR integrity** features are **disabled in this release** until the features mature - they are compiled out of the delivered configuration and are documented below for reference. All three are described below.
226+
227+#### Dual-core lockstep (DCLS)
228+
229+The RISC-V core is instantiated in a dual-core lockstep (DCLS) configuration. A redundant *shadow* core is driven with the same input stream as the main core, offset by a fixed number of pipeline stages. The main core's outputs are delayed by the same offset and compared cycle-by-cycle against the shadow core's outputs; any divergence indicates a fault in one of the cores. Tying `dcls_en` low may allow synthesis to remove the shadow core and comparison logic. The shadow core is not architecturally visible and drives no system state; it exists solely for comparison.
230+
231+The `dcls_en` input enables DCLS in both passive and subsystem profiles (`1` = enabled, `0` = disabled), controlling normal mismatch reporting. Integrators may tie it low or high, or drive it from a synchronous SoC register. The sampled enable is reflected read-only to firmware and the SoC in [CPTRA_HW_CONFIG](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.CPTRA_HW_CONFIG)`.DCLS_en`. The comparison logic fails safe: an invalid multi-bit encoding on the internal disable control is treated as a detected corruption.
232+
233+In scan mode (`scan_mode` = 1), the shadow core's resets are driven directly by the reset inputs so that they are controllable for scan test. The shadow core is then no longer aligned to the main core. Corruption detection is therefore suspended while `scan_mode` is set, and remains suspended until the next Caliptra reset after `scan_mode` is cleared.
234+
235+While detection is enabled, a detected mismatch asserts [CPTRA_HW_ERROR_FATAL](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.CPTRA_HW_ERROR_FATAL)`.rv_dcls_err` (bit [7]; see [Error register summary](#error-register-summary)) and raises the `cptra_error_fatal` interrupt to the SoC. The status bit and the interrupt clear independently: the bit is RW1C, so Caliptra firmware or the SoC can clear it, but its reset is `cptra_pwrgood`, so it survives a warm Caliptra reset. The interrupt has no clear mechanism by design — clearing the status bit does not deassert it, and it deasserts only on a Caliptra reset.
236+
237+#### DCCM write-readback
238+
239+> **Disabled in this release:** the DCCM write-readback feature is compiled out of the delivered core configuration (`RV_DCCM_WR_READBACK` is not set) and is inactive until the feature matures. The description below applies when the feature is re-enabled in a future release.
240+
241+The DCCM store path is protected by a write-readback check (enabled by `RV_DCCM_WR_READBACK`). After a store commits to the DCCM, the hardware reads the target location back and compares it against the data that was intended to be written; a mismatch indicates the store was corrupted (for example, by a fault injected on the write datapath) and is reported as a fault.
242+
243+When compiled in, the write-readback check is *enabled out of reset*. It can be disabled at runtime through bit [7] of the microarchitectural feature-disable CSR (`MFDC`, `dec_tlu_dccm_wr_readback_disable`), which is internal to the core and accessible only to code running on the RISC-V core. The core does not take an internal trap on the mismatch; the fault is reported solely through the exported error pin described below.
244+
245+A detected mismatch asserts [CPTRA_HW_ERROR_FATAL](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.CPTRA_HW_ERROR_FATAL)`.dccm_wr_readback_err` (bit [8]; see [Error register summary](#error-register-summary)) and raises the `cptra_error_fatal` interrupt to the SoC. The status bit and the interrupt clear independently: the bit is RW1C, so Caliptra firmware or the SoC can clear it, but its reset is `cptra_pwrgood`, so it survives a warm Caliptra reset. The interrupt has no clear mechanism by design — clearing the status bit does not deassert it, and it deasserts only on a Caliptra reset. The interrupt assertion can be masked by firmware via [internal_hw_error_fatal_mask](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.internal_hw_error_fatal_mask)`.mask_dccm_wr_readback_err`; masking suppresses only the interrupt output, not the sticky status bit.
246+
247+#### DCCM / ICCM address-XOR integrity
248+
249+> **Disabled in this release:** the DCCM/ICCM address-XOR integrity scheme is compiled out of the delivered core configuration (`RV_DCCM_ADDR_XOR` and `RV_ICCM_ADDR_XOR` are not set) and is inactive until the feature matures. The description below applies when the feature is re-enabled in a future release.
250+
251+The core's tightly-coupled memories are protected by an address-XOR integrity scheme (enabled by `RV_DCCM_ADDR_XOR` and `RV_ICCM_ADDR_XOR`). On a write, the replicated word address is XOR-folded into the stored data bits before the ECC codeword is formed; on a read, the same address is XOR-ed back out before the ECC check. When the read address matches the address used at write time, the original data is recovered and the ECC check passes. If a fault causes an access to resolve to the wrong line (for example, an address-decode glitch), the recovered data is garbled and the existing ECC logic flags it as an uncorrectable error — converting a silent mis-address into a detectable fault. Such errors surface through the standard uncorrectable-ECC reporting path (`CPTRA_HW_ERROR_FATAL.dccm_ecc_unc` for DCCM, `iccm_ecc_unc` for ICCM).
252+
253+> **Backdoor-access note:** while this feature is enabled, any access to DCCM/ICCM that bypasses the core's normal datapath (testbench preload, external loader, debug read/write, memory dump) must apply the address-XOR itself - XOR the data with the replicated word address on write, and de-XOR it on read.
254+
205255 ## Watchdog timer
206256
207257 The primary function of Caliptra Watchdog Timer (WDT) is to reset the microcontroller (Caliptra), in the event of a software malfunction, by resetting the device if it has not been cleared in software. It is a two-stage timer, independent of the RISCV core.
@@ -220,7 +270,7 @@
220270
221271 The following figure shows the two timers.
222272
223-*Figure 3: Caliptra Watchdog Timer*
273+*Figure: Caliptra Watchdog Timer*
224274
225275 ![](../images/caliptra-rtl/docs/images/WDT.png)
226276
@@ -266,11 +316,21 @@
266316
267317 ## Security state
268318
269-Caliptra uses the MSB of the security state input to determine whether or not Caliptra is in debug mode.
270-
271-When Caliptra is in debug mode:
272-
273-* Security state MSB is set to 0.
319+The security state input is a packed value encoded as `{debug_locked[3:0], device_lifecycle[1:0]}`. Caliptra uses the `debug_locked` field to determine whether or not Caliptra is in debug mode.
320+
321+To harden this security-critical decision against fault-injection (glitch) attacks, `debug_locked` is a multi-bit (MuBi4) encoded value rather than a single bit:
322+
323+* `debug_locked` = `4'h6` (MuBi4True) &rarr; debug is **locked** (secure).
324+* `debug_locked` = `4'h9` (MuBi4False) &rarr; debug is **unlocked** (debug mode).
325+
326+The two legal encodings are bitwise complements, so a single- or multi-bit glitch is unlikely to convert one legal value into the other. Caliptra evaluates the field with a fail-secure policy:
327+
328+* The "debug unlocked" decision uses a *strict* test: only the exact `4'h9` encoding unlocks debug. Any other value (including any invalid encoding) leaves debug locked.
329+* The "debug locked" decision uses a *loose* test: `4'h6` and any invalid encoding are all treated as locked.
330+
331+Consequently, any value other than the two legal MuBi4 encodings resolves to debug **locked**. Integrators must drive one of the two legal MuBi4 values on the external `security_state` strap; see the Caliptra Integration Specification for the strap layout.
332+
333+When Caliptra is in debug mode (`debug_locked` = MuBi4False):
274334
275335 * Caliptra JTAG is opened for the microcontroller and HW debug.
276336
@@ -358,7 +418,7 @@
358418
359419 The following figure shows the timing information for clock gating.
360420
361-*Figure 10: Clock gating timing*
421+*Figure: Clock gating timing*
362422
363423 ![](../images/caliptra-rtl/docs/images/clock_gating_timing.png)
364424
@@ -372,19 +432,19 @@
372432
373433 The following figure shows the integrated TRNG block.
374434
375-*Figure 11: Integrated TRNG block*
435+*Figure: Integrated TRNG block*
376436
377437 ![](../images/caliptra-rtl/docs/images/integrated_TRNG.png)
378438
379439 The following figure shows the CSRNG block.
380440
381-*Figure 12: CSRNG block*
441+*Figure: CSRNG block*
382442
383443 ![](../images/caliptra-rtl/docs/images/CSRNG_block.png)
384444
385445 The following figure shows the entropy source block.
386446
387-*Figure 13: Entropy source block*
447+*Figure: Entropy source block*
388448
389449 ![](../images/caliptra-rtl/docs/images/entropy_source_block.png)
390450
@@ -444,13 +504,16 @@
444504
445505 | Name | Input or output | Description |
446506 | :---------- | :-------------- | :------------ |
447-| itrng_data | input | Physical true random noise source data |
448-| itrng_valid | input | Valid is asserted high for one cycle when data is valid. The expected valid output rate is about 50KHz. |
507+| itrng0_data | input | Primary physical true random noise source (ES0) data. |
508+| itrng0_valid | input | Primary source valid, asserted high for one cycle when data is valid. The expected valid output rate is about 50KHz. |
509+| itrng1_data | input | Secondary physical true random noise source (ES1) data, used only when the dual iTRNG entropy combiner is enabled; tie to 0 if unused. |
510+| itrng1_valid | input | Secondary source valid, asserted high for one cycle when data is valid. Used only in dual-iTRNG mode; tie to 0 if unused. |
511+| itrng1_en | input | Dual iTRNG enable strap: enables the secondary entropy source (ES1) and the SHA3-384 entropy combiner. Tie to 0 for a single iTRNG. See [Dual iTRNG entropy combiner](#dual-itrng-entropy-combiner). |
449512
450513
451514 The following figure shows the top level signals defined in caliptra\_top.
452515
453-*Figure 14: caliptra\_top signals*
516+*Figure: caliptra\_top signals*
454517
455518 ![](../images/caliptra-rtl/docs/images/caliptra_top_signals.png)
456519
@@ -459,22 +522,50 @@
459522 The following table provides descriptions of the entropy source signals.
460523
461524 | Name | Input or output | Description |
462-| :------------------ | :-------------- | :--------------- |
525+| :------------------------------ | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
463526 | clk_i | input | All signal timings are related to the rising edge of clk. |
464527 | rst_ni | input | The reset signal is active LOW and resets the core. |
465-| entropy_src_rng_req | output | Request from the entropy_src module to the physical true random noise source to start generating data. |
466-| entropy_src_rng_rsp | input | Contains the internal TRNG data and a flag indicating the data is valid. Valid is asserted high for one cycle when data is valid. |
528+| debugUnlock_or_scan_mode_switch | input | Zeroizes entropy\_src on debug lock/unlock, scan mode and lifecycle change. See [Entropy source zeroize](#entropy-source-zeroize). |
529+| entropy_src_rng_enable_o | output | Request from the entropy_src module to the physical true random noise source to start generating data. |
530+| entropy_src_rng_valid_i | input | Flag indicating the TRNG data is valid. Valid is asserted high for one cycle when data is valid. |
531+| entropy_src_rng_bits_i | input | The internal TRNG data. Sampled when entropy_src_rng_valid_i is asserted high. |
467532 | entropy_src_hw_if_i | input | Downstream block request for entropy bits. |
468533 | entropy_src_hw_if_o | output | 384 bits of entropy data. Valid when es_ack is asserted high. |
469-| cs_aes_halt_i | input | Response from csrng that all requests to AES block are halted. |
470-| cs_aes_halt_o | output | Request to csrng to halt requests to the AES block for power leveling purposes. |
471-
534+
535+
536+While `entropy_src_rng_enable_o` is asserted, entropy\_src accepts every `entropy_src_rng_bits_i` value marked by an asserted `entropy_src_rng_valid_i`; the noise source cannot be back-pressured.
537+The maximum supported rate is one `entropy_src_rng_bits_i` value (i.e. one sample) every two clock cycles.
472538
473539 The following figure shows the entropy source signals.
474540
475-*Figure 15: Entropy source signals*
541+*Figure: Entropy source signals*
476542
477543 ![](../images/caliptra-rtl/docs/images/entropy_source_signals.png)
544+
545+### Entropy source zeroize
546+
547+Writing 1 to `ENTROPY_SRC_CTRL.ZEROIZE` zeroizes entropy\_src and aborts any operation in progress, in any state.
548+entropy\_src is also zeroized on debug lock/unlock, scan mode and lifecycle change (`debugUnlock_or_scan_mode_switch`).
549+While a Caliptra fatal error is asserted, entropy\_src is held in zeroize.
550+
551+Zeroize clears:
552+- all FIFOs, including their storage: the raw entropy FIFOs, the observe FIFO and the esfinal FIFO that holds the conditioned seeds
553+- the main and ack state machines, which return to idle
554+- the health test state, the health test watermark and the alert counters
555+- the SHA3 conditioner (see the Zeroize section of [SHA3](#sha3))
556+
557+All state is cleared synchronously at the end of the zeroize cycle, except for the data of the packer FIFOs, which is cleared one cycle later and is never output in between.
558+In the zeroize cycle, no seed is acknowledged on the hardware interface, and `ENTROPY_DATA` and `FW_OV_RD_DATA` read 0.
559+Zeroize has precedence over the Error state of the state machines. They only return to the Error state if the local escalation is still asserted.
560+
561+Zeroize does not clear:
562+- the configuration registers
563+- the interrupt and alert status
564+- the enable of the noise source: the noise source keeps running. The sample received in the zeroize cycle is dropped.
565+
566+If entropy\_src is enabled, it restarts on its own after the zeroize: it runs the boot or startup health tests again and then delivers new seeds.
567+No seed is delivered from the state before the zeroize, so firmware does not need to disable and re-enable entropy\_src.
568+A pending request from CSRNG stays asserted and is served with a seed produced after the zeroize.
478569
479570 ### CSRNG signal descriptions
480571
@@ -488,11 +579,10 @@
488579 | lc_hw_debug_en_i | input | Lifecycle that selects which diversification value is used for xoring with the seed from entropy_src. |
489580 | entropy_src_hw_if_i | input | 384 bits of entropy data. Valid when es_ack is asserted high. |
490581 | entropy_src_hw_if_o | output | Downstream block request for entropy bits. |
491-| cs_aes_halt_i | input | Request from entropy_src to halt requests to the AES block for power leveling purposes. |
492-| cs_aes_halt_o | output | Response to entropy_src that all requests to AES block are halted. |
493-
494-
495-The CSRNG may only be enabled if entropy\_src is enabled. After it is disabled, CSRNG may only be re-enabled after entropy\_src has been disabled and re-enabled.
582+
583+
584+The recommended enable sequence is to first enable entropy\_src and then CSRNG.
585+entropy\_src can be disabled and re-enabled while CSRNG remains enabled; pending seed requests from CSRNG are served once entropy\_src is re-enabled.
496586
497587 ### FIPS considerations
498588
@@ -503,100 +593,272 @@
503593 publication SP 800-90B.
504594
505595 The TRNG must be re-initialized whenever self-test parameter changes are
506-needed. As described in the previous section, the initialization steps
507-are as follows:
508-
509-1. Disable `csrng` and `entropy_src` in that order.
596+needed. The initialization steps are as follows:
597+
598+1. Disable `entropy_src`. `csrng` can remain enabled.
510599 2. Apply new self-test configuration.
511-3. Enable `entropy_src` and `csrng` in that order.
600+3. Enable `entropy_src`.
512601
513602 ### Adaptive self-test window and thresholds
514603
515-This section details the configuration of the `entropy_src`, focusing on how
516-the test window size for the adaptive self-test is determined and how it
517-relates to threshold calculations.
518-
519-#### Understanding Test Window Sizes
520-
521-The adaptive self-test within the `entropy_src` block utilizes a
522-configurable test window. To clarify its interpretation, two terms are
523-defined:
524-
525-* `ENTROPY_TEST_WINDOW`: This refers to the test window size directly
526- configured in the hardware registers of the `entropy_src` block.
527-* `ACTUAL_TEST_WINDOW`: This refers to the effective window size used for
528- the adaptive self-test threshold calculations. Its value depends on how
529- the test scores are aggregated.
530-
531-The aggregation method is determined by the CONF.THRESHOLD_SCOPE setting in
532-the entropy_src block.
533-
534-#### Aggregate per symbol
535-
536-When CONF.THRESHOLD_SCOPE is enabled:
537-
538-* The adaptive test combines the inputs from all physical entropy lines
539- into a single, cumulative score.
540-* The test essentially treats the combined input as a single binary stream,
541- counting the occurrences of '1's.
542-* In this configuration:
543- * If `ENTROPY_TEST_WINDOW` is set to 1024, then
544- * `ACTUAL_TEST_WINDOW` = `ENTROPY_TEST_WINDOW` = 1024
545-
546-#### Handle each physical noise source separately
547-
548-When `CONF.THRESHOLD_SCOPE` is disabled:
549-
550-* The adaptive test scores each individual physical noise input line
551- independently.
552-* This allows for monitoring the health of each noise source.
553-* In this configuration (assuming, for example, 4 noise sources):
554- * If `ENTROPY_TEST_WINDOW` is set to 4096 bits, then
555- * `ACTUAL_TEST_WINDOW` = (`ENTROPY_TEST_WINDOW` / 4) = 1024
604+This section details the configuration of the `entropy_src` health test
605+windows and of the adaptive self-test thresholds.
606+
607+#### Test windows
608+
609+The size of a sample is determined by `CONF.RNG_BIT_ENABLE`:
610+
611+* In multi-channel mode (`CONF.RNG_BIT_ENABLE` disabled), a sample consists of
612+ one bit from each of the 4 noise source lines.
613+* In single-channel mode (`CONF.RNG_BIT_ENABLE` enabled), a sample is one bit
614+ of the line selected by `CONF.RNG_BIT_SEL`.
615+
616+The window size, in samples, depends on the operating mode:
617+
618+* FIPS mode (`CONF.FIPS_ENABLE` enabled): the window size is configured in
619+ `HEALTH_TEST_WINDOWS.FIPS_WINDOW`, in samples.
620+* Boot-time / bypass mode (`CONF.FIPS_ENABLE` disabled): the window is
621+ configured in `HEALTH_TEST_WINDOWS.BYPASS_WINDOW`, in bits over all tested
622+ lines, so the window size is `BYPASS_WINDOW` / 4 samples in multi-channel
623+ mode and `BYPASS_WINDOW` samples in single-channel mode. Only the default
624+ value of 384 bits is supported: without the conditioner, each window of
625+ tested bits is output directly as one 384-bit seed (the CSRNG seed width).
626+
627+In both modes, each tested noise source line contributes one bit per sample,
628+i.e. window size bits per window.
629+
630+#### Threshold scope
631+
632+Some health tests are executed on each noise source line individually. For
633+example, the Adaptive Proportion test counts the number of '1's of each line
634+over the window. In multi-channel mode (`CONF.RNG_BIT_ENABLE` disabled),
635+`CONF.THRESHOLD_SCOPE` selects the scope in which the results of these tests
636+are compared against the thresholds and health test failures are counted:
637+
638+* `CONF.THRESHOLD_SCOPE` disabled: the count of each line is compared against
639+ the thresholds individually. This allows detecting the failure of a single
640+ noise source line.
641+* `CONF.THRESHOLD_SCOPE` enabled: the counts of all lines are summed up and the
642+ sum is compared against the thresholds. This setting should not be used in
643+ Caliptra.
644+
645+In single-channel mode (`CONF.RNG_BIT_ENABLE` enabled), `CONF.THRESHOLD_SCOPE` has no effect.
556646
557647 #### Configuring adaptive self-test thresholds
558648
559-Once the `ACTUAL_TEST_WINDOW` is determined, the adaptive self-test
560-thresholds can be configured as follows:
561-
562-* `ADAPTP_HI_THRESHOLDS.FIPS_THRESH` = `adaptp_cutoff`
563-* `ADAPTP_LO_THRESHOLDS.FIPS_THRESH` = `ACTUAL_TEST_WINDOW` - `adaptp_cutoff`
564-
565-Here, `adaptp_cutoff` represents the pre-determined cutoff value for the
566-adaptive proportion test, as defined by NIST SP 800-90B. See the threshold
567-calculations below as an example.
649+`entropy_src` provides two variants of the NIST SP 800-90B Adaptive Proportion
650+test (Section 4.4.2), which declares an error if the count reaches the cutoff
651+value \\(C = 1 + critbinom(W, 2^{-H}, 1 - α)\\), where \\(W\\) is the window size and
652+\\(H\\) the min-entropy per sample:
653+
654+* The Adaptive Proportion test (`ADAPTP_HI_THRESHOLD`, `ADAPTP_LO_THRESHOLD`)
655+ treats the noise source lines as binary sources and counts the number of
656+ '1's. It is used when the lines are modeled as binary noise sources.
657+* The Adaptive Proportion Symbol test (`ADAPTPS_THRESHOLD`) treats the 4 lines
658+ together as a non-binary source producing 4-bit symbols. It counts how often
659+ the first symbol of the window occurs within the window.
660+
661+##### Adaptive Proportion test
662+
663+The thresholds depend on the number of bits `N` over which the compared count
664+is taken:
665+
666+| Mode | `CONF.THRESHOLD_SCOPE` disabled | `CONF.THRESHOLD_SCOPE` enabled |
667+| :------------- | :------------------------------ | :----------------------------- |
668+| Multi-channel | `N` = window size | `N` = 4 * window size |
669+| Single-channel | `N` = window size | `N` = window size |
670+
671+
672+`CONF.THRESHOLD_SCOPE` enabled is listed for completeness only and should not
673+be used in Caliptra.
674+
675+The test fails if the count of '1's is greater than or equal to
676+`ADAPTP_HI_THRESHOLD` or less than or equal to `ADAPTP_LO_THRESHOLD`, i.e. if
677+either the '1's or the '0's reach the cutoff value \\(C\\). An
678+`ADAPTP_LO_THRESHOLD` of 0 (reset value) disables the low check. The
679+thresholds can then be configured as follows:
680+
681+* `ADAPTP_HI_THRESHOLD` = \\(C\\)
682+* `ADAPTP_LO_THRESHOLD` = `N` - \\(C\\)
683+
684+with \\(W\\) = `N` and \\(H\\) the min-entropy per bit. See the threshold calculations
685+below as an example.
568686
569687 \\(α = 2^{-40}\\) (recommended)\
570688 \\(H = 0.5\\) (example, estimated entropy measured from hardware)\
571-\\(W\\) = `ACTUAL_TEST_WINDOW`\
572-`adaptp_cutoff` = \\(1 + critbinom(W, 2^{-H}, 1 - α)\\)
689+\\(W\\) = `N`\
690+\\(C = 1 + critbinom(W, 2^{-H}, 1 - α)\\)
691+
692+##### Adaptive Proportion Symbol test
693+
694+The Adaptive Proportion Symbol test is used in multi-channel mode, where each
695+sample is a 4-bit symbol. The test fails if the count of the first symbol
696+reaches `ADAPTPS_THRESHOLD`, so the threshold can be configured as follows:
697+
698+* `ADAPTPS_THRESHOLD` = \\(C\\)
699+
700+with \\(W\\) = window size and \\(H\\) the min-entropy per 4-bit symbol.
701+
702+The same threshold registers are used in FIPS mode and in bypass mode.
703+Since the counts are accumulated over the window, the cutoff \\(C\\) depends on
704+the window size, so thresholds calculated for the FIPS window are wrong for the
705+much smaller bypass window and vice versa. The thresholds therefore have to be set for the window of the
706+mode that is used, and reprogrammed (while `entropy_src` is disabled) when
707+switching between bypass and FIPS mode.
573708
574709 > Note: The `critbinom` function (critical binomial distribution function) is
575710 > implemented by most spreadsheet applications.
576711
577712 ### Recommended configuration
578713
579-The following configuration is recommended for the adaptive and repetition
580-count tests:
581-
582-#### Adaptive test
583-
584-1. Set `CONF.THRESHOLD_SCOPE` to disabled. This allows the test to monitor
585- and score each physical noise source individually, providing more granular
586- health information.
587-2. Set `HEALTH_TEST_WINDOWS.FIPS_WINDOW` to 4096 bits. This value serves
588- as the `ENTROPY_TEST_WINDOW`. With the current 4 noise source configuration,
589- this is equivalent to 1024 bits per noise source, where each source produces
590- 1 bit of entropy as defined in NIST SP 800-90B.
591-3. Calculate thresholds. Use an `ACTUAL_TEST_WINDOW` of 1024 bits (derived
592- from step 2) in the adaptive test threshold formulas provided earlier in
593- this subsection.
714+The configuration of the health tests depends on how the 4 noise source lines
715+can be modeled in the sense of NIST SP 800-90B. For the window size in the
716+different operating modes, see [Test windows](#test-windows).
717+
718+#### Four independent binary noise sources
719+
720+If the 4 lines come from independent noise sources, each line can be health
721+tested as a separate binary noise source:
722+
723+1. Set `CONF.THRESHOLD_SCOPE` to disabled, so that the Adaptive Proportion
724+ test evaluates each line individually. The Repetition Count test always
725+ evaluates each line individually.
726+2. Set the window size to the window size defined by NIST SP 800-90B
727+ for binary noise sources. Each line is then tested over window size bits.
728+3. Calculate the `ADAPTP_HI_THRESHOLD`, `ADAPTP_LO_THRESHOLD` and
729+ `REPCNT_THRESHOLD` cutoffs with `N` = window size.
730+
731+`entropy_src` only supports one set of cutoff values, shared by all 4 lines.
732+This configuration therefore requires a justification that:
733+
734+* the 4 lines can legitimately be treated as independent noise sources, and
735+* the common cutoff values are appropriate for every line, i.e. they are
736+ derived from an entropy estimate that holds for each of the 4 lines.
737+
738+If this cannot be justified, this configuration must not be used. Use one of
739+the following configurations instead.
740+
741+#### Single-lane mode
742+
743+Health test and condition a single binary line:
744+
745+1. Set `CONF.RNG_BIT_ENABLE` to enabled and select the line with
746+ `CONF.RNG_BIT_SEL`. `CONF.THRESHOLD_SCOPE` has no effect in this mode.
747+2. Set the window size to the window size defined by NIST SP 800-90B
748+ for binary noise sources. The selected line is then tested over window
749+ size bits.
750+3. Calculate the `ADAPTP_HI_THRESHOLD`, `ADAPTP_LO_THRESHOLD` and
751+ `REPCNT_THRESHOLD` cutoffs for the selected line with `N` = window size.
752+
753+#### 4-bit symbol mode
754+
755+Treat the 4 lines together as a single noise source producing 4-bit symbols:
756+
757+1. Keep `CONF.RNG_BIT_ENABLE` disabled (multi-channel mode).
758+2. Set the window size to the window size defined by NIST SP 800-90B
759+ for non-binary noise sources. Each sample is a 4-bit symbol.
760+3. Use the symbol-based tests: calculate the `ADAPTPS_THRESHOLD` (see
761+ [Adaptive Proportion Symbol test](#adaptive-proportion-symbol-test)) with
762+ `W` = window size and the `REPCNTS_THRESHOLD` (Repetition Count Symbol
763+ test), both with the min-entropy `H` per 4-bit symbol.
594764
595765 #### Repetition count test
596766
597767 The methodology used for calculating the repetition count threshold in the
598-ROM boot phase can be directly applied for this test as well. The threshold is
599-applied on a per-noise-source basis.
768+ROM boot phase can be directly applied in all three configurations, using
769+the min-entropy per bit (independent sources, single-lane mode) or per 4-bit
770+symbol (4-bit symbol mode).
771+
772+
773+## Dual iTRNG entropy combiner
774+
775+Some integrations require a **second physical noise source** — for example, a
776+secondary noise-generation technology deployed alongside the primary one. To
777+support this, Caliptra can instantiate a **second `entropy_src` (ES1)** next to
778+the primary source (`ES0`) while still feeding a **single CSRNG**. A dedicated
779+**SHA3-384 entropy combiner** sits between the two entropy sources and the CSRNG
780+and merges their conditioned outputs. This feature is only available when the
781+integrated TRNG is instantiated (`CALIPTRA_INTERNAL_TRNG`) and, per the interface
782+rules, is only enabled in Subsystem mode.
783+The following figure shows the dual iTRNG entropy combiner block.
784+
785+*Figure: Dual iTRNG entropy combiner block*
786+
787+![](../images/caliptra-rtl/docs/images/dual_entropy.png)
788+
789+The combiner presents a single `entropy_src_hw_if` interface to CSRNG
790+and drives one such interface to each of ES0 and ES1. It operates in one of two
791+modes, selected by `CPTRA_HW_CONFIG.dual_iTRNG_en`:
792+
793+* **Bypass mode (`dual_iTRNG_en == 0`, default):** the combiner is transparent.
794+ A CSRNG entropy request is forwarded to ES0 and ES0's response is returned
795+ unchanged; ES1 is never requested. This is functionally identical to the
796+ single-iTRNG datapath, so the default behavior of existing integrations is
797+ unchanged.
798+* **Combine mode (`dual_iTRNG_en == 1`):** one CSRNG request is fanned out to
799+ both ES0 and ES1. The combiner waits until both 384-bit conditioned seeds are
800+ captured, concatenates them as `ES0 || ES1` (768 bits — one SHA3-384 block,
801+ because 768 < the 832-bit SHA3-384 rate), hashes them through the shared
802+ `ot_sha3` gates, and returns the single 384-bit digest to CSRNG with one
803+ acknowledge. The FIPS status returned to CSRNG follows a configurable policy
804+ (AND of both sources by default, ES0-only, or a firmware-programmed value).
805+
806+### Enabling the feature
807+
808+Combine mode is enabled by `CPTRA_HW_CONFIG.dual_iTRNG_en`, a software-readable
809+bit that hardware drives from a dedicated `itrng1_en` integration input. The bit
810+resolves to 1 only in Subsystem mode with the internal TRNG present; in any other
811+configuration it reads 0 and the combiner stays in bypass. The same `itrng1_en`
812+input also gates the secondary physical-source pins (`itrng1_data` /
813+`itrng1_valid`). Each entropy source has its own external request output
814+(`etrng0_req` for ES0, `etrng1_req` for ES1).
815+
816+### Power-on known-answer test (KAT) and AHB lock
817+
818+Because FIPS certification requires a power-on KAT of every cryptographic block,
819+the combiner exposes an AHB-lite register interface used **only** by ROM. ROM
820+runs a self-contained KAT by writing a fixed message into `KAT_MSG`, programming
821+`KAT_MSG_LEN`, and pulsing `KAT_CTRL.start`; the combiner hashes that bounded
822+single-block message through the same `ot_sha3` datapath used operationally and
823+exposes the result in `KAT_DIGEST`. After the KAT, ROM sets the write-once
824+multi-bit (MuBi4) `AHB_LOCK`. Once locked, the KAT registers are zeroized and
825+read back as 0, and the FIPS combine policy is frozen, so runtime firmware cannot
826+observe KAT state or weaken the combination. Entropy never appears in any
827+AHB-readable register — the ES0/ES1 → combiner → CSRNG path is internal only.
828+
829+### Zeroize
830+
831+Writing 1 to `COMBINER_CTRL.zeroize` zeroizes the combiner in the following
832+cycle and aborts any combine or KAT operation in progress. The field is a
833+single-cycle pulse and reads back as 0.
834+
835+The combiner is also zeroized on debug lock/unlock, scan mode and lifecycle
836+change.
837+
838+Zeroize clears:
839+- the captured ES0/ES1 seeds and the combined digest
840+- the KAT message, length and digest, including the `KAT_MSG` and `KAT_MSG_LEN` registers
841+- the combiner FSM and the `ot_sha3` core
842+
843+Zeroize does not clear the configuration (`COMBINER_CTRL.es_fips_policy`,
844+`es_fips_cfg`, `AHB_LOCK`) or the interrupt status registers.
845+
846+`zeroize` remains writable after `AHB_LOCK` is set.
847+
848+Outstanding ES0/ES1 requests stay asserted until they are acknowledged, and
849+seeds that were already captured are discarded and requested again. A CSRNG
850+request that was not yet acknowledged is completed with a digest of fresh seeds
851+from ES0 and ES1. A CSRNG request that was already acknowledged still waits for
852+`es_req` to be deasserted.
853+
854+### Fault handling
855+
856+The combiner is fault-hardened consistently with the surrounding OpenTitan
857+blocks: `AHB_LOCK` uses a MuBi4 encoding that is fail-safe to *locked*, and the
858+datapath sequencer uses a sparse Hamming-distance-3 (HD-3) FSM encoding. A
859+single-bit glitch that produces an undefined FSM code is trapped to a terminal
860+error state and latched into the combiner's error-interrupt status (alongside the
861+`ot_sha3` countermeasure errors).
600862
601863
602864 ## External-TRNG REQ HW API
@@ -634,7 +896,54 @@
634896
635897 Note: If the debug security state switches to debug mode anytime, the security assets and keys are still flushed even though JTAG is not open.
636898
637-*Figure 16: JTAG implementation*
899+The following table details the alias addresses for registers in soc ifc that are accessible through JTAG.
900+Debug Locked registers are a subset of registers accessible when debug intent is set, when debug is unlocked, or the lifecycle state is DEVICE_MANUFACTURING.
901+Debug Unlocked registers are accessible when debug is unlocked, or the lifecycle state is DEVICE_MANUFACTURING.
902+
903+| Register Name | JTAG Address | Accessibility | Debug Locked | Debug Unlocked |
904+| ------------------------------------------- | -------------- | --------------- | -------------- | ---------------- |
905+| mbox_lock | 7’h75 | RO | YES | YES |
906+| mbox_cmd | 7’h76 | RW | YES | YES |
907+| mbox_dlen | 7’h50 | RW | YES | YES |
908+| mbox_dataout | 7’h51 | RO | YES | YES |
909+| mbox_datain | 7’h62 | WO | YES | YES |
910+| mbox_status | 7’h52 | RW | YES | YES |
911+| mbox_execute | 7’h77 | WO | YES | YES |
912+| CPTRA_BOOT_STATUS | 7’h53 | RO | YES | YES |
913+| CPTRA_HW_ERRROR_ENC | 7’h54 | RO | YES | YES |
914+| CPTRA_FW_ERROR_ENC | 7’h55 | RO | YES | YES |
915+| SS_UDS_SEED_BASE_ADDR_L | 7’h56 | RO || YES |
916+| SS_UDS_SEED_BASE_ADDR_H | 7’h57 | RO || YES |
917+| CPTRA_HW_ERROR_FATAL | 7’h58 | RO | YES | YES |
918+| CPTRA_FW_ERROR_FATAL | 7’h59 | RO | YES | YES |
919+| CPTRA_HW_ERROR_NON_FATAL | 7’h5a | RO | YES | YES |
920+| CPTRA_FW_ERROR_NON_FATAL | 7’h5b | RO | YES | YES |
921+| CPTRA_DBG_MANUF_SERVICE_REG | 7’h60 | RW | YES | YES |
922+| CPTRA_BOOTFSM_GO | 7’h61 | RW | YES | YES |
923+| SS_DEBUG_INTENT | 7’h63 | RW || YES |
924+| SS_CALIPTRA_BASE_ADDR_L | 7’h64 | RW || YES |
925+| SS_CALIPTRA_BASE_ADDR_H | 7’h65 | RW || YES |
926+| SS_MCI_BASE_ADDR_L | 7’h66 | RW || YES |
927+| SS_MCI_BASE_ADDR_H | 7’h67 | RW || YES |
928+| SS_RECOVERY_IFC_BASE_ADDR_L | 7’h68 | RW || YES |
929+| SS_RECOVERY_IFC_BASE_ADDR_H | 7’h69 | RW || YES |
930+| SS_OTP_FC_BASE_ADDR_L | 7’h6A | RW || YES |
931+| SS_OTP_FC_BASE_ADDR_H | 7’h6B | RW || YES |
932+| SS_STRAP_GENERIC_0 | 7’h6C | RW || YES |
933+| SS_STRAP_GENERIC_1 | 7’h6D | RW || YES |
934+| SS_STRAP_GENERIC_2 | 7’h6E | RW || YES |
935+| SS_STRAP_GENERIC_3 | 7’h6F | RW || YES |
936+| SS_DBG_SERVICE_REG_REQ | 7’h70 | RW | YES | YES |
937+| SS_DBG_SERVICE_REG_RSP | 7’h71 | RO | YES | YES |
938+| SS_DBG_UNLOCK_LEVEL0 | 7’h72 | RW || YES |
939+| SS_DBG_UNLOCK_LEVEL1 | 7’h73 | RW || YES |
940+| SS_STRAP_CALIPTRA_DMA_AXI_USER | 7’h74 | RW || YES |
941+| SS_EXTERNAL_STAGING_AREA_BASE_ADDR_L | 7’h78 | RW || YES |
942+| SS_EXTERNAL_STAGING_AREA_BASE_ADDR_H | 7’h79 | RW || YES |
943+
944+
945+
946+*Figure: JTAG implementation*
638947
639948 ![](../images/caliptra-rtl/docs/images/JTAG_implementation.png)
640949
@@ -644,18 +953,19 @@
644953
645954 * Symmetric cryptographic primitives
646955 * De-obfuscation engine
647- * SHA512/384 (based on NIST FIPS 180-4 [2])
648- * SHA256 (based on NIST FIPS 180-4 [2])
649- * HMAC512 (based on [NIST FIPS 198-1](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf) [5] and [RFC 4868](https://tools.ietf.org/html/rfc4868) [6])
956+ * SHA512/384 (based on NIST FIPS 180-4 [2])
957+ * SHA256 (based on NIST FIPS 180-4 [2])
958+ * HMAC512 (based on [NIST FIPS 198-1](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf) [5] and [RFC 4868](https://tools.ietf.org/html/rfc4868) [6])
959+ * SHA3 (based on [NIST FIPS 202](https://doi.org/10.6028/NIST.FIPS.202) [17])
650960 * Public-key cryptography
651- * NIST Secp384r1 Deterministic Digital Signature Algorithm (based on FIPS-186-4 [11] and RFC 6979 [7])
961+ * NIST Secp384r1 Deterministic Digital Signature Algorithm (based on FIPS-186-4 [11] and RFC 6979 [7])
652962 * Key vault
653- * Key slots
654- * Key slot management
963+ * Key slots
964+ * Key slot management
655965
656966 The high-level architecture of Caliptra cryptographic subsystem is shown in the following figure.
657967
658-*Figure 17: Caliptra cryptographic subsystem*
968+*Figure: Caliptra cryptographic subsystem*
659969
660970 ![](../images/caliptra-rtl/docs/images/Crypto-2p0.png)
661971
@@ -680,7 +990,7 @@
680990
681991 The total size should be equal to 128 bits short of a multiple of 1024 since the goal is to have the formatted message size as a multiple of 1024 bits (N x 1024). The following figure shows the SHA512 input formatting.
682992
683-*Figure 18: SHA512 input formatting*
993+*Figure: SHA512 input formatting*
684994
685995 ![](../images/caliptra-rtl/docs/images/SHA512_input.png)
686996
@@ -692,7 +1002,7 @@
6921002
6931003 The SHA512 architecture has the finite-state machine as shown in the following figure.
6941004
695-*Figure 19: SHA512 FSM*
1005+*Figure: SHA512 FSM*
6961006
6971007 ![](../images/caliptra-rtl/docs/images/SHA512_fsm.png)
6981008
@@ -716,13 +1026,13 @@
7161026
7171027 ### Address map
7181028
719-The SHA512 address map is shown here: [sha512\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.sha512_reg)
1029+The SHA512 address map is shown here: [sha512\_reg -- clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.sha512_reg)
7201030
7211031 ### Pseudocode
7221032
7231033 The following pseudocode demonstrates how the SHA512 interface can be implemented.
7241034
725-*Figure 20: SHA512 pseudocode*
1035+*Figure: SHA512 pseudocode*
7261036
7271037 ![](../images/caliptra-rtl/docs/images/SHA512_pseudo.png)
7281038
@@ -803,7 +1113,7 @@
8031113
8041114 The following figure shows SHA256 input formatting.
8051115
806-*Figure 21: SHA256 input formatting*
1116+*Figure: SHA256 input formatting*
8071117
8081118 ![](../images/caliptra-rtl/docs/images/SHA256_input.png)
8091119
@@ -815,7 +1125,7 @@
8151125
8161126 The SHA256 architecture has the finite-state machine as shown in the following figure.
8171127
818-*Figure 22: SHA256 FSM*
1128+*Figure: SHA256 FSM*
8191129
8201130 ![](../images/caliptra-rtl/docs/images/SHA256_fsm.png)
8211131
@@ -844,13 +1154,13 @@
8441154
8451155 ### Address map
8461156
847-The SHA256 address map is shown here: [sha256\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.sha256_reg).
1157+The SHA256 address map is shown here: [sha256\_reg -- clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.sha256_reg).
8481158
8491159 ### Pseudocode
8501160
8511161 The following pseudocode demonstrates how the SHA256 interface can be implemented.
8521162
853-*Figure 23: SHA256 pseudocode*
1163+*Figure: SHA256 pseudocode*
8541164
8551165 ![](../images/caliptra-rtl/docs/images/SHA256_pseudo.png)
8561166
@@ -890,6 +1200,184 @@
8901200 | 1 KiB message | 8761 | 21.90 | 45,657 |
8911201
8921202
1203+## SHA3
1204+
1205+The SHA3 HWIP performs the hash functions, whose purpose is to check the integrity of the received message.
1206+It supports various SHA3 hashing functions including SHA3 Extended Output Function (XOF) known as SHAKE functions.
1207+The details of the operation are described in the [SHA3 specification, FIPS 202](https://csrc.nist.gov/publications/detail/fips/202/final) known as _sponge construction_.
1208+It has been adapted from OpenTitan and you can find documentation describing the functionality of the KMAC block it was derived from [here](https://opentitan.org/book/hw/ip/kmac/index.html).
1209+In the current use cases of the SHA3 HW IP, either (a) messages are not considered secret (External Mu), or (b) SCA hardening would not be meaningful (HPKE in OCP L.O.C.K.), hence there are no SCA requirements.
1210+
1211+### Features
1212+- Support for SHA3-224, 256, 384, 512, SHAKE[128, 256] and cSHAKE[128, 256]
1213+- Support byte-granularity on input message
1214+- Support arbitrary output length for SHAKE, cSHAKE
1215+- Support customization input string S, and function-name N up to 36 bytes total
1216+- 64b x 10 depth Message FIFO
1217+- Zeroize through the `SHA3_CTRL.ZEROIZE` register and on debug/scan mode switch
1218+- Performance (at 100 MHz):
1219+ - SHA3-224: 2.93 B/cycle, 2.34 Gbit/s - 1.19 B/cycle, 952 Mbit/s (DOM)
1220+ - SHA3-512: 1.47 B/cycle, 1.18 Gbit/s - 0.59 B/cycle, 472 Mbit/s (DOM)
1221+
1222+### Design Details
1223+
1224+#### Keccak Round
1225+
1226+A Keccak round implements the Keccak_f function described in the SHA3 specification.
1227+Keccak round logic in SHA3 HWIP not only supports 1600 bit internal states but also all possible values {25, 50, 100, 200, 400, 800, 1600} based on a parameter `Width`.
1228+Keccak permutations in the specification allow arbitrary number of rounds.
1229+This module, however, supports Keccak_f which always runs `12 + 2*L` rounds, where \\[ L = log_2 {( {Width \over 25} )} \\] .
1230+For instance, 200 bits of internal state run 18 rounds.
1231+SHA3 instantiates the Keccak round module with 1600 bit.
1232+
1233+![](../images/caliptra-rtl/docs/images/sha3-keccak-round.svg)
1234+
1235+Keccak round logic has two phases inside.
1236+Theta, Rho, Pi functions are executed at the 1st phase.
1237+Chi and Iota functions run at the 2nd phase.
1238+The first phase and the second phase run in the same cycle.
1239+
1240+To save circuit area, the Chi function uses 800 instead 1600 DOM multipliers but the multipliers are fully pipelined.
1241+The Chi and Iota functions are thus separately applied to the two halves of the state and the 2nd phase takes in total three clock cycles to complete.
1242+In the first clock cycle of the 2nd phase, the first stage of Chi is computed for the first lane halves of the state.
1243+In the second clock cycle, the new first lane halves are output and written to state register.
1244+At the same time, the first stage of Chi is computed for the second lane halves.
1245+In the third clock cycle, the new second lane halves are output and written to the state register.
1246+
1247+#### Padding for Keccak
1248+
1249+Padding logic supports SHA3/SHAKE/cSHAKE algorithms.
1250+cSHAKE needs the extra inputs for the Function-name `N` and the Customization string `S`.
1251+Other than that, SHA3, SHAKE, and cSHAKE share similar datapath inside the padding module except the last part added next to the end of the message.
1252+SHA3 adds `2'b 10`, SHAKE adds `4'b 1111`, cSHAKE adds `2'b00` then `pad10*1()` follows.
1253+All are little-endian values.
1254+
1255+Interface between this padding logic and the MSG_FIFO follows the conventional FIFO interface.
1256+So `caliptra_prim_fifo_*` can talk to the padding logic directly.
1257+This module talks to Keccak round logic with a more memory-like interface.
1258+The interface has an additional address signal on top of the valid, ready, and data signals.
1259+
1260+![](../images/caliptra-rtl/docs/images/sha3-padding.svg)
1261+
1262+The hashing process begins when the software issues the start command to `CMD` .
1263+If cSHAKE is enabled, the padding logic expands the prefix value (`N || S` above) into a block size.
1264+The block size is determined by the `CFG_SHADOWED.kstrength`.
1265+If the value is 128, the block size will be 168 bytes.
1266+If it is 256, the block size will be 136 bytes.
1267+The expanded prefix value is transmitted to the Keccak round logic.
1268+After sending the block size, the padding logic triggers the Keccak round logic to run a full 24 rounds.
1269+
1270+If the mode is not cSHAKE, or cSHAKE mode and the prefix block has been processed, the padding logic accepts the incoming message bitstream and forward the data to the Keccak round logic in a block granularity.
1271+The padding logic controls the data flow and makes the Keccak logic to run after sending a block size.
1272+
1273+After the software writes the message bitstream, it should issue the Process command into `CMD` register.
1274+The padding logic, after receiving the Process command, appends proper ending bits with respect to the `CFG_SHADOWED.mode` value.
1275+The logic writes 0 up to the block size to the Keccak round logic then ends with 1 at the end of the block.
1276+
1277+![](../images/caliptra-rtl/docs/images/sha3-padding-fsm.svg)
1278+
1279+After the Keccak round completes the last block, the padding logic asserts an `absorbed` signal to notify the software.
1280+At this point, the software is able to read the digest in `STATE` memory region.
1281+If the output length is greater than the Keccak block rate in SHAKE and cSHAKE mode, the software may run the Keccak round manually by issuing Run command to `CMD` register.
1282+
1283+The software completes the operation by issuing Done command after reading the digest.
1284+The padding logic clears internal variables and goes back to Idle state.
1285+
1286+#### Message FIFO
1287+
1288+The SHA3 HWIP has a compile-time configurable depth message FIFO inside.
1289+The message FIFO receives incoming message bitstream regardless of its byte position in a word.
1290+Then it packs the partial message bytes into the internal 64 bit data width.
1291+After packing the data, the logic stores the data into the FIFO until the internal SHA3 engine consumes the data.
1292+
1293+##### FIFO Depth calculation
1294+
1295+The depth of the message FIFO is chosen to cover the throughput of the software or other producers such as DMA engine.
1296+The size of the message FIFO is enough to hold the incoming data while the SHA3 engine is processing the previous block.
1297+Default design parameters assume the system characteristics as below:
1298+
1299+- `kmac_pkg::RegLatency`: The register write takes 5 cycles.
1300+- `kmac_pkg::Sha3Latency`: Keccak round latency takes 24 cycles.
1301+
1302+##### Empty and Full status
1303+
1304+Under normal operating conditions, the SHA3 engine will process data a lot faster than software can push it to the Message FIFO.
1305+The Message FIFO depth observable from `STATUS.fifo_depth` will remain **0** while the `STATUS.fifo_empty` status bit is lowered for one clock cycle whenever software provides new data.
1306+
1307+After the SHA3 engine starts popping the data again, the Message FIFO will eventually run empty again and the `fifo_empty` status interrupt will fire.
1308+Note that the `fifo_empty` status interrupt will not fire if i) one of the hardware application interfaces is using the SHA3 block, ii) the SHA3 core is not in the `Absorb` state, or iii) after software has written the `Process` command.
1309+
1310+If software pushes data to the Message FIFO while it is full, the write operation is blocked until there is again space in the FIFO.
1311+This means the processor is effectively stalled.
1312+If the SHA3 engine is currently running and software fills up the Message FIFO, the resulting stall won't take more than 100 clock cycles.
1313+The stall mechanism prevents data loss and the upper bound on the wait time avoids software needing to poll the `STATUS.fifo_depth` field before writing data.
1314+
1315+### Programmer's guide
1316+
1317+The software can update the SHA3 configurations only when the IP is in the idle state.
1318+The software should check `STATUS.sha3_idle` before updating the configurations.
1319+The software must first program `CFG_SHADOWED.msg_endianness` and `CFG_SHADOWED.state_endianness` at the initialization stage.
1320+These determine the byte order of incoming messages (msg_endianness) and the Keccak state output (state_endianness).
1321+
1322+#### Software Initiated SHA3 process
1323+
1324+This section describes the expected software process to run the SHA3 HWIP.
1325+At first, the software configures `CFG_SHADOWED.kmac_en` for the operation.
1326+If SHA3 is enabled, the software should configure `CFG_SHADOWED.mode` to cSHAKE and `CFG_SHADOWED.kstrength` to 128 or 256 bit security strength.
1327+The software also updates `PREFIX` registers if cSHAKE mode is used.
1328+Current design does not convert cSHAKE mode to SHAKE even if `PREFIX` is empty string.
1329+It is the software's responsibility to change the `CFG_SHADOWED.mode` to SHAKE in case of empty `PREFIX`.
1330+The SHA3 HWIP uses `PREFIX` registers as it is.
1331+It means that the software should update `PREFIX` with encoded values.
1332+
1333+After configuring, the software notifies the SHA3 engine to accept incoming messages by issuing Start command into `CMD`.
1334+If Start command is not issued, the incoming message is discarded.
1335+
1336+After the software pushes all messages, it issues Process command to `CMD` for SHA3 engine to complete the sponge absorbing process.
1337+SHA3 hashing engine pads the incoming message as defined in the SHA3 specification.
1338+
1339+After the SHA3 engine completes the sponge absorbing step, it generates `kmac_done` interrupt.
1340+Or the software can poll the `STATUS.squeeze` bit until it becomes 1.
1341+In this stage, the software may run the Keccak round manually.
1342+
1343+If the desired digest length is greater than the Keccak rate, the software issues Run command for the Keccak round logic to run one full round after the software reads the current available Keccak state.
1344+At this stage, SHA3 does not raise an interrupt when the Keccak round completes the software initiated manual run.
1345+The software should check `STATUS.squeeze` register field for the readiness of `STATE` value.
1346+
1347+After the software reads all the digest values, it issues Done command to `CMD` register to clear the internal states.
1348+Done command clears the Keccak state, FSM in SHA3, and a few internal variables.
1349+
1350+#### Zeroize
1351+
1352+Writing 1 to `SHA3_CTRL.ZEROIZE` clears all message and digest data and aborts any operation in progress, in any state.
1353+SHA3 is also zeroized on debug lock/unlock, scan mode and lifecycle change.
1354+While a Caliptra fatal error is asserted, SHA3 is held in zeroize.
1355+Each register is cleared synchronously in the zeroize cycle.
1356+
1357+Zeroize clears:
1358+- the Keccak state, the padding buffer and the message FIFO
1359+- the `STATE` read data, including the copy held in the TL-UL adapter
1360+- the SHA3 FSMs, the internal counters and any pending command, the engine returns to idle
1361+
1362+Bus transactions in flight complete normally.
1363+A `STATE` read in the zeroize cycle returns 0.
1364+Zeroize has precedence over the terminal error state and returns the SHA3 FSMs to idle.
1365+The FSMs only return to the terminal error state if the escalation signal is still asserted.
1366+
1367+After zeroize, the software must wait for `STATUS.sha3_idle` to start a new operation with the Start command.
1368+
1369+#### Endianness
1370+
1371+This SHA3 HWIP operates in little-endian.
1372+Internal SHA3 hashing engine receives in 64-bit granularity.
1373+The data written to SHA3 is assumed to be little endian.
1374+
1375+The software may write/read the data in big-endian order if `CFG_SHADOWED.msg_endianness` or `CFG_SHADOWED.state_endianness` is set.
1376+If the endianness bit is 1, the data is assumed to be big-endian.
1377+So, the internal logic byte-swap the data.
1378+For example, when the software writes `0xDEADBEEF` with endianness as 1, the logic converts it to `0xEFBEADDE` then writes into MSG_FIFO.
1379+
1380+
8931381 ## HMAC512/HMAC384
8941382
8951383 Hash-based message authentication code (HMAC) is a cryptographic authentication technique that uses a hash function and a secret key. HMAC involves a cryptographic hash function and a secret cryptographic key. This implementation supports the HMAC512 variants HMAC-SHA-512-256 and HMAC-SHA-384-192 as specified in [NIST FIPS 198-1](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf) [5]. The implementation is compatible with the HMAC-SHA-512-256 and HMAC-SHA-384-192 authentication and integrity functions defined in [RFC 4868](https://tools.ietf.org/html/rfc4868) [6].
@@ -916,25 +1404,25 @@
9161404
9171405 The total size should be equal to 128 bits, short of a multiple of 1024 because the goal is to have the formatted message size as a multiple of 1024 bits (N x 1024).
9181406
919-*Figure 24: HMAC input formatting*
1407+*Figure: HMAC input formatting*
9201408
9211409 ![](../images/caliptra-rtl/docs/images/HMAC_input.png)
9221410
9231411 The following figures show examples of input formatting for different message lengths.
9241412
925-*Figure 25: Message length of 1023 bits*
1413+*Figure: Message length of 1023 bits*
9261414
9271415 ![](../images/caliptra-rtl/docs/images/msg_1023.png)
9281416
9291417 When the message is 1023 bits long, padding is given in the next block along with message size.
9301418
931-*Figure 26: 1 bit padding*
1419+*Figure: 1 bit padding*
9321420
9331421 ![](../images/caliptra-rtl/docs/images/1_bit.png)
9341422
9351423 When the message size is 895 bits, a padding of ‘1’ is also considered valid, followed by the message size.
9361424
937-*Figure 27: Multi block message*
1425+*Figure: Multi block message*
9381426
9391427 ![](../images/caliptra-rtl/docs/images/msg_multi_block.png)
9401428
@@ -945,13 +1433,13 @@
9451433
9461434 The HMAC512 core performs the sha2-512 function to process the hash value of the given message. The algorithm processes each block of the 1024 bits from the message, using the result from the previous block. This data flow is shown in the following figure.
9471435
948-*Figure 28: HMAC-SHA-512-256 data flow*
1436+*Figure: HMAC-SHA-512-256 data flow*
9491437
9501438 ![](../images/caliptra-rtl/docs/images/HMAC_SHA_512_256.png)
9511439
9521440 The HMAC384 core performs the sha2-384 function to process the hash value of the given message. The algorithm processes each block of the 1024 bits from the message, using the result from the previous block. This data flow is shown in the following figure.
9531441
954-*Figure 29: HMAC-SHA-384-192 data flow*
1442+*Figure: HMAC-SHA-384-192 data flow*
9551443
9561444 ![](../images/caliptra-rtl/docs/images/HMAC_SHA_384_192.png)
9571445
@@ -959,7 +1447,7 @@
9591447
9601448 The HMAC architecture has the finite-state machine as shown in the following figure.
9611449
962-*Figure 30: HMAC FSM*
1450+*Figure: HMAC FSM*
9631451
9641452 ![](../images/caliptra-rtl/docs/images/HMAC_FSM.png)
9651453
@@ -991,13 +1479,13 @@
9911479
9921480 ### Address map
9931481
994-The HMAC address map is shown here: [hmac\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.hmac_reg).
1482+The HMAC address map is shown here: [hmac\_reg -- clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.hmac_reg).
9951483
9961484 ### Pseudocode
9971485
9981486 The following pseudocode demonstrates how the HMAC interface can be implemented.
9991487
1000-*Figure 31: HMAC pseudocode*
1488+*Figure: HMAC pseudocode*
10011489
10021490 ![](../images/caliptra-rtl/docs/images/HMAC_pseudo.png)
10031491
@@ -1122,7 +1610,7 @@
11221610
11231611 Secp384r1 parameters are shown in the following figure.
11241612
1125-*Figure 32: Secp384r1 parameters*
1613+*Figure: Secp384r1 parameters*
11261614
11271615 ![](../images/caliptra-rtl/docs/images/secp384r1_params.png)
11281616
@@ -1130,7 +1618,7 @@
11301618
11311619 The ECDSA consists of three operations, shown in the following figure.
11321620
1133-*Figure 33: ECDSA operations*
1621+*Figure: ECDSA operations*
11341622
11351623 ![](../images/caliptra-rtl/docs/images/ECDSA_ops.png)
11361624
@@ -1175,7 +1663,7 @@
11751663
11761664 The ECC top-level architecture is shown in the following figure.
11771665
1178-*Figure 34: ECC architecture*
1666+*Figure: ECC architecture*
11791667
11801668 ![](../images/caliptra-rtl/docs/images/ECC_arch.png)
11811669
@@ -1207,7 +1695,7 @@
12071695
12081696 ### Address map
12091697
1210-The ECC address map is shown here: [ecc\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.ecc_reg).
1698+The ECC address map is shown here: [ecc\_reg -- clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.ecc_reg).
12111699
12121700 ### Pseudocode
12131701
@@ -1215,25 +1703,25 @@
12151703
12161704 #### KeyGen
12171705
1218-*Figure 35: KeyGen pseudocode*
1706+*Figure: KeyGen pseudocode*
12191707
12201708 ![](../images/caliptra-rtl/docs/images/keygen_pseudo.png)
12211709
12221710 #### Signing
12231711
1224-*Figure 36: Signing pseudocode*
1712+*Figure: Signing pseudocode*
12251713
12261714 ![](../images/caliptra-rtl/docs/images/signing_pseudo.png)
12271715
12281716 #### Verifying
12291717
1230-*Figure 37: Verifying pseudocode*
1718+*Figure: Verifying pseudocode*
12311719
12321720 ![](../images/caliptra-rtl/docs/images/verify_pseudo.png)
12331721
12341722 #### ECDH sharedkey
12351723
1236-*Figure 38: ECDH sharedkey pseudocode*
1724+*Figure: ECDH sharedkey pseudocode*
12371725
12381726 ![](../images/caliptra-rtl/docs/images/sharedkey_pseudo.png)
12391727
@@ -1299,7 +1787,7 @@
12991787 2. KEYGEN PRIVKEY: Running HMAC\_DRBG with seed and nonce to generate the privkey in KEYGEN operation.
13001788 3. SIGNING NONCE: Running HMAC\_DRBG based on RFC6979 in SIGNING operation with privkey and hashed\_msg.
13011789
1302-*Figure 39: HMAC\_DRBG utilization*
1790+*Figure: HMAC\_DRBG utilization*
13031791
13041792 ![](../images/caliptra-rtl/docs/images/HMAC_DRBG_util.png)
13051793
@@ -1315,7 +1803,7 @@
13151803
13161804 The data flow of the HMAC\_DRBG operation in keygen operation mode is shown in the following figure.
13171805
1318-*Figure 40: HMAC\_DRBG data flow*
1806+*Figure: HMAC\_DRBG data flow*
13191807
13201808 ![](../images/caliptra-rtl/docs/images/HMAC_DRBG_data.png)
13211809
@@ -1325,7 +1813,7 @@
13251813
13261814 In practice, observing a t-value greater than a specific threshold (mainly 4.5) indicates the presence of leakage. However, in ECC, due to its latency, around 5 million samples are required to be captured. This latency leads to many false positives and the TVLA threshold can be considered a higher value than 4.5. Based on the following figure from “Side-Channel Analysis and Countermeasure Design for Implementation of Curve448 on Cortex-M4” by Bisheh-Niasar et. al., the threshold can be considered equal to 7 in our case.
13271815
1328-*Figure 41: TVLA threshold as a function of the number of samples per trace*
1816+*Figure: TVLA threshold as a function of the number of samples per trace*
13291817
13301818 ![](../images/caliptra-rtl/docs/images/TVLA_threshold.png)
13311819
@@ -1335,7 +1823,7 @@
13351823 The TVLA results for performing seed/nonce-dependent leakage detection using 200,000 traces is shown in the following figure. Based on this figure, there is no leakage in ECC keygen by changing the seed/nonce after 200,000 operations.
13361824
13371825
1338-*Figure 42: seed/nonce-dependent leakage detection using TVLA for ECC keygen after 200,000 traces*
1826+*Figure: seed/nonce-dependent leakage detection using TVLA for ECC keygen after 200,000 traces*
13391827
13401828 ![](../images/caliptra-rtl/docs/images/tvla_keygen.png)
13411829
@@ -1343,13 +1831,13 @@
13431831
13441832 The TVLA results for performing privkey-dependent leakage detection using 20,000 traces is shown in the following figure. Based on this figure, there is no leakage in ECC signing by changing the privkey after 20,000 operations.
13451833
1346-*Figure 43: privkey-dependent leakage detection using TVLA for ECC signing after 20,000 traces*
1834+*Figure: privkey-dependent leakage detection using TVLA for ECC signing after 20,000 traces*
13471835
13481836 ![](../images/caliptra-rtl/docs/images/TVLA_privekey.png)
13491837
13501838 The TVLA results for performing message-dependent leakage detection using 64,000 traces is shown in the following figure. Based on this figure, there is no leakage in ECC signing by changing the message after 64,000 operations.
13511839
1352-*Figure 44: Message-dependent leakage detection using TVLA for ECC signing after 64,000 traces*
1840+*Figure: Message-dependent leakage detection using TVLA for ECC signing after 64,000 traces*
13531841
13541842 ![](../images/caliptra-rtl/docs/images/TVLA_msg_dependent.png)
13551843
@@ -1374,13 +1862,14 @@
13741862
13751863 ### Pure hardware architecture
13761864
1377-In this architecture, the ECC interface and controller are implemented in hardware. The performance specification of the ECC architecture is reported as shown in the following table.
1865+In this architecture, the ECC interface and controller are implemented in hardware. The Montgomery multiplier in the current RTL uses a **radix-48** datapath (`MULT_RADIX = 48` in `src/ecc/rtl/ecc_params_pkg.sv`), which reduces the number of PE iterations per 384-bit modular multiplication from 12 (radix-32) to 8. The performance specification of the ECC architecture is reported as shown in the following table. Cycle counts were measured on `ecc_top_tb` running the `ecc_normal_test` (radix-48 RTL).
13781866
13791867 | Operation | Cycle count \[CCs\] | Time \[ms\] @ 400 MHz | Throughput \[op/s\] |
1380-| :-------- | :------------------ | :-------------------- | :------------------ |
1381-| Keygen | 909,648 | 2.274 | 439 |
1382-| Signing | 932,990 | 2.332 | 428 |
1383-| Verifying | 1,223,938 | 3.060 | 326 |
1868+| :------------- | :------------------ | :-------------------- | :------------------ |
1869+| Keygen | 719,675 | 1.799 | 556 |
1870+| Signing | 736,978 | 1.842 | 543 |
1871+| Verifying | 960,404 | 2.401 | 416 |
1872+| ECDH sharedkey | 717,421 | 1.794 | 558 |
13841873
13851874
13861875
@@ -1388,15 +1877,15 @@
13881877
13891878 LMS cryptography is a type of hash-based digital signature scheme that was standardized by NIST in 2020. It is based on the Leighton-Micali Signature (LMS) system, which uses a Merkle tree structure to combine many one-time signature (OTS) keys into a single public key. LMS cryptography is resistant to quantum attacks and can achieve a high level of security without relying on large integer mathematics.
13901879
1391-Caliptra supports only LMS verification using a software/hardware co-design approach. Hence, the LMS accelerator reuses the SHA256 engine to speedup the Winternitz chain by removing software-hardware interface overhead. The LMS-OTS verification algorithm is shown in follwoing figure:
1392-
1393-*Figure 45: LMS-OTS Verification algorithm*
1880+Caliptra supports only LMS verification using a software/hardware co-design approach. Hence, the LMS accelerator reuses the SHA256 engine to speedup the Winternitz chain by removing software-hardware interface overhead. The LMS-OTS verification algorithm is shown in following figure:
1881+
1882+*Figure: LMS-OTS Verification algorithm*
13941883
13951884 ![](../images/caliptra-rtl/docs/images/LMS_verifying_alg.png)
13961885
13971886 The high-level architecture of LMS is shown in the following figure.
13981887
1399-*Figure 46: LMS high-level architecture*
1888+*Figure: LMS high-level architecture*
14001889
14011890 ![](../images/caliptra-rtl/docs/images/LMS_high_level.png)
14021891
@@ -1421,7 +1910,7 @@
14211910
14221911 The Winternitz hash chain can be accelerated in hardware to enhance the performance of the design. For that, a configurable architecture is proposed that can reuse SHA256 engine. The LMS accelerator architecture is shown in the following figure, while H is SHA256 engine.
14231912
1424-*Figure 47: Winternitz chain architecture*
1913+*Figure: Winternitz chain architecture*
14251914
14261915 ![](../images/caliptra-rtl/docs/images/LMS_wntz_arch.png)
14271916
@@ -1449,14 +1938,21 @@
14491938
14501939 ### Address map
14511940
1452-The address map for LMS accelerator integrated into SHA256 is shown here: [sha256\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.sha256_reg).
1941+The address map for LMS accelerator integrated into SHA256 is shown here: [sha256\_reg -- clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.sha256_reg).
14531942
14541943 ## Adams Bridge - Dilithium (ML-DSA)
14551944
14561945 Please refer to the [Adams-bridge specification](https://github.com/chipsalliance/adams-bridge/blob/main/docs/AdamsBridgeHardwareSpecification.md)
14571946
14581947 ### Address map
1459-Address map of ML-DSA accelerator is shown here: [ML-DSA\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.mldsa_reg)
1948+Address map of ML-DSA accelerator is shown here: [ML-DSA\_reg -- clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.abr_reg)
1949+
1950+## Adams Bridge Kyber ML-KEM
1951+
1952+Please refer to the [Adams-bridge specification](https://github.com/chipsalliance/adams-bridge/blob/main/docs/AdamsBridgeHardwareSpecification.md)
1953+
1954+### Address map
1955+Address map of ML-KEM accelerator is shown here: [ML-KEM\_reg -- clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.abr_reg)
14601956
14611957 ## AES
14621958
@@ -1469,6 +1965,12 @@
14691965 ### Operation
14701966
14711967 For more information, see the [AES Programmer's Guide](https://github.com/vogelpi/opentitan/blob/aes-gcm-review/hw/ip/aes/doc/programmers_guide.md).
1968+
1969+## AES Endian
1970+
1971+The AES Core uses little endian for the DATA_IN and DATA_OUT registers. Caliptra allows a user to stream the data into and out of AES in big endian when AES_CLP.CTRL0.ENDIAN_SWAP is set to 1. This is done by swizzling the write and read data when a write targets DATA_IN or a read targets DATA_OUT.
1972+
1973+By default little endian is selected.
14721974
14731975 ### Signal descriptions
14741976
@@ -1482,7 +1984,7 @@
14821984 | DATA_OUT | output | Output block result of encryption or decryption. Stored in four 32-bit registers. |
14831985 | CTRL_SHADOWED.MANUAL_OPERATION | input | Configures the AES core to operation in manual mode. |
14841986 | CTRL_SHADOWED.PRNG_RESEED_RATE | input | Configures the rate of reseeding the internal PRNG used for masking. |
1485-| CTRL_SHADOWED.SIDELOAD | input | When asserted, AES core will use the key from the keyvault interface. |
1987+| CTRL_SHADOWED.SIDELOAD | input | When asserted, AES core will use the key from the key vault interface. |
14861988 | CTRL_SHADOWED.KEY_LEN | input | Configures the AES key length. Supports 128, 192, and 256-bit keys. |
14871989 | CTRL_SHADOWED.MODE | input | Configures the AES block cipher mode. |
14881990 | CTRL_SHADOWED.OPERATION | input | Configures the AES core to operate in encryption or decryption modes. |
@@ -1504,7 +2006,7 @@
15042006
15052007 ### Address map
15062008
1507-The AES address map is shown here: [aes\_clp\_reg — clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.aes_clp_reg).
2009+The AES address map is shown here: [aes\_clp\_reg -- clp Reference (chipsalliance.github.io)](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.aes_clp_reg).
15082010
15092011 ### SCA countermeasures
15102012
@@ -1797,19 +2299,19 @@
17972299 To underpin the results of the formal verification flow, the hardening of the GHASH module has been analyzed on the ChipWhisperer [CW310](https://rtfm.newae.com/Targets/CW310%20Bergen%20Board/) FPGA board.
17982300 For this analysis, power traces with the ChipWhisperer [Husky](https://rtfm.newae.com/Capture/ChipWhisperer-Husky/) scope were captured during GCM operations.
17992301 Afterwards a Test Vector Leakage Assessment (TVLA) with the [ot-sca toolset](https://github.com/lowRISC/ot-sca) has been performed.
1800-The setup is illustrated in Figure 1.
2302+The setup is illustrated in the following Figure.
18012303
18022304 ![](../images/caliptra-rtl/docs/images/cw310_cwhusky.jpeg)
18032305 :--:
1804-**Figure 1**: Target CW310 FPGA board (left) and the CW Husky scope (right).
2306+**Figure**: Target CW310 FPGA board (left) and the CW Husky scope (right).
18052307
18062308 ##### Setup
18072309
18082310 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure2.png)
18092311 :--:
1810-**Figure 2**: Measurement setup. The main components are the target board, the scope, and the SCA framework.
1811-
1812-Figure 2 gives a detailed overview of the measurement setup that has been utilized to capture the power traces.
2312+**Figure**: Measurement setup. The main components are the target board, the scope, and the SCA framework.
2313+
2314+The prior Figure gives a detailed overview of the measurement setup that has been utilized to capture the power traces.
18132315 The SCA evaluation framework ot-sca is the central component of the measurement setup.
18142316 It is responsible for communicating with the penetration testing framework that runs on the target FPGA board and with the scope.
18152317 Initially, ot-sca configures the scope (sample rate, number of samples) and the pentest framework (which input, how many encryptions, where to trigger).
@@ -1821,9 +2323,9 @@
18212323
18222324 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure3.png)
18232325 :--:
1824-**Figure 3**: Power trace with AES encryption rounds visible (*left*). Aligned traces when zooming in (*right*).
1825-
1826-Figure 3 depicts power traces captured during AES-GCM encryptions with the setup above.
2326+**Figure**: Power trace with AES encryption rounds visible (*left*). Aligned traces when zooming in (*right*).
2327+
2328+The prior Figure depicts power traces captured during AES-GCM encryptions with the setup above.
18272329 As shown in the figure, the traces are nicely aligned, allowing to perform a sound evaluation.
18282330
18292331 ##### Methodology
@@ -1835,9 +2337,9 @@
18352337
18362338 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure4.png)
18372339 :--
1838-**Figure 4:** TVLA plot showing leakage at around sample 1000. When increasing the number of traces (from 1000 to 10000), the leakage becomes more present. Note that the traces shown in this plot are taken from an arbitrary cryptographic hardware block and not AES.
1839-
1840-Figure 4 shows a TVLA plot that will be used throughout this document. The red lines mark the ± *t*-test border.
2340+**Figure:** TVLA plot showing leakage at around sample 1000. When increasing the number of traces (from 1000 to 10000), the leakage becomes more present. Note that the traces shown in this plot are taken from an arbitrary cryptographic hardware block and not AES.
2341+
2342+The prior Figure shows a TVLA plot that will be used throughout this document. The red lines mark the ± *t*-test border.
18412343
18422344 ###### Dataset Generation for FvsR IV & Key
18432345
@@ -1878,26 +2380,26 @@
18782380
18792381 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure5.png)
18802382 :--:
1881-**Figure 5:** AES-GCM block diagram. Red lines mark the trigger windows for each analysis step.
1882-
1883-As shown in Figure 5, we focus on analyzing (*i*) the generation of the hash subkey H, (*ii*) the encryption of the initial counter block S, (*iii*) the processing of the AAD blocks, (*iv*) the plaintext blocks, and (*v*) the tag generation. Each measurement is conducted with (*a*) masks off and (*b*) masks on to analyze the effectiveness of the masking countermeasure.
2383+**Figure:** AES-GCM block diagram. Red lines mark the trigger windows for each analysis step.
2384+
2385+As shown in the prior Figure, we focus on analyzing (*i*) the generation of the hash subkey H, (*ii*) the encryption of the initial counter block S, (*iii*) the processing of the AAD blocks, (*iv*) the plaintext blocks, and (*v*) the tag generation. Each measurement is conducted with (*a*) masks off and (*b*) masks on to analyze the effectiveness of the masking countermeasure.
18842386
18852387 ###### i) SCA Evaluation of Generating the Hash Subkey H
18862388
18872389 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure6ab.png)
18882390 :--:
18892391
1890-| **Figure 6a:** Masking Off - 100k traces - **Figure 6b:** Masking On - 1M traces |
2392+| **Figure:** Masking Off - 100k traces - **Figure:** Masking On - 1M traces |
18912393
18922394
18932395 ###### Interpretation
18942396
1895-The AES encryption is clearly visible in the form of 12 distinct peaks in the power traces shown Figures 6a and 6b.
2397+The AES encryption is clearly visible in the form of 12 distinct peaks in the power traces shown in the prior set of Figures.
18962398 The 12 peaks correspond to first the loading of the key and the all-zero block into the AES cipher core, followed by the initial round and the 10 full AES rounds (AES-128).
18972399 They spread over approximately 470 samples which corresponds to the 56 target clock cycles a full AES-128 encryption takes.
18982400
1899-If the masking is turned off (Figure 6a), first and second-order leakage is clearly visible throughout the operation.
1900-If the masking is on (Figure 6b), there is first-order leakage 1) at the beginning as well as 2) at the end of the operation.
2401+If the masking is turned off (set of graphs), first and second-order leakage is clearly visible throughout the operation.
2402+If the masking is on (set of graphs), there is first-order leakage 1) at the beginning as well as 2) at the end of the operation.
19012403
19022404 1. The leakage at the beginning of the operation is due to incrementing the IV/CTR value (inc32 function in GCM spec) which spreads across the first two AES rounds.
19032405 This produces first-order leakage as the inc32 function implementation isn’t masked.
@@ -1907,26 +2409,26 @@
19072409 The leakage is most likely due to how the FPGA implementation tool maps the flip flops of the hash subkey register shares to the available FPGA logic slices: if flip flops of the different shares get mapped to the same logic slice, the carry-chain and other muxing logic present in the logic slice can combine the various inputs thereby causing SCA leakage despite these logic outputs not being used.
19082410 We’ve observed similar effects in the past and there is [research giving more insight into this and other FPGA-specific issues](https://ieeexplore.ieee.org/document/10545383).
19092411
1910-To summarize, the observed first-order leakage if masking is on (Figure 6b) is not of concern for ASIC implementations.
2412+To summarize, the observed first-order leakage if masking is on is not of concern for ASIC implementations.
19112413
19122414 ###### ii) SCA Evaluation of Encrypting the Initial Counter Block
19132415
19142416 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure7ab.png)
19152417 :--:
19162418
1917-| **Figure 7a:** Masking Off - 100k traces - **Figure 7b:** Masking On - 1M traces |
2419+| **Figure:** Masking Off - 100k traces - **Figure:** Masking On - 1M traces |
19182420
19192421
19202422 ###### Interpretation
19212423
1922-Again, the AES encryption is clearly visible in the form of 12 peaks in the power traces shown Figures 7a and 7b.
2424+Again, the AES encryption is clearly visible in the form of 12 peaks in the power traces shown in the prior set of Figures.
19232425 This AES encryption corresponds to the generation of the encrypted initial counter block S.
19242426 The AES encryption is followed by another operation visible in the power trace: the computation of repeatedly used correction terms using the Galois-field multipliers inside GHASH.
19252427 This operation takes 33 target clock cycles (approximately 275 samples).
19262428
1927-If the masking is turned off (Figure 7a), first and second-order leakage is clearly visible throughout both operations while being more pronounced during the GHASH operation.
2429+If the masking is turned off (set of graphs), first and second-order leakage is clearly visible throughout both operations while being more pronounced during the GHASH operation.
19282430 This is because the GHASH block is smaller and thus produces less noise.
1929-If the masking is on (Figure 7b), there is first-order leakage 1) at the beginning as well as 2) between the two operations.
2431+If the masking is on (set of graphs), there is first-order leakage 1) at the beginning as well as 2) between the two operations.
19302432
19312433 1. As before, the leakage at the beginning of the operation is due to incrementing the IV/CTR value (inc32 function in GCM spec) which spreads across the first two AES rounds.
19322434 This produces first-order leakage as the inc32 function implementation isn’t masked.
@@ -1936,7 +2438,7 @@
19362438 As before, the leakage is most likely due to how the FPGA implementation tool maps the multiplexers in front of the GHASH state registers to the available FPGA logic slices: Since the multiplexers for both shares use the same control signals, the multiplexing logic can be combined even into the same look-up tables (LUTs) thereby causing SCA leakage.
19372439 We’ve observed similar effects in the past and there is [research giving more insight into this and other FPGA-specific issues](https://ieeexplore.ieee.org/document/10545383).
19382440
1939-To summarize, the observed first-order leakage if masking is on (FIgure 7b) is not of concern for ASIC implementations.
2441+To summarize, the observed first-order leakage if masking is on is not of concern for ASIC implementations.
19402442
19412443 ###### iii) SCA Evaluation of Processing the AAD Blocks
19422444
@@ -1945,31 +2447,31 @@
19452447 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure8ab.png)
19462448 :--:
19472449
1948-| **Figure 8a:** Masking Off - 50k traces - **Figure 8b:** Masking On - 10M traces |
2450+| **Figure:** Masking Off - 50k traces - **Figure:** Masking On - 10M traces |
19492451
19502452
19512453 ###### Interpretation
19522454
19532455 For AAD blocks, the AES cipher core is not involved.
19542456 However, during the computation of the first AAD block, the GHASH block needs to compute an additional correction term which is used for the very first block only.
1955-If the masking is turned off (Figure 8a), first- and second-order leakage is clearly visible but only for the first activity block.
2457+If the masking is turned off (first set of graphs), first- and second-order leakage is clearly visible but only for the first activity block.
19562458 The second activity block involves computing the additional correction terms which requires Share 1 of the encrypted initial counter block to be multiplied by Share 1 of the hash subkey.
19572459 But since the masking is off, both these values are zero for both the fixed and the random set and hence there is no SCA leakage.
1958-If the masking is turned on (Figure 8b), no SCA leakage is observable which is desirable.
2460+If the masking is turned on (second set of graphs), no SCA leakage is observable which is desirable.
19592461
19602462 ###### Processing AAD Block 1
19612463
19622464 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure9ab.png)
19632465 :--:
19642466
1965-| **Figure 9a:** Masking Off - 50k traces - **Figure 9b:** Masking On - 10M traces |
2467+| **Figure:** Masking Off - 50k traces - **Figure:** Masking On - 10M traces |
19662468
19672469
19682470 ###### Interpretation
19692471
19702472 For the second AAD block (and any subsequent AAD blocks) there is only one activity block corresponding to the Galois-field multiplication.
1971-If masking is turned off (Figure 9a), there is both first- and second-order leakage observable.
1972-If the masking is turned on (Figure 9b), no SCA leakage is observable which is desirable.
2473+If masking is turned off (first set of graphs), there is both first- and second-order leakage observable.
2474+If the masking is turned on (second set of graphs), no SCA leakage is observable which is desirable.
19732475
19742476 ###### iv) SCA Evaluation of Processing the PTX Blocks
19752477
@@ -1978,12 +2480,12 @@
19782480 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure10ab.png)
19792481 :--:
19802482
1981-| **Figure 10a:** Masking Off - 50k traces - **Figure 10b:** Masking On - 1M traces |
2483+| **Figure:** Masking Off - 50k traces - **Figure:** Masking On - 1M traces |
19822484
19832485
19842486 ###### Interpretation
19852487
1986-Like in [ii) SCA Evaluation of Encrypting the Initial Counter Block](#ii-sca-evaluation-of-encrypting-the-initial-counter-block) there is first-order leakage 1) at the beginning and 2) between the two operations if the masking is turned on (Figure 10b).
2488+Like in [ii) SCA Evaluation of Encrypting the Initial Counter Block](#ii-sca-evaluation-of-encrypting-the-initial-counter-block) there is first-order leakage 1) at the beginning and 2) between the two operations if the masking is turned on (first set of graphs).
19872489
19882490 1. As before, the leakage at the beginning of the operation is due to incrementing the IV/CTR value (inc32 function in GCM spec) which spreads across the first two AES rounds.
19892491 This produces first-order leakage as the inc32 function implementation isn’t masked.
@@ -1993,14 +2495,14 @@
19932495 But since the AAD and the plaintext have been chosen to be the same for all traces in the fixed and the random sets, the traces of the fixed set only produce all the same ciphertext and thus are expected to exhibit a static power signature for this step, whereas the ciphertext of the random set is randomized through the random key and IV.
19942496 However, since the ciphertext is not secret in the context of GCM, this leakage is of no concern.
19952497
1996-To summarize, the observed first-order leakage if masking is on (FIgure 10b) is not of concern.
2498+To summarize, the observed first-order leakage if masking is on (second set of graphs) is not of concern.
19972499
19982500 ###### Processing PTX Block 1
19992501
20002502 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure11ab.png)
20012503 :--:
20022504
2003-| **Figure 11a:** Masking Off - 50k traces - **Figure 11b:** Masking On - 1M traces |
2505+| **Figure:** Masking Off - 50k traces - **Figure:** Masking On - 1M traces |
20042506
20052507
20062508 ###### Interpretation
@@ -2013,7 +2515,7 @@
20132515 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure12ab.png)
20142516 :--:
20152517
2016-| **Figure 12a:** Masking Off - 50k traces - **Figure 12b:** Masking On - 1M traces |
2518+| **Figure:** Masking Off - 50k traces - **Figure:** Masking On - 1M traces |
20172519
20182520
20192521 ###### Interpretation
@@ -2023,12 +2525,12 @@
20232525 The GHASH state is unmasked (still masked with the encrypted initial counter block S) and Share 1 of S is added to write the final authentication tag to the data output registers readable by software.
20242526 2) In parallel to writing the final authentication tag to the data output registers, the internal state is all cleared to random values and an additional multiplication is triggered to clear the internal state of the Galois-field multipliers and the correction term registers.
20252527
2026-If masking is turned off (Figure 12a), there is both first- and second-order leakage observable during the first activity block (tag generation) but not during the clearing operation.
2027-If the masking is turned on (Figure 12b), some SCA leakage is observable between the two operations, i.e., when the final authentication tag is written to the output data registers.
2528+If masking is turned off (first set of graphs), there is both first- and second-order leakage observable during the first activity block (tag generation) but not during the clearing operation.
2529+If the masking is turned on (second set of graphs), some SCA leakage is observable between the two operations, i.e., when the final authentication tag is written to the output data registers.
20282530 This leakage is expected as both the fixed and the random data sets use a static AAD and plaintext.
20292531 This means, the tag for the fixed data set is fixed whereas the tags for the random set get randomized through the ciphertext (random due to the random key and IV).
20302532
2031-To summarize, the observed first-order leakage if masking is on (FIgure 12b) is not of concern.
2533+To summarize, the observed first-order leakage if masking is on (second set of graphs) is not of concern.
20322534
20332535 ##### Results – FvsR PTX & AAD
20342536
@@ -2040,16 +2542,16 @@
20402542 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure13ab.png)
20412543 :--:
20422544
2043-| **Figure 13a:** Masking Off - 50k traces - **Figure 13b:** Masking On - 1M traces |
2545+| **Figure:** Masking Off - 50k traces - **Figure:** Masking On - 1M traces |
20442546
20452547
20462548 ###### Interpretation
20472549
2048-There is no SCA leakage visible in both cases without masking (Figure 13a) and with masking turned on (Figure 13b).
2550+There is no SCA leakage visible in both cases without masking (first set of graphs) and with masking turned on (second set of graphs).
20492551 This is expected as the hash subkey generation doesn’t involve the plaintext and the AAD but only the key and IV.
20502552 Both the fixed and random set use the same static key and IV.
20512553
2052-This experiment was specifically done to check whether the leakage identified in Figure 6b and attributed to how the FPGA implementation tool maps the flip flops of the hash subkey register shares to the available FPGA logic slices.
2554+This experiment was specifically done to check whether the leakage identified in [i) SCA Evaluation of Generating the Hash Subkey H](#i-SCA-Evaluation-of-Generating-the-Hash-Subkey-H) and attributed to how the FPGA implementation tool maps the flip flops of the hash subkey register shares to the available FPGA logic slices.
20532555 As expected, the leakage peak is now gone.
20542556
20552557 ###### ii) SCA Evaluation of Encrypting the Initial Counter Block
@@ -2057,16 +2559,16 @@
20572559 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure14ab.png)
20582560 :--:
20592561
2060-| **Figure 14a:** Masking Off - 50k traces - **Figure 14b:** Masking On - 1M traces |
2562+| **Figure:** Masking Off - 50k traces - **Figure:** Masking On - 1M traces |
20612563
20622564
20632565 ###### Interpretation
20642566
2065-There is no SCA leakage visible in both cases without masking (Figure 14a) and with masking turned on (Figure 14b).
2567+There is no SCA leakage visible in both cases without masking (first set of graphs) and with masking turned on (second set of graphs).
20662568 This is expected as the encryption of the initial counter block and the subsequent computation of repeatedly used correction terms doesn’t involve the plaintext and the AAD but only the key and IV.
20672569 Both the fixed and random set use the same static key and IV.
20682570
2069-This experiment was specifically done to check whether the leakage identified in Figure 7b and attributed to how the FPGA implementation tool maps the multiplexers in front of the GHASH state registers to the available FPGA logic slices.
2571+This experiment was specifically done to check whether the leakage identified in [ii) SCA Evaluation of Encrypting the Initial Counter Block](#ii-SCA-Evaluation-of-Encrypting-the-Initial-Counter-Block) and attributed to how the FPGA implementation tool maps the multiplexers in front of the GHASH state registers to the available FPGA logic slices.
20702572 As expected, the leakage peak is now gone.
20712573
20722574 ###### iv) SCA Evaluation of Processing the PTX Block 0
@@ -2074,12 +2576,12 @@
20742576 ![](../images/caliptra-rtl/docs/images/GHASH_TVLA_Figure15ab.png)
20752577 :--:
20762578
2077-| **Figure 15a:** Masking Off - 100k traces - **Figure 15b:** Masking On - 1M traces |
2579+| **Figure:** Masking Off - 100k traces - **Figure:** Masking On - 1M traces |
20782580
20792581
20802582 ###### Interpretation
20812583
2082-With the masking turned off (Figure 15a), there is first-order leakage 1) at the beginning of the operation and 2) throughout the entire GHASH operation.
2584+With the masking turned off (first set of graphs), there is first-order leakage 1) at the beginning of the operation and 2) throughout the entire GHASH operation.
20832585
20842586 1. The leakage at the beginning of the operation is due to the input data (the plaintext) being written to an internal buffer register.
20852587 The AES cipher is operated in counter mode, meaning it doesn’t encrypt the input data but the counter value (incremented IV).
@@ -2088,7 +2590,7 @@
20882590 2. The GHASH operation then processes this ciphertext.
20892591 The observed leakage when the masking is off is expected.
20902592
2091-With the masking turned on (Figure 15b), the first-order leakage at the beginning of the operation remains visible. The reason for this is that the internal register buffering the previous input data is not masked.
2593+With the masking turned on (second set of graphs), the first-order leakage at the beginning of the operation remains visible. The reason for this is that the internal register buffering the previous input data is not masked.
20922594 This is of no concern as the leakage is not related to key or IV.
20932595
20942596 Another first-order leakage peak is visible between the AES encryption and the GHASH operation.
@@ -2267,6 +2769,50 @@
22672769 * HW also implements a HW function called SIGN\_PCR. This function takes the PCR digest that was generated by the previous routine and signs it using the key in key slot 7, following the same ECC sign flow defined in the [ECC](#ecc) section.
22682770 * The resulting PCR DIGEST is used only once for signing by the HW. If a new PCR signing is required, GEN\_PCR\_HASH needs to be redone.
22692771
2772+### ICCM write hash measurement (PCR4/PCR5)
2773+
2774+The SHA-512 accelerator (`sha512_acc_top`) includes an ICCM hash mode that provides hardware-only measurement of all data written to ICCM during firmware loading. This creates a tamper-evident record of what code actually landed in instruction memory, closing the gap between "firmware image was verified" and "firmware image was correctly copied."
2775+
2776+#### Overview
2777+
2778+Two dedicated PCR entries are used:
2779+
2780+| PCR | Name | Reset | Behavior |
2781+| :-- | :--- | :---- | :------- |
2782+| PCR4 | ICCM Current | Cleared on `fw_update_reset` (`iccm_unlock`) | Extended from zero on each firmware load — reflects only the currently running image |
2783+| PCR5 | ICCM Journey | Cleared only on cold reset (`cptra_pwrgood`) | Extended from previous value on each firmware load — accumulates a chain of all images ever loaded |
2784+
2785+
2786+Both PCR entries are write-protected: only the ICCM hash engine (`pv_write[1]`) can write nonzero values to PCR4 and PCR5. The normal SHA512/crypto PCR extend path (`pv_write[0]`) and firmware AHB writes are blocked from targeting these entries. Firmware may clear PCR4 or PCR5 to zero via `PCR_CTRL[n].clear` as a field escape hatch, but cannot write arbitrary values.
2787+
2788+#### Operation
2789+
2790+1. **Autonomous arming**: HW measures the ICCM region automatically. The existing per-bank ICCM-write snoop sets a sticky internal `iccm_armed` flag on the very first write it sees after reset (or after `fw_update_reset` releases the `iccm_unlock`-driven clear). On the same cycle, HW acquires the SHA accelerator lock via the LOCK register's `hwset` path, blocking any concurrent SOC access for the duration of the measurement. Firmware does not need to take any action to enable the feature; ROM simply performs the memcpy as normal.
2791+
2792+2. **ICCM write capture**: As ROM copies firmware from the mailbox to ICCM via CPU store instructions, each ICCM bank write is captured by the SHA accelerator and accumulated into a SHA-384 hash. The hash runs in parallel with the copy — no backpressure or stall. Data is hashed as little-endian 32-bit words (native CPU byte order). The combinational OR of the live snoop into the `iccm_mode` enable guarantees the very first dword is captured in the same cycle, before `iccm_armed` itself updates on the next clock edge.
2793+
2794+3. **Finalization on ICCM lock**: When ROM sets `INTERNAL_ICCM_LOCK`, the SHA accelerator finalizes the hash (padding and last compression), producing a 384-bit ICCM digest.
2795+
2796+4. **PCR extend**: An internal FSM then performs proper PCR extend operations:
2797+ - Reads PCR4 current value (zeros after clear), computes `SHA-384(PCR4 || ICCM_digest)`, writes result to PCR4
2798+ - Reads PCR5 current value, computes `SHA-384(PCR5 || ICCM_digest)`, writes result to PCR5
2799+ - The extend uses the same `sha512_core` instance with the same byte ordering as the normal PCR hash extend path, ensuring consistent results
2800+
2801+5. **Lock release**: After both PCR extends complete, the sticky `iccm_mode_done` flag latches (blocking re-trigger until the next `iccm_unlock`) and the SHA accelerator lock is released for normal firmware use.
2802+
2803+#### Security properties
2804+
2805+- HW-autonomous arming closes the bypass window where firmware could "forget" to enable the feature — the hash starts unconditionally on the first ICCM write the snoop sees
2806+- ICCM measurement is single-shot per boot cycle: once `iccm_mode_done` latches, firmware cannot re-trigger it to overwrite PCR4/PCR5
2807+- The hash captures the ground truth of ICCM write data at the memory bank interface — eliminating TOCTOU gaps between verification and copy
2808+- Skipping any step (trigger, copy, or lock) results in empty PCRs, causing attestation failure
2809+- The feature operates correctly regardless of `boot_flow_monitor_en` — if debug-unlocked tests skip ICCM mode, PCRs stay empty and attestation fails (no security bypass)
2810+- PCR4 clear mechanism (`pcr4_hwclr`) is tied to `iccm_unlock` (fires on `fw_update_reset`), ensuring fresh measurement on each firmware update
2811+
2812+#### Timing impact
2813+
2814+The SHA-384 computation runs in parallel with ROM's ICCM copy. Only finalization (~80 cycles) and the two PCR extend operations (~210 cycles total) occur after `ICCM_LOCK` is set. Total added latency: ~290 cycles, invisible to boot time.
2815+
22702816 ## Key vault
22712817
22722818 Key Vault (KV) is a register file that stores the keys to be used by the microcontroller, but this register file is not observed by the microcontroller. Each cryptographic function has a control register and functional block designed to read from and write to the KV. 
@@ -2292,9 +2838,9 @@
22922838 | Lock wr\[0\] | core_only_rst_b | Setting the lock wr field prevents the entry from being written by the microcontroller. Keys are always locked. After a lock is set, it cannot be reset until cptra_rst_b is de-asserted. |
22932839 | Lock use\[1\] | core_only_rst_b | Setting the lock use field prevents the entry from being used in any cryptographic blocks. After the lock is set, it cannot be reset until cptra_rst_b is de-asserted. |
22942840 | Clear\[2\] | cptra_rst_b | If unlocked, setting the clear bit causes KV to clear the associated entry. The clear bit is reset after entry is cleared. |
2295-| Copy\[3\] | cptra_rst_b | ENHANCEMENT: Setting the copy bit causes KV to copy the key to the entry written to Copy Dest field. |
2296-| Copy Dest\[8:4\] | cptra_rst_b | ENHANCEMENT: Destination entry for the copy function. |
2297-| Dest_valid\[16:9\] | hard_reset_b | KV entry can be used with the associated cryptographic block if the appropriate index is set. <br>\[0\] - HMAC KEY <br>\[1\] - HMAC BLOCK <br>\[2\] - MLDSA SEED <br>\[3\] - ECC PRIVKEY <br>\[4\] - ECC SEED <br>\[5\] - AES KEY <br>\[7:6\] - RSVD |
2841+| rsvd0\[3\] |||
2842+| rsvd1\[8:4\] |||
2843+| Dest_valid\[16:9\] | hard_reset_b | KV entry can be used with the associated cryptographic block if the appropriate index is set. <br>\[0\] - HMAC KEY <br>\[1\] - HMAC BLOCK <br>\[2\] - MLDSA SEED <br>\[3\] - ECC PRIVKEY <br>\[4\] - ECC SEED <br>\[5\] - AES KEY <br>\[6\] - MLKEM SEED <br>\[7\] - MLKEM MSG <br>\[8\] - AXI DMA DATA |
22982844 | last_dword\[20:19\] | hard_reset_b | Store the offset of the last valid dword, used to indicate the last cycle for read operations. |
22992845
23002846
@@ -2310,7 +2856,66 @@
23102856
23112857 Similarly, after programming the key vault write control and initiating the cryptographic function that generates the key to be written, FW needs to query the associated key vault write status to confirm that the requested key was generated and written successfully.
23122858
2859+While the crypto engine, key vault read, or key vault write blocks are active, the read and write control registers are locked. After reading the status register and confirming that the operation was successful, the next key vault control can be programmed.
2860+
23132861 When a key is read from the key vault, the API register is locked and any result generated from the cryptographic block is not readable by firmware. The digest can only be sent to the key vault by appropriately programming the key vault write controls. After the cryptographic block completes its operation, the lock is cleared and the key is cleared from the API registers.
2862+
2863+Key vault read errors will prevent the crypto engine from accepting new commands. The engine will require zeroization in order to clear the error and resume normal operation.
2864+
2865+### Key vault key-length-mismatch detection
2866+
2867+Each cryptographic consumer that reads from KV performs a length check
2868+between the KV entry's stored `last_dword` and the consumer's
2869+`expected_key_size` port (derived from mode, e.g., HMAC-384 vs HMAC-512,
2870+or fixed by the consumer, e.g., ECC P-384, MLDSA/MLKEM seed, OCP LOCK
2871+MEK). The KV read-mux broadcasts each addressed entry's stored
2872+`last_dword` on `kv_rd_resp_t.entry_last_dword`, and every
2873+`kv_read_client` latches that value into a local `stored_last_dword`
2874+register.
2875+A stored entry *larger* than the
2876+consumer's expected size is accepted. A stored entry *smaller* than the
2877+consumer's expected size triggers `KV_RD_LEN_MISMATCH`. Access-control
2878+(`dest_valid` + `kv_read_rule_check`) still gates which slots each
2879+consumer may touch, so prefix use of an oversized entry does not
2880+widen attack surface.
2881+
2882+When mismatch fires, `error_code` is registered to `KV_RD_LEN_MISMATCH`
2883+and self-holds via the existing mux fall-through (cleared only by
2884+`rst_b` or `zeroize`). The length check enforces *how much of
2885+the slot is meaningful* and closes a key-substitution class where a
2886+shorter stored key would otherwise be silently zero-padded (or worse,
2887+consumed with undefined-tail bits) by a wider engine.
2888+
2889+**Two check-time modes**, selected by parameter `LEN_CHECK_AT_KEY_USE`:
2890+- `LEN_CHECK_AT_KEY_USE=0` (default) — check fires on `read_done` (KV
2891+ FSM's `KV_DONE` state), comparing `stored_last_dword` to the fixed
2892+ `expected_key_size` the consumer wires. Used by consumers whose
2893+ expected size is stable at KV-read time (ECC privkey/seed, AXI-DMA
2894+ MEK, MLDSA/MLKEM seeds and message).
2895+- `LEN_CHECK_AT_KEY_USE=1` — check fires on the consumer's
2896+ `check_key_size` strobe (typically at `INIT`/`START`/op-commit).
2897+ Used by consumers whose expected size is not stable until the op
2898+ commits (HMAC and AES, whose mode/key_len may be programmed after
2899+ the KV read completes).
2900+
2901+**HMAC** enables the check on the key path only. `hmac_key_kv_read`
2902+uses `LEN_CHECK_AT_KEY_USE=1` with `check_key_size = (init_reg |
2903+next_reg) & kv_key_data_present` and `expected_key_size =
2904+hmac_expected_key_size` (11 for HMAC-384, 15 for HMAC-512). The HMAC
2905+block is a message chunk, not a security-sized key, and legitimate
2906+consumers (notably the OCP LOCK HEK seed at `OCP_LOCK_HEK_NUM_DWORDS=8`
2907+dwords routed to `KV_DEST_IDX_HMAC_BLOCK`) may supply KV entries
2908+shorter than the mode's key size.
2909+
2910+**AES** derives `expected_key_size` from the runtime-selectable
2911+`CTRL_SHADOWED.key_len` (128/192/256 → 3/5/7), exposed to the CLP
2912+wrapper via `aes2caliptra.key_len`. The check is armed at
2913+`kv_key_done | keymgr_key.valid`, so any FW re-program of `key_len`
2914+that would create an entry-too-small condition is caught before AES
2915+samples the key. AES does not raise an interrupt on KV errors; FW
2916+must observe `AES_KV_RD_KEY_STATUS.ERROR` after the status VALID bit
2917+sets. The `AES_KV_RD_KEY_STATUS.ERROR` field encodes the KV error
2918+code (`KV_SUCCESS=0`, `KV_READ_FAIL=1`, `KV_RD_LEN_MISMATCH=3`).
23142919
23152920 If multiple iterations of the cryptographic function are required, the key vault read and write controls must be programmed for each iteration. This ensures that the lock is set and the digest is not readable.
23162921
@@ -2334,7 +2939,10 @@
23342939 | ecc_pkey_dest_valid\[9\] | ECC PKEY is a valid destination. |
23352940 | ecc_seed_dest_valid\[10\] | ECC SEED is a valid destination. |
23362941 | aes_key_dest_valid\[11\] | AES KEY is a valid destination. |
2337-| rsvd\[31:12\] | Reserved field |
2942+| mlkem_seed_dest_valid\[12\] | MLKEM SEED is a valid destination. |
2943+| mlkem_msg_dest_valid\[13\] | MLKEM MSG is a valid destination. |
2944+| dma_data_dest_valid\[14\] | DMA DATA is a valid destination. |
2945+| rsvd\[31:15\] | Reserved field |
23382946
23392947
23402948 | KV Status Reg | Description |
@@ -2342,6 +2950,41 @@
23422950 | ready\[0\] | Key vault control is idle and ready for a command. |
23432951 | valid\[1\] | Requested flow is done. |
23442952 | error\[9:2\] | SUCCESS - 0x0 - Key Vault flow was successful <br>KV_READ_FAIL - 0x1 - Key Vault Read flow failed <br>KV_WRITE_FAIL - 0x2 - Key Vault Write flow failed |
2953+
2954+
2955+### Key vault endianness and byte ordering
2956+
2957+The Key Vault stores each entry as an array of 16 DWORDs (32-bit words), indexed KV\[0\] through KV\[15\]. The KV read and write clients perform byte and DWORD ordering transformations so that data written by one engine can be correctly consumed by another.
2958+
2959+The KV write client has a configurable parameter, `KV_WRITE_SWAP_DWORDS`, that controls DWORD ordering when writing result data into a KV entry. When set to 1 (default), the write client reverses DWORD order so that KV\[0\] holds the most-significant DWORD: KV\[offset\] = data\[N−1−offset\]. When set to 0, DWORDs are stored sequentially: KV\[offset\] = data\[offset\]. The KV read client always reads sequentially from KV\[0\] through KV\[15\]; each engine applies its own register-level mapping.
2960+
2961+#### Per-engine endianness conventions
2962+
2963+| Engine | Native endianness | KV write SWAP\_DWORDS | KV read register mapping | Notes |
2964+| :----- | :---------------- | :-------------------- | :----------------------- | :---- |
2965+| HMAC-512 | Big-endian | 1 (default) | Sequential: BLOCK\[d\] = KV\[d\], KEY\[d\] = KV\[d\] | Block read supports PAD and HMAC auto-padding. |
2966+| SHA-512 | Big-endian | 1 (default) | Sequential: BLOCK\[d\] = KV\[d\] | Block read supports PAD. |
2967+| ECC (P-384) | Big-endian | 1 (default) | Sequential: PRIVKEY\[d\] = KV\[d\], SEED\[d\] = KV\[d\] | -- |
2968+| AES | Little-endian | 0 | Byte swap per DWORD: key\_reg\[d\]\[b\] = KV\_data\[3−b\] | CTRL0.ENDIAN\_SWAP optionally swaps bytes in FW DATA\_IN/DATA\_OUT registers. |
2969+| ML-KEM | Little-endian | 0 | DWORD-reversed: SEED\_D\[d\] = KV\[N−1−d\], SEED\_Z\[i\] = KV\[2N−1−i\] | Shared key undergoes DWORD reversal in the ABR controller before the write client. |
2970+| ML-DSA | Little-endian | N/A (no KV write) | DWORD-reversed: SEED\[d\] = KV\[N−1−d\] | -- |
2971+
2972+
2973+**Write path:** HMAC, SHA-512, and ECC produce results with the most-significant DWORD at the highest internal index; the write client reversal (SWAP\_DWORDS=1) places the most-significant DWORD at KV\[0\]. AES stores its 128-bit (4 DWORD) output sequentially. The ML-KEM shared key is pre-reversed in the ABR controller (`mlkem_sharedkey_data[d] = shared_key[SHAREDKEY_NUM_DWORDS-1-d]`), producing the same KV layout as the big-endian engines despite using SWAP\_DWORDS=0.
2974+
2975+**Read path:** Big-endian engines (HMAC, SHA-512, ECC) use sequential mapping; register\[d\] receives KV\[d\]. AES applies a per-DWORD byte swap to convert from big-endian to its little-endian internal format. ML-KEM and ML-DSA reverse the DWORD index (`SEED[d]` is written when `kv_read_offset == N-1-d`), producing a full byte reversal of the original data.
2976+
2977+#### Firmware byte-ordering rules
2978+
2979+When firmware passes data between engines via software registers (without using KV), it must perform the following transformations. In this table, "big-endian" means the lowest-addressed register (index 0) holds the most-significant DWORD; "little-endian" means index 0 holds the least-significant DWORD. AES is little-endian but additionally byte-swaps each DWORD on the KV read path, so firmware must apply `BSWAP32` per DWORD when writing AES key registers directly.
2980+
2981+| Source → Destination | Transformation | Example |
2982+| :--- | :--- | :--- |
2983+| Big-endian → big-endian | Copy DWORDs directly | HMAC tag → ECC seed |
2984+| Big-endian → little-endian | Reverse DWORD order: DEST\[i\] = SRC\[N−1−i\] | HMAC tag → ML-KEM seed |
2985+| Big-endian → AES | Byte-swap each DWORD: AES\_KEY\[i\] = BSWAP32(src\[i\]) | HMAC tag → AES key |
2986+| Little-endian → AES | Reverse DWORDs and byte-swap each: AES\_KEY\[i\] = BSWAP32(src\[N−1−i\]) | ML-KEM shared key → AES key |
2987+| Little-endian → big-endian (non-AES) | Reverse DWORD order only: DEST\[i\] = src\[N−1−i\] | ML-KEM shared key → HMAC block |
23452988
23462989
23472990 ### De-obfuscation engine
@@ -2363,12 +3006,12 @@
23633006
23643007 ### Key vault de-obfuscation block operation
23653008
2366-A de-obfuscation engine (DOE) is used in conjunction with AES cryptography to de-obfuscate the UDS and field entropy.  
2367-
2368-1. The obfuscation key is driven to the AES key. The data to be decrypted (either obfuscated UDS or obfuscated field entropy) is fed into the AES data. 
2369-2. An FSM manually drives the AES engine and writes the decrypted data back to the key vault. 
2370-3. FW programs the DOE with the requested function (UDS or field entropy de-obfuscation), and the destination for the result. 
2371-4. After de-obfuscation is complete, FW can clear out the UDS and field entropy values from any flops until cptra\_pwrgood de-assertion.  
3009+A de-obfuscation engine (DOE) is used in conjunction with AES cryptography to de-obfuscate the UDS and field entropy and HEK seed.  
3010+
3011+1. The obfuscation key is wired to DOE engine. The data to be decrypted (either obfuscated UDS, obfuscated field entropy, or obfuscated HEK seed) is fed into the DOE data.
3012+2. An FSM manually drives the DOE engine and writes the decrypted data back to the key vault. 
3013+3. FW programs the DOE with the requested function (UDS, field entropy, or HEK seed de-obfuscation), and the destination for the result. 
3014+4. After de-obfuscation is complete, FW can clear out the UDS, field entropy, and HEK seed values from any flops until cptra\_pwrgood de-assertion.  
23723015
23733016 The following tables describe DOE register and control fields.
23743017
@@ -2381,19 +3024,262 @@
23813024
23823025 | DOE Ctrl Fields | Reset | Description |
23833026 | :--------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
2384-| COMMAND\[1:0\] | Cptra_rst_b | 2’b00 Idle <br>2’b01 Run UDS flow <br>2’b10 Run FE flow <br>2’b11 Clear Obf Secrets |
2385-| DEST\[4:2\] | Cptra_rst_b | Destination register for the result of the de-obfuscation flow. Field entropy writes into DEST and DEST+1 <br>Key entry only, can’t go to PCR . |
3027+| CMD\[1:0\] | Cptra_rst_b | 2’b00 Idle <br>2’b01 Run UDS flow <br>2’b10 Run FE flow <br>2’b11 Clear Obf Secrets |
3028+| DEST\[6:2\] | Cptra_rst_b | Destination register for the result of the de-obfuscation flow. Field entropy writes into DEST and DEST+1 <br>Key entry only, can’t go to PCR . |
3029+| CMD_EXT\[8:7\] | Cptra_rst_b | 2’b00 Idle (or running a standard, non-extended command) <br>2’b01 Run OCP LOCK HEK seed flow <br>2’b10 RESERVED <br>2’b11 RESERVED |
23863030
23873031
23883032 ### Key vault de-obfuscation flow 
23893033
2390-1. ROM loads IV into DOE. ROM writes to the DOE control register the destination for the de-obfuscated result and sets the appropriate bit to run UDS and/or the field entropy flow. 
3034+1. ROM loads IV into DOE. ROM writes to the DOE control register the destination for the de-obfuscated result and sets the appropriate bit to run UDS, field entropy, and/or HEK seed flow. 
23913035 2. DOE state machine takes over and loads the Caliptra obfuscation key into the key register. 
23923036 3. Next, either the obfuscated UDS or field entropy are loaded into the block register 4 DWORDS at a time. 
23933037 4. Results are written to the KV entry specified in the DEST field of the DOE control register. 
23943038 5. State machine resets the appropriate RUN bit when the de-obfuscated key is written to KV. FW can poll this register to know when the flow is complete.
23953039 6. The clear obf secrets command flushes the obfuscation key, the obfuscated UDS, and the field entropy from the internal flops. This should be done by ROM after both de-obfuscation flows are complete.
23963040
3041+## Key vault boot flow transition enforcement
3042+
3043+The Key Vault Boot Flow Transition Enforcement feature provides hardware-enforced integrity monitoring and access control for DICE key derivation across boot phase transitions (ROM->FMC->RT). It detects ICCM code execution transitions, validates key vault state at each boundary, and atomically applies lock/clear enforcement to key slots.
3044+
3045+### Overview
3046+
3047+The feature consists of three cooperating blocks:
3048+
3049+1. **Boot Flow Monitor** (in `caliptra_top`): Detects ROM->FMC and FMC->RT transitions by observing ICCM memory bank read enables against programmed address regions.
3050+2. **KV Monitor** (in `kv`): Validates dest_valid permissions and crypto write counts on DICE key slots at each transition boundary.
3051+3. **KV Enforcement** (in `kv`): Atomically applies lock_wr, lock_use, and slot clearing at each transition.
3052+
3053+*Figure: KV Boot Flow Transition Enforcement high-level block diagram*
3054+
3055+![](../images/caliptra-rtl/docs/images/kv_monitor.png)
3056+
3057+### Boot flow monitor
3058+
3059+The boot flow monitor detects firmware execution phase transitions by spying the ICCM memory interface. It compares bank-level read addresses against programmed FMC and RT region boundaries.
3060+
3061+#### ICCM region registers
3062+
3063+Four shadow-hardened registers define the FMC and RT code regions within ICCM address space:
3064+
3065+| Register | Address | Description |
3066+| :------- | :------ | :---------- |
3067+| INTERNAL_ICCM_FMC_START_ADDR | 0x30030650 | Start address of FMC region (18-bit ICCM-relative) |
3068+| INTERNAL_ICCM_FMC_END_ADDR | 0x30030654 | End address of FMC region (inclusive) |
3069+| INTERNAL_ICCM_RT_START_ADDR | 0x30030658 | Start address of RT region (18-bit ICCM-relative) |
3070+| INTERNAL_ICCM_RT_END_ADDR | 0x3003065C | End address of RT region (inclusive) |
3071+| INTERNAL_ICCM_REGION_LOCK | 0x30030660 | W1S lock -- once set, address registers cannot be modified until reset |
3072+
3073+
3074+These registers use the `caliptra_prim_subreg_shadow` primitive for glitch hardening:
3075+- **2-phase write protocol**: Each register must be written twice with the same value to commit. A single write updates only the shadow copy; the second matching write commits to the primary register.
3076+- **Phase-clear-on-read**: A read operation resets the write phase to 0, preventing stale partial writes from persisting.
3077+- **Error lockout**: If the shadow and committed copies diverge (storage fault), all further writes are blocked until reset.
3078+- **Error reporting**: Storage faults assert `CPTRA_HW_ERROR_FATAL.shadow_storage_err[5]`. Phase-1/phase-0 mismatches assert `CPTRA_HW_ERROR_NON_FATAL.shadow_update_err[3]`.
3079+
3080+The effective lock for the boot flow monitor is `iccm_region_lock & iccm_all_shadows_committed` -- both the lock register must be set AND all four address registers must have completed their 2-phase writes.
3081+
3082+#### Transition detection
3083+
3084+The monitor uses MuBi4-encoded signals for glitch resistance:
3085+
3086+| Signal | Encoding | Meaning |
3087+| :----- | :------- | :------ |
3088+| `boot_flow_fmc` | MuBi4True/False | CPU has begun executing from the FMC region |
3089+| `boot_flow_rt` | MuBi4True/False | CPU has begun executing from the RT region |
3090+| `boot_flow_error` | MuBi4True/False | Fatal error detected in boot flow |
3091+
3092+
3093+Transitions are one-way: once `boot_flow_fmc` becomes True, it remains True until reset. The monitor fires on the first ICCM read within the FMC region (after effective lock is set), and similarly for RT.
3094+
3095+#### Error conditions
3096+
3097+`boot_flow_error` is asserted (fatal) when any of the following occur:
3098+- ICCM fetch while region lock is not set or shadow registers are not committed
3099+- RT region fetch while `boot_flow_fmc` is False (illegal ROM->RT jump -- the RT transition is gated on FMC, so this fires the error without producing a transient `boot_flow_rt` pulse)
3100+- ICCM fetch outside both the FMC and RT programmed regions after region lock is set (out-of-range execution)
3101+- Any boot flow MuBi4 signal enters an invalid (non-True, non-False) encoding state
3102+
3103+#### Simulation support
3104+
3105+In simulation, `boot_flow_monitor_en` defaults to 0 (disabled). The testbench overrides this signal with a `force` when testing the feature. In hardware, the monitor is enabled when `debug_locked` is asserted AND `scan_mode` is deasserted. The monitor is disabled when debug is unlocked (to allow JTAG ICCM access and fake-ROM flows) and during scan mode (to prevent false transitions from clock-override activity on the ICCM banks).
3106+
3107+### KV monitor
3108+
3109+At each boot phase transition, the KV monitor validates that the expected DICE key slots are correctly populated. The monitor checks **only DICE derivation key slots** (0–9) — optional feature keys (Stable Owner Key, OCP Lock keys) are excluded from monitoring because they are conditionally derived and do not participate in the DICE trust chain. A mismatch triggers `kv_monitor_alert`, which escalates to `CPTRA_HW_ERROR_FATAL.kv_error[4]` and flushes all key entries.
3110+
3111+#### ROM->FMC checks (on `enter_fmc`)
3112+
3113+| Slot | Name | Expected dest_valid |
3114+| :--- | :--- | :------------------ |
3115+| 0 | SI_IDEV | AES_KEY |
3116+| 1 | SI_LDEV | AES_KEY |
3117+| 2 | KEY_LADDER | HMAC_KEY |
3118+| 6 | FMC_CDI | HMAC_KEY &#124; MLDSA_SEED &#124; ECC_SEED |
3119+| 7 | FMC_ECDSA | ECC_PKEY |
3120+| 8 | FMC_MLDSA | MLDSA_SEED |
3121+
3122+
3123+Additionally, per-slot crypto write counters verify **exact** expected derivation counts:
3124+- Slot 6 (FMC_CDI): == 4 writes (IDevID CDI + LDevID intermediate + LDevID CDI + FMC Alias CDI)
3125+- Slot 7 (FMC_ECDSA): == 2 writes (IDevID ECC keygen + FMC Alias ECC keygen)
3126+- Slot 8 (FMC_MLDSA): == 2 writes (IDevID MLDSA keygen + FMC Alias MLDSA keygen)
3127+
3128+An exact match (rather than a minimum threshold) detects both truncated DICE chains (too few writes, indicating a skipped derivation step) and glitch-replayed operations (too many writes, which could overwrite the final safe key with an earlier intermediate value such as raw UDS).
3129+
3130+Write counters are 3-bit saturating counters that reset only on hard reset (`cptra_pwrgood`) or `flush_keyvault`, persisting across warm and FW update resets. Since ROM does not re-derive DICE keys on warm or FW update reset, the counters retain their cold-boot values and pass the exact-match check on subsequent transitions.
3131+
3132+#### FMC->RT checks (on `enter_rt`)
3133+
3134+| Slot | Name | Expected dest_valid |
3135+| :--- | :--- | :------------------ |
3136+| 4 | RT_CDI | HMAC_KEY &#124; MLDSA_SEED &#124; ECC_SEED |
3137+| 5 | RT_ECDSA | ECC_PKEY |
3138+| 9 | RT_MLDSA | MLDSA_SEED |
3139+
3140+
3141+### KV enforcement
3142+
3143+Enforcement is applied continuously based on the current boot phase and atomically at transitions.
3144+
3145+#### Lock enforcement (continuous)
3146+
3147+| Condition | Slots affected | Action |
3148+| :-------- | :------------- | :----- |
3149+| `boot_flow_fmc` = True | 0, 1, 2, 6, 7, 8 | `lock_wr` asserted via hwset (HW-driven, cannot be cleared by SW) |
3150+| `boot_flow_rt` = True | 4, 5, 9 | `lock_wr` asserted via hwset |
3151+| `boot_flow_rt` = True | 6, 7, 8 | `lock_use` asserted via hwset (FMC keys cannot be used in RT) |
3152+
3153+
3154+The `lock_wr` and `lock_use` fields have `hwset` property in the register definition, allowing hardware to set them without firmware intervention. Once set, they can only be cleared by `core_only_rst_b` de-assertion.
3155+
3156+#### Slot clearing (atomic, on transition edge)
3157+
3158+**DICE slots** — unconditionally cleared or preserved at each transition:
3159+
3160+| Slot | Purpose | ROM→FMC | FMC→RT |
3161+| :--- | :------ | :------ | :----- |
3162+| 0 | SI_IDEV | Preserved | Preserved |
3163+| 1 | SI_LDEV | Preserved | Preserved |
3164+| 2 | KEY_LADDER | Preserved | Preserved |
3165+| 3 | TMP | Cleared | Cleared |
3166+| 4 | RT_CDI | Cleared | Preserved |
3167+| 5 | RT_ECDSA | Cleared | Preserved |
3168+| 6 | FMC_CDI | Preserved | Preserved |
3169+| 7 | FMC_ECDSA | Preserved | Preserved |
3170+| 8 | FMC_MLDSA | Preserved | Preserved |
3171+| 9 | RT_MLDSA | Cleared | Preserved |
3172+| 10–14 | Unused | Cleared | Cleared |
3173+
3174+
3175+**Conditionally-preserved slots** — behavior depends on active mode:
3176+
3177+| Slot | Purpose | Default (no optional features) | `stable_owner_key_en` | `ocp_lock_mode_en` |
3178+| :--- | :------ | :----------------------------- | :-------------------- | :----------------- |
3179+| 15 | Stable Owner Key | Cleared | Preserved | Cleared (mutually exclusive) |
3180+| 16 | MDK | Cleared | Cleared | Preserved |
3181+| 17–21 | Unused OCP range | Cleared | Cleared | Cleared |
3182+| 22 | HEK seed | Cleared | Cleared | Preserved |
3183+| 23 | MEK | Cleared | Cleared | **Always cleared** (DMA-accessible) |
3184+
3185+
3186+Clearing destroys the key data and resets `dest_valid` and `last_dword` for the affected slots.
3187+
3188+#### Conditional slot preservation
3189+
3190+Two optional Caliptra features populate KV slots that must survive boot transitions when the feature is active, but must be cleared when inactive. These slots are **not monitored** (no dest_valid checks, no write counters) — the monitor is exclusively for DICE keys. Only the enforcement block (slot clearing) handles them conditionally.
3191+
3192+**Stable Owner Key (Slot 15)**
3193+
3194+The Stable Owner Root Key is conditionally derived by ROM when all three conditions are met:
3195+
3196+- `SUBSYSTEM_MODE_en` = 1 (Caliptra operating in subsystem mode)
3197+- `OCP_LOCK_MODE_en` = 0 (OCP Lock feature is not active)
3198+- `SS_FW_FEATURE_CFG.STABLE_OWNER_KEY_EN` = 1 (SoC configuration, written prior to `CPTRA_FUSE_WR_DONE`, enabling the stable owner key feature)
3199+
3200+The combined signal `stable_owner_key_en` is computed in `soc_ifc_top` and routed to the Key Vault. When active, slot 15 is excluded from `boot_flow_key_clear` at both ROM-to-FMC and FMC-to-RT transitions. When inactive, slot 15 is cleared normally.
3201+
3202+**OCP Lock Keys (Slots 16 and 22)**
3203+
3204+When OCP Lock mode is enabled (`ocp_lock_mode_en` = 1 from the `ss_ocp_lock_en` strap), DOE populates slot 16 (MDK) and slot 22 (HEK seed) before ROM runs. FMC and RT firmware require these keys for EPK, VEK, and MEK derivation in OCP Lock flows.
3205+
3206+When `ocp_lock_mode_en` is active, slots 16 and 22 are excluded from clearing at both transitions. When inactive, they are cleared normally.
3207+
3208+**Slot 23 (MEK) is always cleared** regardless of `ocp_lock_mode_en`. MEK has `DMA_DATA` in its `dest_valid` (it is DMA-accessible for key release), making it a security risk if it persists across transitions. RT firmware re-derives MEK when needed during OCP Lock key release flows.
3209+
3210+Only the specific slots that ROM or FMC actually derive (16 and 22) are preserved — not the entire OCP Lock range (16–23). Slots 17–21 and 23 are always cleared.
3211+
3212+**Mutual exclusion**: Stable Owner Key and OCP Lock are mutually exclusive by construction — `stable_owner_key_en` includes `~OCP_LOCK_MODE_en` in its definition. When OCP Lock is enabled, slot 15 is always cleared even if `SS_FW_FEATURE_CFG.STABLE_OWNER_KEY_EN` = 1.
3213+
3214+#### Error escalation
3215+
3216+Any of the following trigger all key entries to be flushed:
3217+- `boot_flow_error` = MuBi4True
3218+- `kv_monitor_alert` (dest_valid mismatch or write count violation)
3219+- `kv_multi_write_err` (existing: multiple crypto engines writing simultaneously)
3220+
3221+The error is reported as `CPTRA_HW_ERROR_FATAL.kv_error[4]`, which is unmasked and always triggers an interrupt.
3222+
3223+### DOE lockdown
3224+
3225+Once the boot flow monitor detects that execution has transitioned to FMC or RT (i.e., `boot_flow_fmc` or `boot_flow_rt` is True), the DOE command register is forcibly cleared via `doe_cmd_lock`. This prevents any new de-obfuscation commands from being issued after the DICE key derivation phase is complete, closing the window for an attacker to re-derive secrets using the obfuscation key.
3226+
3227+### Error register summary
3228+
3229+| Register | Bit | Field | Trigger |
3230+| :------- | :-- | :---- | :------ |
3231+| CPTRA_HW_ERROR_FATAL | 4 | kv_error | Boot flow error OR KV monitor alert |
3232+| CPTRA_HW_ERROR_FATAL | 5 | shadow_storage_err | ICCM region shadow register storage fault |
3233+| CPTRA_HW_ERROR_FATAL | 7 | rv_dcls_err | RISC-V dual-core lockstep (DCLS) mismatch; normal reporting enabled by `CPTRA_HW_CONFIG.DCLS_en` in both profiles |
3234+| CPTRA_HW_ERROR_FATAL | 8 | dccm_wr_readback_err | DCCM write-readback mismatch detected (store corrupted); maskable via `internal_hw_error_fatal_mask` |
3235+| CPTRA_HW_ERROR_NON_FATAL | 3 | shadow_update_err | ICCM region shadow register phase mismatch |
3236+
3237+
3238+### DICE slot assignments
3239+
3240+The following table documents the key vault slot assignments used by the DICE key derivation chain (defined in `kv_defines_pkg.sv`):
3241+
3242+| Slot | Constant | Purpose |
3243+| :--- | :------- | :------ |
3244+| 0 | KV_SLOT_SI_IDEV | Silicon IDevID private key |
3245+| 1 | KV_SLOT_SI_LDEV | Silicon LDevID private key |
3246+| 2 | KV_SLOT_KEY_LADDER | Key ladder intermediate |
3247+| 4 | KV_SLOT_RT_CDI | Runtime CDI |
3248+| 5 | KV_SLOT_RT_ECDSA | Runtime ECDSA private key |
3249+| 6 | KV_SLOT_FMC_CDI | FMC CDI (accumulates through DICE chain) |
3250+| 7 | KV_SLOT_FMC_ECDSA | FMC ECDSA private key |
3251+| 8 | KV_SLOT_FMC_MLDSA | FMC MLDSA private key |
3252+| 9 | KV_SLOT_RT_MLDSA | Runtime MLDSA private key |
3253+
3254+
3255+### Conditionally-preserved slot assignments
3256+
3257+The following slots are populated by optional features and conditionally preserved by enforcement (but not monitored):
3258+
3259+| Slot | Constant | Feature | Preserved when |
3260+| :--- | :------- | :------ | :------------- |
3261+| 15 | KV_SLOT_STABLE_OWNER | Stable Owner Root Key | `stable_owner_key_en` (subsystem mode, strap[3][0]=1, OCP Lock off) |
3262+| 16 | OCP_LOCK_RT_OBF_KEY_KV_SLOT | MDK (runtime obfuscation key) | `ocp_lock_mode_en` |
3263+| 22 | OCP_LOCK_HEK_SEED_KV_SLOT | HEK seed | `ocp_lock_mode_en` |
3264+| 23 | OCP_LOCK_MEK_KV_SLOT | MEK (key release) | **Never** (always cleared — DMA-accessible, security risk) |
3265+
3266+
3267+### ROM programming sequence
3268+
3269+ROM must perform the following steps before jumping to FMC:
3270+
3271+1. Complete all DICE key derivations (DOE decrypt, HMAC, ECC keygen, MLDSA keygen)
3272+2. Program ICCM region registers with 2-phase writes:
3273+ - Write `INTERNAL_ICCM_FMC_START_ADDR` twice with the same value
3274+ - Write `INTERNAL_ICCM_FMC_END_ADDR` twice with the same value
3275+ - Write `INTERNAL_ICCM_RT_START_ADDR` twice with the same value
3276+ - Write `INTERNAL_ICCM_RT_END_ADDR` twice with the same value
3277+3. Set `INTERNAL_ICCM_REGION_LOCK` (W1S) -- this arms the boot flow monitor
3278+4. Jump to FMC entry point in ICCM
3279+
3280+The first instruction fetch from the FMC region triggers the ROM->FMC transition, at which point the KV monitor validates slot state and enforcement atomically applies locks and clears.
3281+
3282+
23973283 ## Data vault
23983284
23993285 Data vault is a set of generic scratch pad registers with specific lock functionality and clearable on cold and warm resets.
@@ -2403,6 +3289,141 @@
24033289 * 4B scratchpad registers that are lockable but cleared on cold reset (8 registers)
24043290 * 4B scratchpad registers that are lockable but cleared on warm reset (10 registers)
24053291 * 4B scratchpad registers that are cleared on warm reset (8 registers)
3292+
3293+
3294+## OCP LOCK Hardware Architecture
3295+
3296+### Overview
3297+The following hardware and ROM/FW enhancements support the OCP L.O.C.K. (a.k.a. **OCP LOCK**) flows defined for SSD applications. The specification is available here:
3298+[OCP LOCK Spec](https://chipsalliance.github.io/Caliptra/ocp-lock/specification/HEAD)
3299+
3300+---
3301+
3302+### Additional Registers, Straps, and Macros for OCP LOCK
3303+
3304+- **`SS_OCP_LOCK_CTRL.LOCK_IN_PROGRESS`**
3305+ A status/control bit used to enforce the new key Vvult (KV) rules required by OCP LOCK. Write-1-to-set, meaning that, once-enabled, OCP LOCK functionality will persist until the register is cleared by a cold reset. See the dedicated section below for details on the behaviors this register enables.
3306+
3307+- **`ss_ocp_lock_en`** (constant-value input strap) with a corresponding bit in **`CPTRA_HW_CONFIG`** register named **`OCP_LOCK_MODE_en`**:
3308+ - Enables Caliptra ROM to perform OCP LOCK operations (e.g., using DOE for HEK seed de-obfuscation, Key Release via AXI DMA).
3309+ - Allows the ROM to set `SS_OCP_LOCK_CTRL.LOCK_IN_PROGRESS`.
3310+ - `ss_ocp_lock_en` is a strap pin and **must be driven with a constant value by the integrator**.
3311+ - `CPTRA_HW_CONFIG` register samples this strap and store its value in `OCP_LOCK_MODE_en` bit
3312+ - This bit is only reflected in CPTRA_HW_CONFIG if CALIPTRA_MODE_SUBSYSTEM is defined
3313+
3314+- **HEK seed fuse register**
3315+ Holds the **obfuscated HEK seed**. ROM is responsible for performing the operation to de-obfuscate the HEK seed.
3316+
3317+- **Key release address and size straps**
3318+ Writable until `FUSE_WR_DONE`, then locked (same as fuses and other subsystem-mode straps).
3319+ - **Address strap** (`strap_ss_key_release_base_addr`): full destination address for key release; in OCP LOCK this is the destination for the MEK to be written. Firmware can derive the SFR base from this value as needed.
3320+ - **Size strap** (`strap_ss_key_release_key_size`): byte-count (dword-aligned count is required by HW) of the key to program to the destination address via the key release operation. Strap input values are forced to a dword value by hardware. If control firmware updates this value (prior to FUSE_WR_DONE being set), it must use a dword-aligned value.
3321+
3322+Refer to the [Caliptra Integration Spec](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraIntegrationSpecification.md) for more details about macros and strap pins.
3323+
3324+---
3325+
3326+### `SS_OCP_LOCK_CTRL.LOCK_IN_PROGRESS` Register Bit
3327+
3328+**When/How it is set**
3329+- Set by **Caliptra ROM** after performing OCP LOCK-related derivations (HEK, MDK, etc.).
3330+- Can be set **iff** (`ss_ocp_lock_en` is set to 1 **AND** `CALIPTRA_MODE_SUBSYSTEM` is defined).
3331+ - Once set, a value of 1 persists until the register is cleared by cold reset.
3332+
3333+**Enforcements/Effects**
3334+- Reserves **key vault slots 0–15** for *standard* use-cases.
3335+- Reserves **key vault slots 16–23** for *OCP LOCK* use-cases.
3336+ - Key Vault slot 16 (KV16) is reserved for holding the MDK
3337+ - Key Vault slot 23 (KV23) is reserved for holding the MEK
3338+- Blocks interactions between *standard* slots and *LOCK* slots. This means that any crypto operation that uses a Key Vault input value (e.g. for Key, Block, Seed inputs) may not write the output to a Key Vault from a different region. E.g., When `SS_OCP_LOCK_CTRL.LOCK_IN_PROGRESS` is set, HMAC may not perform an operation that uses Key Vault slot 8 as BLOCK input and writes the output TAG to Key Vault slot 17.
3339+- Enables **Key Release via AXI DMA**.
3340+- Enables **AES engine to write output to Key Vault, which must use KV23**.
3341+
3342+> **Note:** If `SS_OCP_LOCK_CTRL.LOCK_IN_PROGRESS` is `1`, it also implies `ss_ocp_lock_en` and `CALIPTRA_MODE_SUBSYSTEM` are also `1`.
3343+
3344+---
3345+
3346+### AES Write Path
3347+
3348+- **MEK** is the final OCP LOCK key. It is **decrypted and stored in KV23**. After decryption, MEK may be transferred to its destination (as specified by the input strap) **via AXI DMA**.
3349+- OCP LOCK requires both the **AES write path** and a **DMA path** to the MEK destination.
3350+- **Hardware enforcement:** MEK is written to **KV23**. Hardware recognizes the MEK generation request if there is an **AES-ECB decrypt** operation with **KV16 (MDK)** as the AES-ECB key and routes the result accordingly. In this case, output of the decrypted plaintext via the AES dataout register API is blocked. Any Key Vault write operation requested for the AES output that does not meet these requirements results in a Key Vault write failure status.
3351+
3352+---
3353+
3354+### Key Vault Access Rules & Filtering (when `LOCK_IN_PROGRESS` is set)
3355+
3356+- **KV23 (MEK destination)**: **write-restricted to AES only**.
3357+- **KV22 (HEK)**: **locked for writes until warm reset** (ROM requirement).
3358+- **KV16 (MDK)**: **locked for writes until warm reset** (ROM requirement).
3359+- If OCP LOCK mode is enabled:
3360+ - **KV23 must not be used** as input to other crypto operations—**only** as a **Key Release** source.
3361+ - **AES-ECB decrypt** with **key = KV16** **must** have **dest = KV23**; otherwise the destination is **FW**.
3362+ *Rationale:* Prevents malicious FW from writing known values into other KV slots via AES.
3363+- **Additional KV behaviors**
3364+ - On write, hardware validates that the **destination** is legal for the **source/read**. If not valid, the Key Vault write operation returns a failing status.
3365+ - **No parallel crypto operations** permitted for cryptographic blocks with access to Key Vault. KV does not track this; Caliptra enforces this rule by evaluating each block's busy status indicator and signaling violations through the [CPTRA_HW_ERROR_FATAL](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.CPTRA_HW_ERROR_FATAL) register and corresponding interrupt at Caliptra top level design.
3366+
3367+---
3368+
3369+### HEK Seed De‑obfuscation
3370+
3371+- Executed by **Caliptra ROM**. The DOE supports a HEK deobfuscation command that may be executed only once during a boot cycle. If Caliptra ROM does not run this flow to produce the HEK seed, it should run the flow with a dummy Key Vault slot to lock against future erroneous uses.
3372+- **Hardware-supported HEK seed Deobfuscation Path:** Ratchet Fuse Register (**obfuscated HEK seed**) → **DOE** (with `OBF_KEY`) → **KV slot 22** (de-obfuscated seed).
3373+- Caliptra ROM shall lock **KV22** for writes immediately it has derived the **HEK** into that slot.
3374+
3375+---
3376+
3377+### Key Release
3378+
3379+Caliptra's AXI DMA supports a hardware path to write **KV23 (MEK)** to the SoC via the AXI manager interface. The following rules constrain this operation:
3380+- Allowed **only** when `SS_OCP_LOCK_CTRL.LOCK_IN_PROGRESS` (sticky **W1SET**) is set by Caliptra ROM.
3381+- Destination and size must match the values from the straps:
3382+ - `strap_ss_key_release_base_addr`
3383+ - `strap_ss_key_release_key_size`
3384+
3385+---
3386+
3387+### Additional Security Hardening Specific to OCP LOCK Enhancements
3388+
3389+**Scan/Debug Protections**
3390+- Flush **DMA FIFOs** to prevent leakage of secrets via scan chain.
3391+- Flush **AES ↔ KV** interface.
3392+
3393+**AES/KV/DMA Robustness**
3394+- **AES → KV write path:** The key can't be written to key vault unless key_size bytes are decrypted by AES.
3395+- Validate **DMA `key_size`**; **error** if `key_size > 512b`.
3396+- Avoid hangs when **`key_size` != KV read DWORD count**:
3397+ - On KV reads, if `key_size` is **smaller** than the KV entry, **drop extra data** (do not push to FIFO).
3398+- **DMA KV read error**: Raised on the **first transfer cycle** from KV to DMA; DMA transitions immediately to **`DMA_ERROR`** without issuing an AXI transfer.
3399+- **KV write enable sourced from AES** (during OCP LOCK) so it **cannot** be modified mid-transfer.
3400+- **Enable AES ↔ KV write path** only if `SS_OCP_LOCK_CTRL.LOCK_IN_PROGRESS` is set.
3401+
3402+
3403+
3404+## Fatal hardware errors
3405+
3406+The `CPTRA_HW_ERROR_FATAL` register aggregates all fatal hardware error conditions. Assertion of any bit drives the SoC `cptra_error_fatal` interrupt pin (unless the bit is masked by `internal_hw_error_fatal_mask`). Once the interrupt is asserted, clearing the register bit does **not** deassert the interrupt — only a Caliptra reset clears a fatal error interrupt. All fields are sticky (RW1C by Caliptra and SoC).
3407+
3408+| Bit | Field | Maskable | Trigger |
3409+| :-- | :---- | :------- | :------ |
3410+| 0 | iccm_ecc_unc | Yes (`mask_iccm_ecc_unc`) | Uncorrectable double-bit ECC error in ICCM |
3411+| 1 | dccm_ecc_unc | Yes (`mask_dccm_ecc_unc`) | Uncorrectable double-bit ECC error in DCCM |
3412+| 2 | nmi_pin | Yes (`mask_nmi_pin`) | NMI asserted by WDT Timer2 timeout |
3413+| 3 | crypto_err | No | Multiple concurrent cryptographic operations using the Key Vault |
3414+| 4 | kv_error | No | KV boot-flow monitor `dest_valid` mismatch or boot-flow error |
3415+| 5 | shadow_storage_err | No | ICCM region shadow-register storage fault (register/shadow corrupted) |
3416+| 6 | fsm_error | No | Sparse-encoded security FSM entered an invalid/illegal state (fault-injection/glitch detection) |
3417+| 7 | rv_dcls_err | No | RISC-V dual-core lockstep (DCLS) mismatch; normal reporting enabled by `CPTRA_HW_CONFIG.DCLS_en` in both profiles |
3418+| 8 | dccm_wr_readback_err | Yes (`mask_dccm_wr_readback_err`) | DCCM write-readback mismatch — data read back after a store did not match what was written |
3419+| 31:9 | rsvd | — | Reserved |
3420+
3421+
3422+**Masking behavior:** Only `iccm_ecc_unc`, `dccm_ecc_unc`, and `nmi_pin` are maskable via the writable fields of `internal_hw_error_fatal_mask`. The remaining fields (`crypto_err`, `kv_error`, `shadow_storage_err`, `fsm_error`) are unmaskable; their corresponding mask bits are read-only zero. Firmware cannot suppress an already-triggered fatal interrupt by setting a mask bit.
3423+
3424+**`fsm_error` — sparse-FSM glitch detection:** Security-critical FSMs (for example, the mailbox FSM) are sparse-encoded with Hamming-distance-separated state values. If a fault-injection/glitch drives an FSM into an unused encoding, the sparse-FSM guard forces the machine to its error state and asserts `fsm_error`. This is an unmaskable, reset-only fatal error.
3425+
3426+The recoverable counterpart, `CPTRA_HW_ERROR_NON_FATAL`, aggregates non-fatal conditions (mailbox protocol violations, mailbox uncorrectable ECC, and the ICCM region shadow-register phase mismatch `shadow_update_err`); firmware may deassert `cptra_error_non_fatal` by clearing or masking all set non-fatal bits.
24063427
24073428 ## Cryptographic blocks fatal and non-fatal errors
24083429
@@ -2485,10 +3506,11 @@
24853506 9. Coron, J.-S.: Resistance against differential power analysis for elliptic curve cryptosystems. In: Ko¸c, C¸ .K., Paar, C. (eds.) CHES 1999. LNCS, vol. 1717, pp. 292–302.
24863507 10. Schindler, W., Wiemers, A.: Efficient side-channel attacks on scalar blinding on elliptic curves with special structure. In: NISTWorkshop on ECC Standards (2015).
24873508 11. National Institute of Standards and Technology, "Digital Signature Standard (DSS)", Federal Information Processing Standards Publication (FIPS PUB) 186-4, July 2013.
2488-12. NIST SP 800-90A, Rev 1: "Recommendation for Random Number Generation Using Deterministic Random Bit Generators", 2012. |
3509+12. NIST SP 800-90A, Rev 1: "Recommendation for Random Number Generation Using Deterministic Random Bit Generators", 2012.
24893510 13. CHIPS Alliance, “RISC-V VeeR EL2 Programmer’s Reference Manual” \[Online\] Available at https://github.com/chipsalliance/Cores-VeeR-EL2/blob/main/docs/RISC-V_VeeR_EL2_PRM.pdf.
24903511 14. “The RISC-V Instruction Set Manual, Volume I: User-Level ISA, Document Version 20191213”, Editors Andrew Waterman and Krste Asanovi ́c, RISC-V Foundation, December 2019. Available at https://riscv.org/technical/specifications/.
24913512 15. “The RISC-V Instruction Set Manual, Volume II: Privileged Architecture, Document Version 20211203”, Editors Andrew Waterman, Krste Asanovi ́c, and John Hauser, RISC-V International, December 2021. Available at https://riscv.org/technical/specifications/.
2492-16. NIST SP 800-56A, Rev 3: "Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography", 2018, |
3513+16. NIST SP 800-56A, Rev 3: "Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography", 2018.
3514+17. NIST FIPS 202: "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions", 2015. Available at: [https://csrc.nist.gov/pubs/fips/202/final](https://doi.org/10.6028/NIST.FIPS.202).
24933515
24943516 <sup>[1]</sup> _Caliptra.** **Spanish for “root cap” and describes the deepest part of the root_

Image Changes

v2.0: Caliptra_boot_fsm.png

Image not present in this version

v2.1: Caliptra_boot_fsm.png

New version

v2.0: Crypto-2p0.png

Old version

v2.1: Crypto-2p0.png

Image not present in this version

v2.0: HW_mbox_boot_fsm.png

Old version

v2.1: HW_mbox_boot_fsm.png

Image not present in this version

v2.0: dual_entropy.png

Image not present in this version

v2.1: dual_entropy.png

New version

v2.0: entropy_source_block.png

Old version

v2.1: entropy_source_block.png

New version

v2.0: kv_monitor.png

Image not present in this version

v2.1: kv_monitor.png

New version

v2.0: mbox_boot_fsm_FW_update_reset.png

Old version

v2.1: mbox_boot_fsm_FW_update_reset.png

Image not present in this version