v2.0: Caliptra_mbox_boot_FSM.png
v2.1: Caliptra_mbox_boot_FSM.png
Image not present in this version
| @@ -1,12 +1,12 @@ | |||
| 1 | 1 | <div style="font-size: 0.85em; color: #656d76; margin-bottom: 1em; padding: 0.5em; background: #f6f8fa; border-radius: 4px;"> | |
| 2 | -📄 Source: <a href="https://github.com/chipsalliance/caliptra-rtl/blob/35b0bc5691b2bd0fc180403914cfabe207379089/docs/CaliptraIntegrationSpecification.md" target="_blank">chipsalliance/caliptra-rtl/docs/CaliptraIntegrationSpecification.md</a> @ <code>35b0bc5</code> | ||
| 2 | +📄 Source: <a href="https://github.com/chipsalliance/caliptra-rtl/blob/a7d7421ef510e809ad2b9c071402c0cc9c19328d/docs/CaliptraIntegrationSpecification.md" target="_blank">chipsalliance/caliptra-rtl/docs/CaliptraIntegrationSpecification.md</a> @ <code>a7d7421</code> | ||
| 3 | 3 | </div> | |
| 4 | 4 | ||
| 5 | 5 |  | |
| 6 | 6 | ||
| 7 | 7 | <p style="text-align: center;">Caliptra Integration Specification</p> | |
| 8 | 8 | ||
| 9 | -<p style="text-align: center;">Version 2.0.3</p> | ||
| 9 | +<p style="text-align: center;">Version 2.1</p> | ||
| 10 | 10 | ||
| 11 | 11 | <div style="page-break-after: always"></div> | |
| 12 | 12 | ||
| @@ -31,7 +31,7 @@ | |||
| 31 | 31 | | IP/Block | GitHub URL | Documentation | Link | | |
| 32 | 32 | | :--------- | :--------- | :--------- | :--------- | | |
| 33 | 33 | | Cores-VeeR | [GitHub - chipsalliance/Cores-VeeR-EL2](https://github.com/chipsalliance/Cores-VeeR-EL2) | VeeR EL2 Programmer’s Reference Manual | [chipsalliance/Cores-VeeR-EL2 · GitHubPDF](http://cores-swerv-el2/RISC-V_SweRV_EL2_PRM.pdf%20at%20master%20%C2%B7) | | |
| 34 | -| AHB Lite Bus | [aignacio/ahb_lite_bus: AHB Bus lite v3.0 (github.com)](https://github.com/aignacio/ahb_lite_bus) | AHB Lite Protocol<br> [Figure 1: SoC interface block diagram](#soc-interface-definition) | [ahb_lite_bus/docs at master · aignacio/ahb_lite_bus (github.com)](https://github.com/aignacio/ahb_lite_bus/tree/master/docs)<br> [ahb_lite_bus/diagram_ahb_bus.png at master · aignacio/ahb_lite_bus (github.com)](https://github.com/aignacio/ahb_lite_bus/blob/master/diagram_ahb_bus.png) | | ||
| 34 | +| AHB Lite Bus | [aignacio/ahb_lite_bus: AHB Bus lite v3.0 (github.com)](https://github.com/aignacio/ahb_lite_bus) | AHB Lite Protocol<br> [Figure: SoC interface block diagram](#soc-interface-definition) | [ahb_lite_bus/docs at master · aignacio/ahb_lite_bus (github.com)](https://github.com/aignacio/ahb_lite_bus/tree/master/docs)<br> [ahb_lite_bus/diagram_ahb_bus.png at master · aignacio/ahb_lite_bus (github.com)](https://github.com/aignacio/ahb_lite_bus/blob/master/diagram_ahb_bus.png) | | ||
| 35 | 35 | | SHA 256 | [secworks/sha256: Hardware implementation of the SHA-256 cryptographic hash function (github.com)](https://github.com/secworks/sha256) ||| | |
| 36 | 36 | | SHA 512 |||| | |
| 37 | 37 | | SPI Controller | <https://github.com/pulp-platform/axi_spi_master> ||| | |
| @@ -45,7 +45,7 @@ | |||
| 45 | 45 | ||
| 46 | 46 | The following figure shows the SoC interface definition. | |
| 47 | 47 | ||
| 48 | -*Figure 1: SoC Interface Block Diagram* | ||
| 48 | +*Figure: SoC Interface Block Diagram* | ||
| 49 | 49 | ||
| 50 | 50 |  | |
| 51 | 51 | ||
| @@ -68,7 +68,8 @@ | |||
| 68 | 68 | ||
| 69 | 69 | | **Defines** | **Defines file** | **Description** | | |
| 70 | 70 | | :--------- | :--------- | :--------- | | |
| 71 | -| CALIPTRA_INTERNAL_TRNG | config_defines.svh | Defining this enables the internal TRNG source. This must be set to 1 in Subsystem mode. | | ||
| 71 | +| CALIPTRA_FUSE_GRANULARITY_32 | config_defines.svh | Defining this means fuse row granularity is 32-bits. If not defined it means fuse row granularity is 64 bits. If defined, the ``CPTRA_HW_CONFIG.CALIPTRA_FUSE_GRANULARITY_32`` SOC_IFC register bit is set to 1 for 32-bit granularity. Otherwise, it is set to 0 for 64-bit granularity. This is used by Caliptra ROM for UDS and Field Entropy provisioning. | | ||
| 72 | +| CALIPTRA_INTERNAL_TRNG | config_defines.svh | Defining this enables the internal TRNG source. This is recommended to be set to 1 in Core (Passive) mode and must be set to 1 in Subsystem mode. | | ||
| 72 | 73 | | CALIPTRA_MODE_SUBSYSTEM | config_defines.svh | Defining this enables Caliptra to operate in Subsystem mode. This includes features such as the debug unlock flow, AXI DMA (for recovery flow), Subsystem-level straps, among other capabilites. See [Caliptra Subsystem Architectural Flows](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#caliptra-subsystem-architectural-flows) for more details | | |
| 73 | 74 | | USER_ICG | config_defines.svh | If added by an integrator, provides the name of the custom clock gating module that is used in [clk_gate.sv](../src/libs/rtl/clk_gate.sv). USER_ICG replaces the clock gating module, CALIPTRA_ICG, defined in [caliptra_icg.sv](../src/libs/rtl/caliptra_icg.sv). This substitution is only performed if integrators also define TECH_SPECIFIC_ICG. | | |
| 74 | 75 | | TECH_SPECIFIC_ICG | config_defines.svh | Defining this causes the custom, integrator-defined clock gate module (indicated by the USER_ICG macro) to be used in place of the native Caliptra clock gate module. | | |
| @@ -183,7 +184,7 @@ | |||
| 183 | 184 | Strobe width describes the number of bits enabled by each strobe. All strobed memories are byte enabled in the design. | |
| 184 | 185 | See [ABR Memory requirement](https://github.com/chipsalliance/adams-bridge/blob/main/docs/AdamsBridgeHardwareSpecification.md#memory-requirement) for more details. | |
| 185 | 186 | ||
| 186 | -The full set of wires is encapsulated in the mldsa_mem_if construct mldsa_memory_export at the Caliptra boundary. | ||
| 187 | +The full set of wires is encapsulated in the abr_mem_if construct abr_memory_export at the Caliptra boundary. | ||
| 187 | 188 | ||
| 188 | 189 | The table below details the interface required for each SRAM. Driver direction is from the perspective of Caliptra. | |
| 189 | 190 | ||
| @@ -210,6 +211,7 @@ | |||
| 210 | 211 | ||
| 211 | 212 | ||
| 212 | 213 | *Table 10: RISC-V Trace interface* | |
| 214 | +Trace ports have been directly connected from Caliptra's instance of the VeeR-EL2 RISC-V core to the top-level. However, use of these ports has not been validated. Integrators shall leave these ports unconnected. Support for these ports may be added in a future release. | ||
| 213 | 215 | | Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description | | |
| 214 | 216 | | :--------- | :--------- | :--------- | :--------- | :--------- | | |
| 215 | 217 | | trace_rv_i_insn_ip | 32 | Output | Synchronous to clk | Trace signals from Caliptra RV core instance. Refer to VeeR documentation for more details. | | |
| @@ -228,8 +230,11 @@ | |||
| 228 | 230 | | strap_ss_caliptra_base_addr | 64 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 229 | 231 | | strap_ss_mci_base_addr | 64 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 230 | 232 | | strap_ss_recovery_ifc_base_addr | 64 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 233 | +| strap_ss_external_staging_area_base_addr | 64 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | ||
| 231 | 234 | | strap_ss_otp_fc_base_addr | 64 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 232 | 235 | | strap_ss_uds_seed_base_addr | 64 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 236 | +| strap_ss_key_release_base_addr | 64 | Input Strap | Synchronous to clk | Used in Subsystem mode only. This is the full destination address for MEK generated via OCP LOCK flow. In Passive mode, integrators shall tie this input to 0. | | ||
| 237 | +| strap_ss_key_release_key_size | 64 | Input Strap | Synchronous to clk | Used in Subsystem mode only. This is the size of MEK generated via OCP LOCK flow. In Passive mode, integrators shall tie this input to 0. | | ||
| 233 | 238 | | strap_ss_prod_debug_unlock_auth_pk_hash_reg_bank_offset | 32 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 234 | 239 | | strap_ss_num_of_prod_debug_unlock_auth_pk_hashes | 32 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 235 | 240 | | strap_ss_caliptra_dma_axi_user | 32 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| @@ -237,7 +242,8 @@ | |||
| 237 | 242 | | strap_ss_strap_generic_1 | 32 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 238 | 243 | | strap_ss_strap_generic_2 | 32 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 239 | 244 | | strap_ss_strap_generic_3 | 32 | Input Strap | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. | | |
| 240 | -| ss_debug_intent | 1 | Input | Synchronous to clk | Sample on cold reset. Used in Subsystem mode only. Indicates that the SoC is in debug mode and a user intends to request unlock of debug mode through the TAP mailbox. In Passive mode, integrators shall tie this input to 0. | | ||
| 245 | +| ss_debug_intent | 1 | Input | Synchronous to clk | Sampled on cold reset. Used in Subsystem mode only. Indicates that the SoC is in debug mode and a user intends to request unlock of debug mode through the TAP mailbox. In Passive mode, integrators shall tie this input to 0. | | ||
| 246 | +| ss_ocp_lock_en | 1 | Input | Synchronous to clk | Sampled on cold reset. Used in Subsystem mode only. Indicates that the SoC enables OCP LOCK features of Caliptra. Must be tied to a constant value. For example, driving this input from a programmable register or from a package pin is not permitted. | | ||
| 241 | 247 | | ss_dbg_manuf_enable | 1 | Output | Synchronous to clk | Enables unlock of the debug interface in the Manufacturing security state, for Subsystem mode only. | | |
| 242 | 248 | | ss_soc_dbg_unlock_level | 64 | Output | Synchronous to clk | Enables unlock of the debug interface in the Production security state, for Subsystem mode only. | | |
| 243 | 249 | | ss_generic_fw_exec_ctrl | 128 | Output | Synchronous to clk | Enables SoC processors to execute firmware once authenticated by Caliptra. | | |
| @@ -250,7 +256,7 @@ | |||
| 250 | 256 | | Signal name | Width | Driver | Synchronous (as viewed from Caliptra’s boundary) | Description | | |
| 251 | 257 | | :--------- | :--------- | :--------- | :--------- | :--------- | | |
| 252 | 258 | | cptra_obf_key | 256 | Input Strap | Asynchronous | Obfuscation key is driven by SoC at integration time. Ideally this occurs just before tape-in and the knowledge of this key must be protected unless PUF is driving this. The key is latched by Caliptra upon first deassertion of the warm reset following caliptra powergood assertion. It is not resampled during subsequent warm resets, therefore the value is only captured upon a cold boot. It is cleared after its use and can only re-latched on a power cycle (powergood deassertion to assertion). | | |
| 253 | -| cptra_csr_hmac_key | 512 | Input Strap | Asynchronous | CSR HMAC key is driven by SoC at integration time. Ideally this occurs just before tape-in and the knowledge of this key must be protected. The key is latched by Caliptra on caliptra powergood assertion during DEVICE_MANUFACTURING lifecycle state. | | ||
| 259 | +| cptra_csr_hmac_key | 512 | Input Strap | Asynchronous | CSR HMAC key is driven by SoC at integration time. Ideally this occurs just before tape-in and the knowledge of this key must be protected. The key is latched by Caliptra following deassertion of the noncore warm reset during DEVICE_MANUFACTURING lifecycle state. This key input is ignored in all other lifecycle states. | | ||
| 254 | 260 | | cptra_obf_field_entropy_vld | 1 | Input | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. Valid signal used to sample cptra_obf_field_entropy if it is driven by wires from the fuse controller. | | |
| 255 | 261 | | cptra_obf_field_entropy | 256 | Input | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. Fuse controller can optionally drive the field entropy value over wires through this interface. The value is sampled after warm reset if the valid cptra_obf_field_entropy_vld is asserted. | | |
| 256 | 262 | | cptra_obf_uds_seed_vld | 1 | Input | Synchronous to clk | Used in Subsystem mode only. In Passive mode, integrators shall tie this input to 0. Valid signal used to sample cptra_obf_uds_seed if it is driven by wires from the fuse controller. | | |
| @@ -284,17 +290,31 @@ | |||
| 284 | 290 | ||
| 285 | 291 | **Note**: Starting in Caliptra 2.0 subsystem strap and other configuration registers have been added to the fuse region. Subsystem [straps](#straps) are expected to be programmed during the same time as fuses per [Caliptra spec](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#subsystem-pre-fw-load-boot-flow). The following SS registers in the fuse region are not straps, are intended for internal use in Caliptra, and cannot be written by any SoC agents; therefore, categorizing them under the FUSE range has no effect: | |
| 286 | 292 | ||
| 287 | -- `SS_DBG_MANUF_SERVICE_REG_RSP` | ||
| 293 | +- `SS_DBG_SERVICE_REG_RSP` | ||
| 288 | 294 | - `SS_SOC_DBG_UNLOCK_LEVEL` | |
| 289 | 295 | - `SS_GENERIC_FW_EXEC_CTRL` | |
| 290 | 296 | ||
| 291 | -The remaining register `SS_DBG_MANUF_SERVICE_REG_REQ` is initialized by the same SoC agent as fuses and is the only agent that can make subsystem debug service requests. | ||
| 297 | +The remaining register `SS_DBG_SERVICE_REG_REQ` is initialized by the same SoC agent as fuses and is the only agent that can make subsystem debug service requests. | ||
| 298 | + | ||
| 299 | +### FUSE AXI USER attribute | ||
| 300 | + | ||
| 301 | +The CPTRA_FUSE_VALID_AXI_USER attribute is used to restrict access to the fuse registers via AXI to a single permitted SoC configuration agent. It is strongly recommended that the CPTRA_FUSE_VALID_AXI_USER value is either set at integration time through integration parameters or be programmed by the SoC ROM via register write before any mutable firmware or ROM patches are applied. | ||
| 302 | + | ||
| 303 | +SoC SHALL not use value 0xFFFFFFFF as a valid AXI user value for any of the below settings. This is reserved for Caliptra-internal usage. | ||
| 304 | + | ||
| 305 | +#### FUSE AXI USER Programmable register | ||
| 306 | + | ||
| 307 | +Caliptra provides 1 programmable register that SoC can set at boot time to limit access to the fuse register set. If the CPTRA_FUSE_AXI_USER_LOCK.LOCK is set to ‘0, then access to the fuse registers by any agent is allowed. If the lock is set to ‘1, only an agent whose AXI USER matches the register CPTRA_FUSE_VALID_AXI_USER.AXI_USER can write to fuse registers. Any access by an unallowed AXI USER will return an AXI error response. CPTRA_FUSE_VALID_AXI_USER registers become valid once the corresponding lock bit CPTRA_FUSE_AXI_USER_LOCK.LOCK is set. | ||
| 308 | + | ||
| 309 | +#### FUSE AXI USER Parameter override | ||
| 310 | + | ||
| 311 | +Another option for limiting access to the fuse registers is the integration time parameter, which overrides the programmable AXI_USER register. At integration time, the CPTRA_SET_FUSE_AXI_USER_INTEG parameter can be set to 1 which enables the corresponding CPTRA_FUSE_VALID_AXI_USER parameter to override the programmable register. If CPTRA_SET_FUSE_AXI_USER_INTEG is set to ‘0, then access to the fuse registers by any agent is allowed. If this parameter is set to ‘1, only an agent whose AXI USER matches the parameter CPTRA_FUSE_VALID_AXI_USER can write to fuse registers. Any access by an unallowed AXI USER will return an AXI error response. | ||
| 292 | 312 | ||
| 293 | 313 | ## Interface rules | |
| 294 | 314 | ||
| 295 | 315 | The following figure shows the reset rules and timing for cold boot flows. | |
| 296 | 316 | ||
| 297 | -*Figure 2: Reset rules and timing diagram* | ||
| 317 | +*Figure: Reset rules and timing diagram* | ||
| 298 | 318 | ||
| 299 | 319 |  | |
| 300 | 320 | ||
| @@ -371,7 +391,7 @@ | |||
| 371 | 391 | ||
| 372 | 392 | SoC drives the key at the tape-in time of the SoC using an Engineering Change Order (ECO) and must be protected from common knowledge. For a given SoC construction, this can be driven using a PUF too. | |
| 373 | 393 | ||
| 374 | -The key must follow the security rules defined in the[ Caliptra architectural specification](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html). | ||
| 394 | +The key must follow the security rules defined in the [SOC integration requirements](#soc-integration-requirements). | ||
| 375 | 395 | ||
| 376 | 396 | SoC must ensure that there are no SCAN cells on the flops that latch this key internally to Caliptra. | |
| 377 | 397 | ||
| @@ -379,7 +399,7 @@ | |||
| 379 | 399 | ||
| 380 | 400 | SoC drives the key at the tape-in time of the SoC using an Engineering Change Order (ECO) and must be protected from common knowledge. | |
| 381 | 401 | ||
| 382 | -The key must follow the security rules defined in the[ Caliptra architectural specification](https://chipsalliance.github.io/Caliptra/doc/Caliptra.html). | ||
| 402 | +The key must follow the security rules defined in the [SOC integration requirements](#soc-integration-requirements). | ||
| 383 | 403 | ||
| 384 | 404 | SoC must ensure that there are no SCAN cells on the flops that latch this key internally to Caliptra. | |
| 385 | 405 | ||
| @@ -425,11 +445,7 @@ | |||
| 425 | 445 | ||
| 426 | 446 | ## Boot FSM | |
| 427 | 447 | ||
| 428 | -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 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 deasserting the internal reset. The following figure shows the boot FSM state. | ||
| 429 | - | ||
| 430 | -*Figure 3: Mailbox Boot FSM state diagram* | ||
| 431 | - | ||
| 432 | - | ||
| 448 | +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 ready for fuses. After fuses are populated and the SoC indicates that it is done downloading fuses, the boot FSM wakes up the rest of Caliptra by deasserting the internal reset. Refer to [CaliptraHardwareSpecification.md](./CaliptraHardwareSpecification.md#boot-fsm) for more details and diagrams. | ||
| 433 | 449 | ||
| 434 | 450 | The boot FSM first waits for the SoC to assert cptra\_pwrgood and deassert cptra\_rst\_b. The SoC first provides a stable clock to Caliptra. After a minimum of 10 clock cycles have elapsed on the stable clock, the SoC asserts cptra\_pwrgood. The SoC waits for a minimum of 10 clocks after asserting cptra\_pwrgood before deasserting cptra\_rst\_b. | |
| 435 | 451 | 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. | |
| @@ -442,9 +458,31 @@ | |||
| 442 | 458 | ||
| 443 | 459 | The AXI_USER bits are used by the SoC to identify which device is accessing the mailbox. | |
| 444 | 460 | ||
| 461 | +## External Staging Area | ||
| 462 | + | ||
| 463 | +To save SRAM area when Caliptra operates in Subsystem mode, the mailbox (MBOX) SRAM is reduced to **16 KiB**. | ||
| 464 | +Instead of passing images directly to Caliptra through the mailbox, the SoC can configure an external staging SRAM that Caliptra fetches from and processes. | ||
| 465 | + | ||
| 466 | +Caliptra Core receives the base address of this staging area through the **SOC_IFC** register `SS_EXTERNAL_STAGING_AREA_BASE_ADDR`. The address must be an AXI address accessable via the Caliptra DMA controller. This register is exposed as a strap ``strap_ss_external_staging_area_base_addr`` and is overridable by SW until ``FUSE_DONE`` is set. | ||
| 467 | + | ||
| 468 | +For hitless updates or other image-processing operations, the Caliptra mailbox should be used to: | ||
| 469 | + | ||
| 470 | +1. Notify Caliptra that an image is available for processing. | ||
| 471 | +2. Specify the command to run on the image. | ||
| 472 | +3. Indicate the size of the image in the staging area. | ||
| 473 | + | ||
| 474 | +References: | ||
| 475 | + | ||
| 476 | +- [Caliptra ROM MBOX Commands](https://github.com/chipsalliance/caliptra-sw/blob/main/rom/dev/README.md#handling-commands-from-mailbox) | ||
| 477 | +- [Caliptra Runtime FW MBOX Commands](https://github.com/chipsalliance/caliptra-sw/blob/main/runtime/README.md#mailbox-commands) | ||
| 478 | +- [Caliptra HW API](#mailbox) | ||
| 479 | + | ||
| 480 | + | ||
| 481 | +The external staging area must be within the Caliptra crypto boundary. Meaning there must be access restrictions similar to the MBOX preventing trusted entities from manipulating or accessing the data being processed by Caliptra. | ||
| 482 | + | ||
| 445 | 483 | ## Mailbox | |
| 446 | 484 | ||
| 447 | -The Caliptra mailbox is a 256 KiB buffer used for exchanging data between the SoC and the Caliptra microcontroller. | ||
| 485 | +The Caliptra mailbox is a 256 KiB when in passive mode and 16 KiB when in subsystem mode buffer used for exchanging data between the SoC and the Caliptra microcontroller. See [External Staging Area](#external-staging-area) why the MBOX SRAM size is smaller in subsystem mode. | ||
| 448 | 486 | ||
| 449 | 487 | When a mailbox is populated by the SoC, initiation of the operation by writing the execute bit triggers an interrupt to the microcontroller. This interrupt indicates that a command is available in the mailbox. The microcontroller is responsible for reading from and responding to the command. | |
| 450 | 488 | ||
| @@ -473,9 +511,17 @@ | |||
| 473 | 511 | ||
| 474 | 512 | **Notes on behavior:** | |
| 475 | 513 | ||
| 476 | -Once LOCK is granted, the mailbox is locked until that device has concluded its operation. Caliptra has access to an internal mechanism to terminate a lock early or release the lock if the device does not proceed to use it or to recover from deadlock scenarios. The following figure shows the sender protocol flow. | ||
| 477 | - | ||
| 478 | -*Figure 4: Sender protocol flow chart* | ||
| 514 | +Once LOCK is granted, the mailbox is locked until that device has concluded its operation. Caliptra has access to an internal mechanism to terminate a lock early or release the lock if the device does not proceed to use it or to recover from deadlock scenarios. If used, the force unlock mechanism has several effects: | ||
| 515 | +* Returns the mailbox FSM (indicated in the mbox_status register) to the IDLE state. | ||
| 516 | +* Resets the status field of the mbox_status register to CMD_BUSY. | ||
| 517 | +* Resets the soc_has_lock field of the mbox_status register to 0. | ||
| 518 | +* If the mailbox was in the ERROR state, internal hardware would continuously assert the error interrupt signals as described in [Caliptra mailbox errors](#Caliptra-mailbox-errors). The force unlock mechanism causes hardware to stop asserting these conditions, though any interrupts that are already asserted remain asserted and require firmware intervention to be cleared. | ||
| 519 | + | ||
| 520 | +To address these conditions, integrators may wish to add timeout handling logic to their implementation of the mailbox protocol. This timeout handling logic may determine that a pending mailbox request has been terminated by observing the deassertion of mbox_status.soc_has_lock, or by observing that mbox_status.mbox_fsm_ps indicates the IDLE state. Upon observing these conditions, SoC logic may check for any error conditions reported in [CPTRA_HW_ERROR_FATAL](https://chipsalliance.github.io/caliptra-rtl/main/external-regs/?p=clp.soc_ifc_reg.CPTRA_HW_ERROR_FATAL) or [CPTRA_HW_ERROR_NON_FATAL](https://chipsalliance.github.io/caliptra-rtl/main/external-regs/?p=clp.soc_ifc_reg.CPTRA_HW_ERROR_NON_FATAL), and may attempt a retry of the command depending on any SoC retry policies. | ||
| 521 | + | ||
| 522 | +The following figure shows the sender protocol flow. | ||
| 523 | + | ||
| 524 | +*Figure: Sender protocol flow chart* | ||
| 479 | 525 | ||
| 480 | 526 |  | |
| 481 | 527 | ||
| @@ -499,7 +545,7 @@ | |||
| 499 | 545 | ||
| 500 | 546 | The following figure shows the receiver protocol flow. | |
| 501 | 547 | ||
| 502 | -*Figure 5: Receiver protocol flowchart* | ||
| 548 | +*Figure: Receiver protocol flowchart* | ||
| 503 | 549 | ||
| 504 | 550 |  | |
| 505 | 551 | ||
| @@ -535,8 +581,8 @@ | |||
| 535 | 581 | ||
| 536 | 582 | | Register | Description | | |
| 537 | 583 | | :--------- | :--------- | | |
| 538 | -| CPTRA_MBOX_VALID_AXI_USER\[4:0\]\[31:0\] | 5 registers for programming AXI_USER values that are considered valid for accessing the mailbox protocol. Requests with AXI_USER attributes that are not in this list will be ignored. | | ||
| 539 | -| CPTRA_MBOX_AXI_USER_LOCK\[4:0\] | 5 registers, bit 0 of each will lock and mark VALID for the corresponding VALID_AXI_USER register. | | ||
| 584 | +| CPTRA_MBOX_VALID_AXI_USER\[4:0\]\[31:0\] | 5 registers for programming AXI_USER values that are considered valid for accessing the mailbox protocol. Requests with AXI_USER attributes that are not in this list will return an AXI error response. | | ||
| 585 | +| CPTRA_MBOX_AXI_USER_LOCK\[4:0\] | 5 registers, bit 0 of each locks the corresponding VALID_AXI_USER register and marks it VALID. | | ||
| 540 | 586 | ||
| 541 | 587 | ||
| 542 | 588 | ### Parameter override | |
| @@ -639,11 +685,11 @@ | |||
| 639 | 685 | ||
| 640 | 686 | # TRNG REQ HW API | |
| 641 | 687 | ||
| 642 | -For SoCs that choose to not instantiate Caliptra’s internal TRNG, we provide a TRNQ REQ HW API. | ||
| 688 | +For SoCs integrating Caliptra core without Subsystem (i.e., passive mode) that choose not to instantiate Caliptra’s internal TRNG, Caliptra provides a TRNQ REQ HW API. | ||
| 643 | 689 | ||
| 644 | 690 | **While the use of this API is convenient for early enablement, the current | |
| 645 | 691 | Caliptra hardware is unable to provide the same security guarantees with an | |
| 646 | -external TRNG. In particular, it is highly advisable to instantiate an internal | ||
| 692 | +external TRNG. The internal TRNG is recommended at a minimum, and required in Subsystem mode. In particular, it is highly advisable to instantiate an internal | ||
| 647 | 693 | TRNG if ROM glitch protection is important.** | |
| 648 | 694 | ||
| 649 | 695 | 1. Caliptra asserts TRNG\_REQ wire (this may be because Caliptra’s internal hardware or firmware made the request for a TRNG). | |
| @@ -651,9 +697,9 @@ | |||
| 651 | 697 | 3. SoC write a done bit in the TRNG architectural registers. | |
| 652 | 698 | 4. Caliptra deasserts TRNG\_REQ. | |
| 653 | 699 | ||
| 654 | -Having an interface that is separate from the SoC mailbox ensures that this request is not intercepted by any SoC firmware agents (which communicate with SoC mailbox). It is a requirement for FIPS compliance that this TRNG HW API is always handled by SoC hardware gasket logic (and not some SoC ROM or firmware code). | ||
| 655 | - | ||
| 656 | -TRNG DATA register is tied to TRNG VALID AXI USER. SoC can program the TRNG VALID AXI USER and lock the register using TRNG\_AXI\_USER\_LOCK[LOCK]. This ensures that TRNG DATA register is read-writeable by only the AXI USER programmed into the TRNG\_VALID\_AXI\_USER register. If the CPTRA\_TNRG\_AXI\_USER\_LOCK.LOCK is set to ‘0, then any agent can write to the TRNG DATA register. If the lock is set, only an agent with a specific TRNG\_VALID\_AXI\_USER can write. | ||
| 700 | +Having an interface that is separate from the SoC mailbox ensures that this request is not intercepted by any SoC firmware agents (which communicate with SoC mailbox). It is a requirement for FIPS compliance that this TRNG HW API is always handled by SoC hardware gasket logic (and not some SoC ROM or firmware code). SoC implementations of this gasket logic must guarantee that only one AXI agent has access to the Caliptra TRNG REQ HW API. | ||
| 701 | + | ||
| 702 | +Access to TRNG DATA register is controlled by TRNG VALID AXI USER. SoC can program the TRNG VALID AXI USER and lock the register using TRNG\_AXI\_USER\_LOCK[LOCK]. This ensures that TRNG DATA register is read-writeable by only the AXI USER programmed into the TRNG\_VALID\_AXI\_USER register. If the CPTRA\_TNRG\_AXI\_USER\_LOCK.LOCK is set to ‘0, then any agent can write to the TRNG DATA register. If the lock is set to ‘1, only an agent whose AXI USER matches TRNG\_VALID\_AXI\_USER can write to TRNG DATA. It is strongly recommended that these AXI USER registers are either set at integration time through integration parameters or be programmed by the SoC ROM before any mutable FW or ROM patches are absorbed. If integrators do not use these registers to filter agent access to the TRNG REQ HW API, then the SoC implementation must allow no more than one AXI agent in total to access Caliptra's SoC interface. | ||
| 657 | 703 | ||
| 658 | 704 | The ROM and firmware currently time out on the TRNG interface after 250,000 | |
| 659 | 705 | attempts to read a DONE bit. This bit is set in the architectural registers, as | |
| @@ -809,7 +855,7 @@ | |||
| 809 | 855 | ||
| 810 | 856 | The following figure shows the SRAM interface timing. | |
| 811 | 857 | ||
| 812 | -*Figure 6: SRAM interface timing* | ||
| 858 | +*Figure: SRAM interface timing* | ||
| 813 | 859 | ||
| 814 | 860 |  | |
| 815 | 861 | ||
| @@ -837,9 +883,9 @@ | |||
| 837 | 883 | ||
| 838 | 884 | This example is applicable to scenarios where an integrator may need control of or visibility into SRAM errors for purposes of reliability or functional safety. In such cases, integrators may introduce additional layers of error injection, detection, and correction logic surrounding SRAMs. The addition of such logic is transparent to the correct function of Caliptra, and removes integrator dependency on Caliptra for error logging or injection. | |
| 839 | 885 | ||
| 840 | -Note that the example assumes that data and ECC codes are in non-deterministic bit-position in the exposed SRAM interface bus. Accordingly, redundant correction coding is shown in the integrator level logic (i.e., integrator\_ecc(calitpra\_data, caliptra\_ecc)). If the Caliptra data and ECC are deterministically separable at the Caliptra interface, the integrator would have discretion to store the ECC codes directly and calculate integrator ECC codes for the data alone. | ||
| 841 | - | ||
| 842 | -*Figure 7: Example machine check reliability implementation* | ||
| 886 | +Note that the example assumes that data and ECC codes are in non-deterministic bit-position in the exposed SRAM interface bus. Accordingly, redundant correction coding is shown in the integrator level logic (i.e., integrator\_ecc(caliptra\_data, caliptra\_ecc)). If the Caliptra data and ECC are deterministically separable at the Caliptra interface, the integrator would have discretion to store the ECC codes directly and calculate integrator ECC codes for the data alone. | ||
| 887 | + | ||
| 888 | +*Figure: Example machine check reliability implementation* | ||
| 843 | 889 | ||
| 844 | 890 |  | |
| 845 | 891 | ||
| @@ -885,28 +931,28 @@ | |||
| 885 | 931 | ||
| 886 | 932 | | Category | Requirement | Definition of done | Rationale | | |
| 887 | 933 | | :--------- | :--------- | :--------- | :--------- | | |
| 888 | -| Obfuscation Key | SoC backend flows shall generate obfuscation key with appropriate NIST compliance as dictated in the Caliptra RoT specification. | Statement of conformance | Required by UDS and Field Entropy threat model | | ||
| 934 | +| Device Keys | SoC backend flows shall generate obfuscation and CSR HMAC key with appropriate NIST compliance as dictated in the Caliptra RoT specification. | Statement of conformance | Required by UDS and Field Entropy threat model | | ||
| 935 | +| Device Keys | SoC backend flows shall ECO the obfuscation and CSR HMAC signing keys before tapeout. | Statement of conformance | Required by Caliptra threat model | | ||
| 936 | +| Device Keys* | SoC backend flows should rotate obfuscation and CSR HMAC signing keys for each project. | Statement of conformance | Required by Caliptra threat model | | ||
| 937 | +| Device Keys | The obfuscation and CSR HMAC keys shall not be accessible (readable or modifiable) to firmware or any on-chip non-Caliptra entities, including preventing oracle attacks. The keys shall not be on any scannable path. | Statement of conformance | Required for Caliptra threat model | | ||
| 938 | +| Device Keys* | SoC backend flows should not insert obfuscation and CSR HMAC key flops into the scan chain. | Synthesis report | Required by UDS and Field Entropy threat model | | ||
| 939 | +| Device Keys* | For defense in depth, it is strongly recommended that obfuscation and CSR HMAC key flops are not on the scan chain. <br> Remove the following signals from the scan chain: <br> cptra\_scan\_mode\_Latched\_d <br> cptra\_scan\_mode\_Latched\_f <br> field\_storage.internal\_obf\_key <br> cptra_csr_hmac_key_reg | Statement of conformance | Caliptra HW threat model | | ||
| 940 | +| Device Keys | SoC shall implement protections for obfuscation and CSR HMAC key generation logic and protect against debug/sw/scandump visibility.<br>1. Any flops outside of Caliptra that store keys or parts of the keys should be excluded from scandump.<br>2. SoC shall ensure that the obfuscation key is sent only to Caliptra through HW wires, and it is not visible anywhere outside of Caliptra. | Statement of conformance | Required for Caliptra threat model | | ||
| 941 | +| Obfuscation Key | The obfuscation key shall be generated using a method that ensures 256 bits of entropy, such as an ESV certified entropy source or an on-die Physically Unclonable Function (PUF) that is compliant with industry standards. | Statement of conformance | Required for Caliptra threat model | | ||
| 942 | +| Obfuscation Key | SoC shall ensure that obfuscation key is available (and wires are stable) before Caliptra reset is de-asserted. | Statement of conformance | Functionality and security | | ||
| 889 | 943 | | Obfuscation Key | If not driven through PUF, SoC backend flows shall ECO the obfuscation key before tapeout. | Statement of conformance | Required by UDS and Field Entropy threat model | | |
| 890 | 944 | | Obfuscation Key | Rotation of the obfuscation key (if not driven through PUF) between silicon steppings of a given product (for example, A0 vs. B0 vs. PRQ stepping) is dependent on company-specific policies. | Statement of conformance | Required by UDS and Field Entropy threat model | | |
| 891 | -| Obfuscation Key | SoC backend flows should not insert obfuscation key flops into the scan chain. | Synthesis report | Required by UDS and Field Entropy threat model | | ||
| 892 | -| Obfuscation Key | For defense in depth, it is strongly recommended that debofuscation key flops are not on the scan chain. <br> Remove the following signals from the scan chain: <br> cptra\_scan\_mode\_Latched\_d <br> cptra\_scan\_mode\_Latched\_f <br> field\_storage.internal\_obf\_key | Statement of conformance | Caliptra HW threat model | | ||
| 893 | -| Obfuscation Key | SoC shall ensure that obfuscation key is available (and wires are stable) before Caliptra reset is de-asserted. | Statement of conformance | Functionality and security | | ||
| 894 | -| Obfuscation Key | SoC shall implement protections for obfuscation key generation logic and protect against debug/sw/scandump visibility.<br>1. Any flops outside of Caliptra that store obfuscation key or parts of the key should be excluded from scandump.<br>2. SoC shall ensure that the obfuscation key is sent only to Caliptra through HW wires, and it is not visible anywhere outside of Caliptra. | Statement of conformance | Required for Caliptra threat model | | ||
| 895 | -| CSR HMAC Key | SoC backend flows shall generate CSR signing key with appropriate NIST compliance as dictated in the Caliptra ROT specification. | Statement of conformance | Required by Caliptra threat model | | ||
| 896 | -| CSR HMAC Key | SoC backend flows shall ECO the CSR signing key before tapeout. | Statement of conformance | Required by Caliptra threat model | | ||
| 897 | -| CSR HMAC Key | SoC backend flows should rotate CSR signing key for each project. | Statement of conformance | Required by Caliptra threat model | | ||
| 898 | -| CSR HMAC Key | SoC backend flows should not insert CSR signing key flops into the scan chain. | Statement of conformance | Required by Caliptra threat model | | ||
| 899 | 945 | | DFT | Before scan is enabled (separate signal that SoC implements on scan insertion), SoC shall set Caliptra's scan\_mode indication to '1 for 5,000 clocks to allow secrets/assets to be flushed. | Statement of conformance | Required by Caliptra threat model | | |
| 900 | -| DFT | Caliptra’s TAP should be a TAP endpoint. | Statement of conformance | Functional requirement | | ||
| 901 | -| Mailbox | SoC shall provide an access path between the mailbox and the application CPU complex on SoCs with such complexes (for example, Host CPUs and Smart NICs). See the [Sender Protocol](#sender-protocol) section for details about error conditions. | Statement of conformance | Required for Project Kirkland and TDISP TSM | | ||
| 902 | -| Fuses | SoC shall burn non-field fuses during manufacturing. Required vs. optional fuses are listed in the architectural specification. | Test on silicon | Required for UDS threat model | | ||
| 946 | +| DFT* | If connected, Caliptra’s TAP should be a TAP endpoint. | Statement of conformance | Functional requirement | | ||
| 947 | +| DFD | Integrators shall not connect Caliptra's exposed RISC-V trace ports to any SoC logic. These ports are unvalidated and any implications to the SoC logic due to connecting these signals have not been analyzed. | Synthesis report | Required for Caliptra threat model | | ||
| 948 | +| Mailbox | SoC should provide an access path between the mailbox and the application CPU complex on SoCs with such complexes (for example, Host CPUs and Smart NICs). | Statement of conformance | Required for Project Kirkland and TDISP TSM | | ||
| 949 | +| Fuses | SoC shall burn non-field fuses during manufacturing. All *Caliptra Core* fuses must be implemented as described in the [fuse map table](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#fuse-map). Fuses used for *Subsystem* are optional outside of the subsystem context. | Test on silicon | Required for UDS threat model | | ||
| 903 | 950 | | Fuses | SoC shall expose an interface for burning field fuses. Protection of this interface is the SoC vendor’s responsibility. | Test on silicon | Required for Field Entropy | | |
| 904 | 951 | | Fuses | SoC shall write fuse registers and fuse done via immutable logic or ROM code. | Statement of conformance | Required for Caliptra threat model | | |
| 905 | 952 | | Fuses | SoC shall expose an API for programming Field Entropy as described in the architecture documentation. SoC shall ensure that Field Entropy can only be programmed via this API and shall explicitly prohibit burning of discrete Field Entropy bits and re-burning of already burned Field Entropy entries. | Test on silicon | Required for Field Entropy | | |
| 906 | 953 | | Fuses | SoC shall ensure that any debug read paths for fuses are disabled in PRODUCTION lifecycle state. | Test on silicon | Required for Field Entropy | | |
| 907 | 954 | | Fuses | SoC shall ensure that UDS\_SEED and Field Entropy supplied to Caliptra come directly from OTP fuses and there are no debug paths to inject new values. | Statement of conformance | Required for Caliptra threat model | | |
| 908 | 955 | | Fuses | SoC shall add integrity checks for Caliptra fuses as per SoC policy. | Statement of conformance | Reliability | | |
| 909 | -| Fuses | SoC should apply shielding/obfuscation measures to protect fuse macro. | Statement of conformance | Required for Caliptra threat model | | ||
| 910 | 956 | | Fuses | SoCs that intend to undergo FIPS 140-3 zeroization shall expose zeroization API as described in zeroization requirements in architecture specification. SoC shall apply appropriate authentication for this API to protect against denial of service and side channel attacks. | Test on silicon | FIPS 140-3 certification | | |
| 911 | 957 | | Security State | SoC shall drive security state wires in accordance with the SoC's security state. | Statement of conformance | Required for Caliptra threat model | | |
| 912 | 958 | | Security State | If SoC is under debug, then SoC shall drive debug security state to Caliptra. | Statement of conformance | Required for Caliptra threat model | | |
| @@ -914,14 +960,12 @@ | |||
| 914 | 960 | | Resets and Clocks | After asserting cptra\_pwrgood, SoC shall wait for a minimum of 10 clock cycles before deasserting cptra\_rst\_b. | Statement of conformance | Functional | | |
| 915 | 961 | | Resets and Clocks | SoC reset logic shall assume reset assertions are asynchronous and deassertions are synchronous. | Statement of conformance | Functional | | |
| 916 | 962 | | Resets and Clocks | SoC shall ensure Caliptra's powergood is tied to SoC’s own powergood or any other reset that triggers SoC’s cold boot flow. | Statement of conformance | Required for Caliptra threat model | | |
| 917 | -| Resets and Clocks | SoC shall ensure Caliptra clock is derived from an on-die oscillator circuit. | Statement of conformance | Required for Caliptra threat model | | ||
| 963 | +| Resets and Clocks | SoC shall ensure Caliptra's clock is driven by an on-die source such as an internal oscillator, PLL, or other clock generation circuit. This is to protect against clock fault injection or clock stretching attacks. | Statement of conformance | Required for Caliptra threat model | | ||
| 918 | 964 | | Resets and Clocks | SoC shall ensure that any programmable Caliptra clock controls are restricted to the SoC Manager. | Statement of conformance | Required for Caliptra threat model | | |
| 919 | -| Resets and Clocks | SoC should defend against external clock stop attacks. | Statement of conformance | Required for Caliptra threat model | | ||
| 920 | -| Resets and Clocks | SoC should defend against external clock glitching attacks. | Statement of conformance | Required for Caliptra threat model | | ||
| 921 | -| Resets and Clocks | SoC should defend against external clock overclocking attacks. | Statement of conformance | Required for Caliptra threat model | | ||
| 922 | -| TRNG | SoC shall either provision Caliptra with a dedicated TRNG or shared TRNG. It is highly recommended to use dedicated ITRNG | Statement of conformance | Required for Caliptra threat model and Functional | | ||
| 965 | +| Resets and Clocks | SoC should employ reasonable countermeasures to defend against advanced physical attacks like clock glitching. These countermeasures may be guided by common best practices as well as specific customer requirements. | Statement of conformance | Required for Caliptra threat model | | ||
| 923 | 966 | | TRNG | SoC shall provision the Caliptra embedded TRNG with an entropy source if that is used (vs. SoC-shared TRNG API support). | Statement of conformance | Functional | | |
| 924 | 967 | | TRNG | If the TRNG is shared, then upon TRNG\_REQ, SoC shall use immutable logic or code to program Caliptra's TRNG registers. | Statement of conformance | Required for Caliptra threat model and Functional | | |
| 968 | +| TRNG* | SoC shall either provision Caliptra with a dedicated TRNG or shared TRNG. It is highly recommended to use dedicated ITRNG. When using Caliptra Subsystem, dedicated internal TRNG is required for Caliptra. | Statement of conformance | Required for Caliptra threat model and Functional | | ||
| 925 | 969 | | SRAMs | SoC shall ensure timing convergence with 1-cycle read path for SRAMs. | Synthesis report | Functional | | |
| 926 | 970 | | SRAMs | SoC shall size SRAMs to account for SECDED. Exception for Adams-Bridge SRAMs that do not utilize SECDED. | Statement of conformance | Functional | | |
| 927 | 971 | | SRAMs | SoC shall write-protect fuses that characterize the SRAM. | Statement of conformance | Required for Caliptra threat model | | |
| @@ -934,29 +978,25 @@ | |||
| 934 | 978 | | AXI USER | Assigned AXI USER values must be unique for each agent on the interconnect. All SoC AXI agents that have an access path to Caliptra AXI subordinate (or any Caliptra Subsystem components, when using the Subsystem mode) via AXI must either (a) generate AXI transactions using an AXI_USER value that is unique from that used by all other AXI agents on the interconnect or (b) generate AXI transactions using an AXI_USER value that will never overlap with the configured valid AXI users, if the agent is not a valid mailbox user, valid fuse user, or valid trng user. For example, if any AXI agents utilize the AxUSER field for any type of dynamic metadata and are on the same AXI interconnect as Caliptra, all possible AxUSER values from those agents should be avoided for assigning Caliptra VALID AXI USER values. Because AXI AxUSER signals are used to identify accessing agents and enforce access rules, this rule ensures that no single agent may ever generate an AXI transaction that identifies it as originating from a different agent. | Statement of conformance | Required for Caliptra threat model | | |
| 935 | 979 | | Error reporting | SoC shall report Caliptra error outputs. | Statement of conformance | Telemetry and monitoring | | |
| 936 | 980 | | Error reporting | SoC shall only recover Caliptra fatal errors via SoC power-good reset. | Statement of conformance | Required for Caliptra threat model | | |
| 937 | -| TRNG AXI USER Programming rules | If SoC doesn’t program the CPTRA\_TRNG\_AXI\_USER\_LOCK\[LOCK\] and Caliptra is configured in external TRNG mode, then Caliptra HW will accept TRNG data from any SoC entity. | Security | Required for Caliptra threat model | | ||
| 938 | -| TRNG AXI USER Programming rules | If SoC programs CPTRA\_TRNG\_VALID\_AXI\_USER and sets CPTRA\_TRNG\_AXI\_USER\_LOCK\[LOCK\] and Caliptra is configured in external TRNG mode, then Caliptra HW will accept TRNG data only from the entity that is programmed into the AXI USER register. | Security | Required for Caliptra threat model | | ||
| 939 | -| TRNG AXI USER Programming rules | It is strongly recommended that these AXI USER registers are either set at integration time through integration parameters or be programmed by the SoC ROM before any mutable FW or ROM patches are absorbed. | Security | Required for Caliptra threat model | | ||
| 940 | -| TRNG AXI USER Programming rules | It is strongly recommended that integrators set the TRNG valid AXI_USER to a non-zero value, due to the above uniqueness requirement. | Security | Required for Caliptra threat model | | ||
| 941 | -| MAILBOX AXI USER programming rules | 5 AXI USER attribute registers are implemented at SoC interface. | Security | Required for Caliptra threat model | | ||
| 942 | -| MAILBOX AXI USER programming rules | At boot time, a default SoC or AXI USER can access the mailbox. The value of this AXI USER is an integration parameter, CPTRA\_DEF\_MBOX\_VALID\_AXI\_USER. | Security | Required for Caliptra threat model | | ||
| 943 | -| MAILBOX AXI USER programming rules | The value of CPTRA\_MBOX\_VALID\_AXI\_USER\[4:0\] register can be programmed by SoC. After it is locked, it becomes a valid AXI USER for accessing the mailbox. | Security | Required for Caliptra threat model | | ||
| 944 | -| MAILBOX AXI USER programming rules | CPTRA\_SET\_MBOX\_AXI\_USER\_INTEG parameter can be set along with the corresponding CPTRA\_MBOX\_VALID\_AXI\_USER parameter at integration time. If set, these integration parameters take precedence over the CPTRA\_MBOX\_VALID\_AXI\_USER\[4:0\] register. | Security | Required for Caliptra threat model | | ||
| 945 | -| MAILBOX AXI USER programming rules | SoC logic (ROM, HW) that is using the Caliptra mailbox right out of cold reset, without first configuring the programmable mailbox AXI USER registers, must send the mailbox accesses with the default AXI USER, CPTRA\_DEF\_MBOX\_VALID\_AXI\_USER. | Security | Required for Caliptra threat model | | ||
| 946 | -| MAILBOX AXI USER programming rules | For CPTRA\_MBOX\_VALID\_AXI\_USER\[4:0\], the corresponding lock bits MUST be programmed to ‘1. This enables the mailbox to accept transactions from non-default AXI USERS. | Security | Required for Caliptra threat model | | ||
| 947 | -| MAILBOX AXI USER programming rules | It is strongly recommended that mailbox AXI USER registers are either set at integration time through integration parameters or are programmed by the SoC ROM before any mutable FW or ROM patches are applied. | Security | Required for Caliptra threat model | | ||
| 948 | -| MAILBOX AXI USER Programming rules | It is strongly recommended that integrators set the MAILBOX valid AXI_USER to non-zero values, due to the above uniqueness requirement. | Security | Required for Caliptra threat model | | ||
| 949 | -| FUSE AXI USER programming rules | 1 AXI USER attribute register is implemented at SoC interface: CPTRA\_FUSE\_VALID\_AXI\_USER. | Security | Required for Caliptra threat model | | ||
| 950 | -| FUSE AXI USER programming rules | CPTRA\_FUSE\_AXI\_USER\_LOCK locks the programmable valid axi user register, and marks the programmed value as valid. | Security | Required for Caliptra threat model | | ||
| 951 | -| FUSE AXI USER programming rules | Integrators can choose to harden the valid axi user for fuse access by setting the integration parameter, CPTRA\_FUSE\_VALID\_AXI\_USER, to the desired value in RTL, and by setting CPTRA\_SET\_FUSE\_AXI\_USER\_INTEG to 1. If set, these integration parameters take precedence over the CPTRA\_FUSE\_VALID\_AXI\_USER register. | Security | Required for Caliptra threat model | | ||
| 952 | -| FUSE AXI USER Programming rules | It is strongly recommended that integrators set the FUSE valid AXI_USER to a non-zero value, due to the above uniqueness requirement. | Security | Required for Caliptra threat model | | ||
| 981 | +| TRNG AXI USER Programming rules | If integrating Caliptra in passive mode with an external TRNG, SoC integrators must assign an SoC agent that is permitted to access Caliptra's TRNG REQ HW API via AXI. All other AXI agents must be excluded from such access. SoC integrators must enforce this exclusivity either by using the access restriction features described in [TRNG REQ HW API](#TRNG-REQ-HW-API) or by implementing an alternative mechanism. For example, restricting the hardware paths to Caliptra through an AXI interconnect to only the agent that is allowed access also satisfies this requirement. | Security | Required for Caliptra threat model | | ||
| 982 | +| TRNG AXI USER Programming rules* | It is strongly recommended that the TRNG AXI USER register be programmed by the SoC ROM before any mutable FW or ROM patches are absorbed. | Security | Required for Caliptra threat model | | ||
| 983 | +| TRNG AXI USER Programming rules* | It is strongly recommended that integrators set the TRNG valid AXI_USER to a non-zero value, due to the AXI USER uniqueness requirement. | Security | Required for Caliptra threat model | | ||
| 984 | +| MAILBOX AXI USER Programming rules | SoC logic (ROM, HW) that uses the Caliptra mailbox right out of cold reset, without first configuring the programmable mailbox AXI USER registers, must send the mailbox accesses with the default AXI USER, CPTRA\_DEF\_MBOX\_VALID\_AXI\_USER. | Security | Required for Caliptra threat model | | ||
| 985 | +| MAILBOX AXI USER Programming rules | SoC integrators must assign a subset of SoC agents that are permitted to access Caliptra's mailbox via AXI. All other AXI agents must be excluded from such access. SoC integrators must enforce this exclusivity either by using the access restriction features described in [MAILBOX AXI USER attribute register](#MAILBOX-AXI-USER-attribute-register) or by implementing an alternative mechanism. For example, restricting the hardware paths to Caliptra through an AXI interconnect to only those agents that are allowed access also satisfies this requirement. | Security | Required for Caliptra threat model | | ||
| 986 | +| MAILBOX AXI USER Programming rules* | It is strongly recommended that mailbox AXI USER registers are either set at integration time through integration parameters or are programmed by the SoC ROM before any mutable FW or ROM patches are applied. | Security | Required for Caliptra threat model | | ||
| 987 | +| MAILBOX AXI USER Programming rules* | It is strongly recommended that integrators set the MAILBOX valid AXI_USER to non-zero values, due to the AXI USER uniqueness requirement. | Security | Required for Caliptra threat model | | ||
| 988 | +| FUSE AXI USER Programming rules | SoC integrators must assign a single SoC agent that is permitted to access Caliptra's fuse registers via AXI. All other AXI agents must be excluded from such access. SoC integrators must enforce this exclusivity either by using the access restriction features described in [FUSE AXI USER attribute](#FUSE-AXI-USER-attribute) or by implementing an alternative mechanism. For example, restricting the hardware paths to Caliptra through an AXI interconnect to only the agent that is allowed access to fuse registers also satisfies this requirement. | Security | Required for Caliptra threat model | | ||
| 989 | +| FUSE AXI USER Programming rules* | It is strongly recommended that fuse AXI USER register is either set at integration time through the integration parameter or is programmed by the SoC ROM before any mutable FW or ROM patches are applied. | Security | Required for Caliptra threat model | | ||
| 990 | +| FUSE AXI USER Programming rules* | It is strongly recommended that integrators set the FUSE valid AXI_USER to a non-zero value, due to the AXI USER uniqueness requirement. | Security | Required for Caliptra threat model | | ||
| 953 | 991 | | Manufacturing | SoC shall provision an IDevID certificate with fields that conform to the requirements described in [Provisioning IDevID during manufacturing](https://github.com/chipsalliance/Caliptra/blob/main/doc/Caliptra.md#provisioning-idevid-during-manufacturing). | Statement of conformance | Functionality | | |
| 954 | 992 | | Manufacturing | Caliptra relies on obfuscation for confidentiality of UDS\_SEED. It is strongly advised to implement manufacturing policies to protect UDS\_SEED as defense in depth measures. <br>1, Prevent leakage of UDS\_SEED on manufacturing floor.<br>2. Implement policies to prevent cloning (programming same UDS\_SEED into multiple devices).<br>3. Implement policies to prevent signing of spurious IDEVID certs. | Statement of conformance | Required for Caliptra threat model | | |
| 955 | 993 | | Chain of trust | SoC shall ensure all mutable code and configuration measurements are stashed into Caliptra. A statement of conformance lists what is considered mutable code and configuration vs. what is not. The statement also describes the start of the boot sequence of the SoC and how Caliptra is incorporated into it. | Statement of conformance | Required for Caliptra threat model | | |
| 956 | 994 | | Chain of trust | SoC shall limit the mutable code and configuration that persists across the Caliptra powergood reset. A statement of conformance lists what persists and why this persistence is necessary. | Statement of conformance | Required for Caliptra threat model | | |
| 957 | -| Implementation | SoC shall apply size-only constraints on cells tagged with the "u\_\_size\_only\_\_" string and shall ensure that these are not optimized in synthesis and PNR | Statement of conformance | Required for Caliptra threat model | | ||
| 958 | -| GLS FEV | GLS FEV must be run to make sure netlist and RTL match and none of the countermeasures are optimized away. See the following table for example warnings from synthesis runs to resolve through FEV | GLS simulations pass | Functional requirement | | ||
| 959 | - | ||
| 995 | +| Implementation | Integrators shall follow the [Primitive Instantiation Process](#primitive-instantiation) to ensure that process-specific library cells are used and appropriately named. Integrators shall apply size-only constraints on the resulting cells tagged with the "u\_\_size\_only\_\_" string. Integrators shall review results from synthesis and PNR to ensure that these are not optimized away. | Statement of conformance | Required for Caliptra threat model | | ||
| 996 | +| GLS FEV | GLS FEV must be run to make sure netlist and RTL match. See the following table for example warnings from synthesis runs to resolve through FEV. | GLS simulations pass | Functional requirement | | ||
| 997 | + | ||
| 998 | + | ||
| 999 | +\* **Note: Deviation or exemption from requirements marked with * may be permitted if documented justification is provided and approved by the SRP and TAC.** | ||
| 960 | 1000 | ||
| 961 | 1001 | *Table 20: Caliptra synthesis warnings for FEV evaluation* | |
| 962 | 1002 | ||
| @@ -968,6 +1008,39 @@ | |||
| 968 | 1008 | | ecc_montgomerymultiplier | Netlist for always_ff block does not contain flip flop | 274, 326 | Output width is smaller than internal signals, synthesis optimizes away the extra internal flops with no loads | | |
| 969 | 1009 | | Multiple modules | Signed to unsigned conversion occurs ||| | |
| 970 | 1010 | ||
| 1011 | + | ||
| 1012 | +## OCP LOCK Caliptra ROM & Firmware Requirements | ||
| 1013 | + | ||
| 1014 | +The following rules outline additional steps that are divided between Caliptra ROM and Caliptra Runtime firmware to ensure secure operation protocol compliance to OCP L.O.C.K. | ||
| 1015 | +As described in the Caliptra Hardware Specification, when operating in OCP LOCK mode Key Vault slot 16 (KV16) is designated for holding the MDK and Key Vault slot 23 (KV23) is designated for holding the MEK. | ||
| 1016 | + | ||
| 1017 | +- **DOE error status (KV write failure):** | ||
| 1018 | + Introduce a new status bit; ROM must check it after any DOE flow to ensure the KV write succeeded. | ||
| 1019 | +- **HEK DOE flow**: | ||
| 1020 | + Must be locked after execution (like other DOE flows). ROM must run the HEK DOE flow even in non-LOCK contexts to lock it. Reset only by hard reset. | ||
| 1021 | +- **Derivations & locking**: | ||
| 1022 | + - Derive the MDK to **KV16**, then set the **lock_wr** control bit of KV16. | ||
| 1023 | + - If OCP LOCK is enabled, derive **HEK** to **KV22**, then set the **lock_wr** control bit of KV23. | ||
| 1024 | + - Perform this **before** setting `OCP_LOCK_IN_PROGRESS` since HEK derivation depends on the **HEK seed** and **standard CDI derivatives** (from standard KV slots). | ||
| 1025 | +- **Setting lock state:** | ||
| 1026 | + If OCP LOCK is enabled, ROM **MUST** set `OCP_LOCK_IN_PROGRESS` before transitioning to the First Mutable Code (FMC) image. | ||
| 1027 | +- **KV23 usage constraints:** | ||
| 1028 | + Never attempt to write anything to **KV23** except **MEK** (produced by AES). | ||
| 1029 | + - DOE will flag an error and **stall** if a write to **KV23** is attempted while OCP LOCK is enabled. Note that this differs from other cryptographic engines, which use the SS_OCP_LOCK_CTRL.LOCK_IN_PROGRESS bit to enforce the respective ruleset. This is because HEK seed deobfuscation is performed by the ROM prior to setting LOCK_IN_PROGRESS. | ||
| 1030 | +- **DMA programming with KV:** | ||
| 1031 | + The programmed byte count must match the value on the input strap_ss_key_release_key_size strap. The programmed destination address must match the value on the input strap_ss_key_release_base_addr. Violation of either of these rules will trigger a command decode error in the DMA. | ||
| 1032 | +- **KV filtering rules:** | ||
| 1033 | + Cryptographic operations attempting to read from a Standard Key Vault slot and write a result to a LOCK Key Vault slot will fail (the same rule holds for the LOCK Key Vault slot → Standard Key Vault slot path). The error status is reported as a Key Vault Write failure in the respective cryptographic engine's register block. | ||
| 1034 | +- **AES API updates:** | ||
| 1035 | + - Similar to all cryptographic core operations in Caliptra, firmware must set both the Key Vault Read Control and Key Vault Write Control registers prior to beginning the AES operation. | ||
| 1036 | + - When AES operation parameters match the configuration for which output data is written to KV23, result data is masked from being presented on the `dataout` register. Also, the STATUS.OUTPUT_LOST register bit will be asserted to reflect that output data has been blocked. | ||
| 1037 | + - AES operations used to decrypt Key Content into KV23 must be performed using automatic mode; manual operation is not supported for this process. | ||
| 1038 | + - Firmware shall execute the clear operation after any AES operation used to generate or load the MEK. | ||
| 1039 | +- **Strap validation:** | ||
| 1040 | + Read and confirm valid values for: | ||
| 1041 | + - [SS_KEY_RELEASE_BASE_ADDR](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.SS_KEY_RELEASE_BASE_ADDR_L) | ||
| 1042 | + - [KEY_RELEASE_KEY_SIZE](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.soc_ifc_reg.SS_KEY_RELEASE_SIZE) | ||
| 1043 | +- **Firmware must clear any obfuscated MEK from memory immediately after use.** | ||
| 971 | 1044 | ||
| 972 | 1045 | ## Integrator RTL modification requirements | |
| 973 | 1046 | ||
| @@ -1047,14 +1120,14 @@ | |||
| 1047 | 1120 | In an unconstrained environment, several CDC violations are anticipated. CDC analysis requires the addition of constraints to identify valid synchronization mechanisms and/or static/pseudo-static signals. | |
| 1048 | 1121 | ||
| 1049 | 1122 | ## Analysis of missing synchronizers | |
| 1050 | -* All of the signals, whether single-bit or multi-bit, originate from the CalitpraClockDomain clock and their endpoint is the JTAG clock domain. | ||
| 1123 | +* All of the signals, whether single-bit or multi-bit, originate from the CaliptraClockDomain clock and their endpoint is the JTAG clock domain. | ||
| 1051 | 1124 | * The violations occur on the read path to the JTAG. | |
| 1052 | 1125 | * We only need to synchronize the controlling signal for this interface. | |
| 1053 | 1126 | * Inside the dmi\_wrapper, the dmi\_reg\_en and dmi\_reg\_rd\_en comes from dmi\_jtag\_to\_core\_sync, which is a 2FF synchronizer. | |
| 1054 | 1127 | ||
| 1055 | 1128 | The following code snippets and schematic diagrams illustrate the CDC violations that end at the JTAG interface. | |
| 1056 | 1129 | ||
| 1057 | -*Figure 8: Schematic diagram and code snippet showing JTAG-originating CDC violations* | ||
| 1130 | +*Figure: Schematic diagram and code snippet showing JTAG-originating CDC violations* | ||
| 1058 | 1131 | ||
| 1059 | 1132 |  | |
| 1060 | 1133 | ||
| @@ -1111,7 +1184,7 @@ | |||
| 1111 | 1184 | ||
| 1112 | 1185 | The reset definitions can be visually represented as shown in the following diagram. | |
| 1113 | 1186 | ||
| 1114 | -*Figure 9: Reset tree for Caliptra* | ||
| 1187 | +*Figure: Reset tree for Caliptra* | ||
| 1115 | 1188 | ||
| 1116 | 1189 |  | |
| 1117 | 1190 | ||
| @@ -1138,7 +1211,7 @@ | |||
| 1138 | 1211 | ||
| 1139 | 1212 | The reset sequencing is illustrated in the following waveform. | |
| 1140 | 1213 | ||
| 1141 | -*Figure 10: Reset sequencing waveform for Caliptra* | ||
| 1214 | +*Figure: Reset sequencing waveform for Caliptra* | ||
| 1142 | 1215 | ||
| 1143 | 1216 |  | |
| 1144 | 1217 | ||
| @@ -1205,7 +1278,7 @@ | |||
| 1205 | 1278 | ||
| 1206 | 1279 | For violations in Sl No 1 and 2, the schematic for the crossing is shown in the following figure. | |
| 1207 | 1280 | ||
| 1208 | -*Figure 11: Schematic for RDC violations #1 and #2* | ||
| 1281 | +*Figure: Schematic for RDC violations #1 and #2* | ||
| 1209 | 1282 | ||
| 1210 | 1283 |  | |
| 1211 | 1284 | ||
| @@ -1213,7 +1286,7 @@ | |||
| 1213 | 1286 | ||
| 1214 | 1287 | For violations in Sl No 3 and 4, the schematic for the crossing is shown in the following figure. | |
| 1215 | 1288 | ||
| 1216 | -*Figure 12: Schematic for RDC violations #3 and #4* | ||
| 1289 | +*Figure: Schematic for RDC violations #3 and #4* | ||
| 1217 | 1290 | ||
| 1218 | 1291 |  | |
| 1219 | 1292 | ||
Image not present in this version
