From eabd98bb54404e339c128a218c5d50230cf91eb8 Mon Sep 17 00:00:00 2001 From: steph-morton <143441730+steph-morton@users.noreply.github.com> Date: Thu, 14 Sep 2023 13:41:08 -0700 Subject: [PATCH] edit pass for second part of high level architecture section (#91) * edit pass for second part of high level architecture section * updated based on feedback --- doc/Caliptra.md | 151 ++++++++++++++++++++++++------------------------ 1 file changed, 74 insertions(+), 77 deletions(-) diff --git a/doc/Caliptra.md b/doc/Caliptra.md index f325e98..e5d7d31 100644 --- a/doc/Caliptra.md +++ b/doc/Caliptra.md @@ -199,7 +199,7 @@ A Caliptra RTM implements the DPE API, allowing Caliptra to derive and wield a D This specification follows the industry standards and specifications listed in [References](#References). -## NIST SP800-193 Platform Firmware Resiliency +## NIST SP 800-193 Platform Firmware Resiliency Per [Reference 1](#ref-1), RoT subsystems are required to fulfill three principles: *protection, detection* and *recovery*. The associated RoT services are referred to as: @@ -225,7 +225,7 @@ As an extension to controlling configuration, the Silicon RoT must control the s Measurements must be uniquely bound to the device and its manufacturer at a minimum. This establishes the need for **Identity** services in the Silicon RoT, which serve as the basis for key derivation and attestation authenticity. -For further details about how Caliptra addresses NIST SP800-193, see [Device Resilience](#device-resilience). +For further details about how Caliptra addresses NIST SP 800-193, see [Device Resilience](#device-resilience). ## Trusted Computing Group (TCG) DICE Attestation @@ -319,7 +319,7 @@ The Caliptra Core blocks consume the Tcc and Tcw trust level components. This b Assets are defined to be secrets or abilities that must be protected by an owner or user of the asset. Ownership means that the owner has the responsibility to protect these assets and must only make them available based on a defined mechanism while protecting all other assets. -An example of when an owner must protect assets is moving from secure mode to unsecure mode. Another example is moving from one owner to another. Before moving through these transitions, the owner must ensure all assets are removed, disabled, or protected based on how the use case is defined. +An example of when an owner must protect assets is moving from secure mode to insecure mode. Another example is moving from one owner to another. Before moving through these transitions, the owner must ensure all assets are removed, disabled, or protected based on how the use case is defined. *Table 6: Assets* @@ -664,113 +664,110 @@ The SoC may support a fuse bank for representing the hash of the owner's public The owner key, when represented in fuses or in the FMC's alias certificate, is a SHA-384 hash of a structure that contains a list of owner public keys. This supports key rotation. -## Provisioning IDevID During Manufacturing +## Provisioning IDevID during manufacturing ![](./images/Caliptra_manuf_flow1.png) -*Figure 7: Device Manufacturing Identity Flow* +*Figure 7: Device manufacturing identity flow* -1. High Volume Manufacturing (HVM) programs NIST compliant UDS into fuses using SOC specific fuse programming flow. Note that this UDS goes through an obfuscation function within Caliptra IP. -2. SOC will drive the security state indicating that its a manufacturing flow. Refer to *[Caliptra Security States](#caliptra-security-states)*) for encodings. -3. SOC (using a GPIO pin or SOC ROM) will drive BootFSMBrk (this is also used for debug cases). This can be driven at any time before cptra\_rst\_b is deasserted. -4. SOC will follow the boot flow as defined in Caliptra IP HW boot flow to assert cptra\_pwrgood and deassert cptra\_rst\_b, followed by writing to the fuse registers. -5. HVM through JTAG or using Caliptra SOC interface writes to “CPTRA\_DBG\_MANUF\_SERVICE\_REG” requesting for a CSR (refer to the [Caliptra ROM specification](https://github.com/chipsalliance/caliptra-sw/blob/main/rom/dev/README.md) for bit definitions) -6. HVM through JTAG or using Caliptra SOC interface writes to “CPTRA\_BOOTFSM\_GO” to allow Caliptra’s internal BootFSM to continue to bring up uController out of reset -7. ROM will look at the manufacturing state encoding, “CPTRA\_DBG\_MANUF\_SERVICE\_REG” and populates the Caliptra internal SRAM \[MB SRAM hardware structure is reused\] with the CSR and CSR envelope signature and write to Caliptra internal register to indicate CSR is valid (refer to [Caliptra ROM specification](https://github.com/chipsalliance/caliptra-sw/blob/main/rom/dev/README.md) and [Identity](#identity) section in this document on the ROM steps to generate the CSR) -8. HVM through JTAG or using SOC interface polls for “requested service\[s\]” bit\[s\] available in “CPTRA\_BOOT\_STATUS” register. -9. HVM through JTAG reads mbox\_status\[3:0\] to check if the data is ready to be read (DATA\_READY encoding). -10. HVM must write a bit in CPTRA\_DBG\_MANUF\_SERVICE\_REG over JTAG that it has completed reading CSR -11. Caliptra IP HW will now open up the Caliptra Mailbox for SOC usages such as FW loading (if required in some HVM flows) - 1. Note that until the above write is complete, SOC will not get a grant/lock of the APB-exposed mailbox interface. - -## Certificate Format +1. High Volume Manufacturing (HVM) programs NIST compliant UDS into fuses using SoC-specific fuse programming flow. Note that this UDS goes through an obfuscation function within Caliptra IP. +2. SoC drives the security state, which indicates that it's a manufacturing flow. See [Caliptra Security States](#caliptra-security-states) for encodings. +3. SoC (using a GPIO pin or SoC ROM) drives BootFSMBrk (this is also used for debug cases). This can be driven at any time before cptra\_rst\_b is deasserted. +4. SoC follows the boot flow as defined in Caliptra IP HW boot flow to assert cptra\_pwrgood and deassert cptra\_rst\_b, followed by writing to the fuse registers. +5. HVM, through JTAG or using the Caliptra SoC interface, writes to “CPTRA\_DBG\_MANUF\_SERVICE\_REG”, requesting a CSR (see the [Caliptra ROM specification](https://github.com/chipsalliance/caliptra-sw/blob/main/rom/dev/README.md) for bit definitions). +6. HVM, through JTAG or using the Caliptra SoC interface, writes to “CPTRA\_BOOTFSM\_GO” to allow Caliptra’s internal BootFSM to continue to bring up uController out of reset. +7. ROM looks at the manufacturing state encoding, “CPTRA\_DBG\_MANUF\_SERVICE\_REG”, and populates the Caliptra internal SRAM \[the mailbox SRAM hardware structure is reused\] with the CSR and CSR envelope signature. It then writes to the Caliptra internal register to indicate the CSR is valid (see the [Caliptra ROM specification](https://github.com/chipsalliance/caliptra-sw/blob/main/rom/dev/README.md) and [Identity](#identity) sections in this document on the ROM steps to generate the CSR). +8. HVM, through JTAG or using the SoC interface, polls for “requested service\[s\]” bit\[s\] available in “CPTRA\_BOOT\_STATUS” register. +9. HVM, through JTAG, reads mbox\_status\[3:0\] to check if the data is ready to be read (DATA\_READY encoding). +10. HVM must write a bit in CPTRA\_DBG\_MANUF\_SERVICE\_REG over JTAG, indicating that it completed reading the CSR. +11. Caliptra IP HW opens the Caliptra Mailbox for SoC usages, such as FW loading (if required in some HVM flows). Until this write operation is complete, the SoC does not get a grant/lock of the APB-exposed mailbox interface. -Device Identity Certificates follow the X.509 v3 format described in RFC 5280. The values in the X.509 certificate shall follow the DICE TCBInfo fields, as defined in [Reference 5](#ref-5). The owner public key shall be extended into VendorInfo, with the security operational state reflecting the flags of DICE TCBInfo. Additional fields may be extended into VendorInfo. +## Certificate format -[**TODO for 0.8 release**: The x509 owner key, JTAG state, public key used to verify firmware should be extended in the Cert. ] +Device identity certificates follow the X.509 v3 format described in RFC 5280. The values in the X.509 certificate follow the DICE TCBInfo fields, as defined in [Reference 5](#ref-5). The owner public key is extended into VendorInfo, with the security operational state reflecting the flags of DICE TCBInfo. Additional fields may be extended into VendorInfo. -## Caliptra Security States +## Caliptra security states ![](./images/Caliptra_security_states.png) -*Figure 8: Caliptra Security States* +*Figure 8: Caliptra security states* **Definitions** -* **Non-Debug:** Caliptra JTAG is NOT open for uController and HW debug -* **Debug:** Caliptra JTAG is open for uController and HW debug -* **Unprovisioned:** Blank/unprogrammed fuse part -* **Manufacturing:** Device is going through manufacturing flow where High-Volume-Manufacturing (HVM) Caliptra fuses are being programmed -* **Production:** All Caliptra’s HVM Fuses are programmed. +* **Non-Debug:** Caliptra JTAG is not open for uController and HW debug. +* **Debug:** Caliptra JTAG is open for uController and HW debug. +* **Unprovisioned:** Blank/unprogrammed fuse part. +* **Manufacturing:** Device is in the manufacturing flow where HVM Caliptra fuses are programmed. +* **Production:** All of Caliptra’s HVM fuses are programmed. **Notes:** -* Caliptra’s security state is determined by the SOC’s security state and SOC device lifecycle state. +* Caliptra’s security state is determined by the SoC’s security state and the SoC device lifecycle state. * Caliptra’s state is considered a mode of operation. - * Caliptra security state is defined by the uppermost bit of the encoding below; 1=DebugLocked and 0=DebugUnlocked - * Lower 2 bits are mapped to device lifecycle (Unprovisioned, Manufacturing, Production) -* SoC’s security state may also be influenced by its own device life cycle. A HW state machine must drive the SoC security state. + * Caliptra security state is defined by the uppermost bit of the encoding below; 1=DebugLocked and 0=DebugUnlocked. + * Lower 2 bits are mapped to device lifecycle (unprovisioned, manufacturing, production). +* SoC’s security state may also be influenced by its own device lifecycle. A HW state machine must drive the SoC security state. * Caliptra’s security state determines Caliptra’s debug state and the state of its security assets. -* In general, if Caliptra is in unsecure state, all keys, assets are ‘zeroized’. Zeroized may mean switching to all 0s or 1s or debug keys based on the key. Refer to [Caliptra Assets](#assets) for a description of Caliptra assets. +* In general, if Caliptra is in an insecure state, all keys and assets are ‘zeroized’. Zeroized may mean switching to all 0s, 1s, or debug keys based on the key. See [Caliptra Assets](#assets) for information. -*Table 7: Security States* +*Table 7: Security states* -| {Security State, Device Life Cycle State[2:0]} | State | Definition | State Transition Requirement | +|Security state, device lifecycle state [2:0]| State | Definition | State transition requirement | |------------------------------------------------|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| 000b | DebugUnlocked and Unprovisioned | This is Caliptra’s default state; it is used for development and early Caliptra bring up. This state is not used to provision the Caliptra assets. In this state:
NIST SP800-193 Chapter | +NIST SP 800-193 Chapter | Requirement | -Caliptra Responsibility | +Caliptra responsibility |
---|---|---|---|---|
4.1.1 | -All security mechanisms and functions shall be founded to Roots of Trust. | -Caliptra forms the basis for all trust in the SoC starting from execution of its immutable ROM. See chapter on Secure Boot Flow. | +All security mechanisms and functions shall be founded to Roots of Trust (RoT). | +Caliptra forms the basis for all trust in the SoC starting from execution of its immutable ROM. See the Secure Boot Flow section. |
If Chains of Trust (CoT) are used, RoT shall serve as the anchor for the CoT. | -All other firmware shall be authenticated and executed as part of a Chain of Trust extended from the Caliptra ROM. See chapter on Secure Boot Flow. | +All other firmware shall be authenticated and executed as part of a Chain of Trust extended from the Caliptra ROM. See the Secure Boot Flow section. | ||
All RoTs and CoTs shall either be immutable or protected using mechanisms which ensure all RoTs and CoTs remain in a state of integrity. | -All other firmware is authenticated and executed as part of a Chain of Trust extended from the Caliptra ROM. See chapter on Secure Boot Flow. | +All RoTs and CoTs shall either be immutable or protected using mechanisms that ensure all RoTs and CoTs remain in a state of integrity. | +All other firmware is authenticated and executed as part of a Chain of Trust extended from the Caliptra ROM. See the Secure Boot Flow section. | |
All elements of the Chains of Trust for Update, Detection and Recovery in non-volatile storage shall be implemented in platform firmware. | -Caliptra forms the basis for Root of Trust for Measurement (or Detection). All other silicon RoT capabilities are extended by additional firmware loaded in the SoC and anchored by the Caliptra RTM. | +All elements of the CoT for update, detection, and recovery in non-volatile storage shall be implemented in platform firmware. | +Caliptra forms the basis for RTM (or detection). All other silicon RoT capabilities are extended by additional firmware loaded in the SoC and anchored by the Caliptra RTM. | |
The functions of the RoTs or CoTs shall be resistant to any tampering attempted by software running under, or as part of, the operating system on the host processor. | @@ -781,53 +778,53 @@ Table 8: NIST SP800-193 Requirements describes the NIST SP800-193 requirements t||||
CoTs may be extended to include elements that are not from non-volatile storage. Before use, those elements shall be cryptographically verified by an earlier element of the CoT. | -Caliptra shall verify the authenticity of its firmware using an approved digital signature verification mechanism. Caliptra shall also measure the SoC Security Processor FMC code before it is verified and executed by the SoC. | +Caliptra shall verify the authenticity of its firmware using an approved digital signature verification mechanism. Caliptra shall also measure the SoC security processor FMC code before it is verified and executed by the SoC. | ||
4.1.2 | If the key store is updateable, then the key store shall be updated using an authenticated update mechanism, absent unambiguous physical presence through a secure local update. | -Hashes for the keys used to authenticate Caliptra FW are programmed into fuses during manufacturing. If a key is deemed to be compromised, that key may be revoked and the next key used instead. See chapter on Fuse/OTP Requirements. | +Hashes for the keys used to authenticate Caliptra FW are programmed into fuses during manufacturing. If a key is deemed to be compromised, that key may be revoked and the next key used instead. See the Fuse/OTP Requirements section. | |
4.1.3 | -Each platform device which implements a detection capability shall rely on either a Root of Trust for Detection (RTD), or a Chain of Trust for Detection (CTD) which is anchored by an RTD, for its detection. | -Caliptra forms the basis for all trust in the SoC starting from execution of its immutable ROM. All other firmware shall be authenticated and executed as part of a Chain of Trust extended from the Caliptra ROM. See chapter on Secure Boot Flow. | +Each platform device that implements a detection capability shall rely on either a Root of Trust for Detection (RTD), or a Chain of Trust for Detection (CTD). The CTD is anchored by an RTD for its detection. | +Caliptra forms the basis for all trust in the SoC starting from execution of its immutable ROM. All other firmware shall be authenticated and executed as part of a CoT extended from the Caliptra ROM. See the Secure Boot Flow section. |
The RTD or CTD shall include or have access to information necessary to detect corruption of firmware code and critical data. | -Caliptra relies on hashes of authorized keys stored in fuses. Those hashes are then checked against public keys found in firmware headers to authenticate Caliptra’s runtime firmware. Caliptra relies on redundancy in the fuses to protect the key and configuration data. See chapter on Fuse/OTP Requirements | +Caliptra relies on hashes of authorized keys stored in fuses. Those hashes are then checked against public keys found in firmware headers to authenticate Caliptra’s runtime firmware. Caliptra relies on redundancy in the fuses to protect the key and configuration data. See the Fuse/OTP Requirements section. | ||
4.2.3 | -If Critical Platform Firmware code in non-volatile memory is copied into RAM to be executed (for performance, or for other reasons) then the firmware program in RAM shall be protected from modification by software or shall complete its function before software starts. | +If critical platform firmware code in non-volatile memory is copied into RAM to be executed (for performance, or for other reasons) then the firmware program in RAM shall be protected from modification by software or shall complete its function before software starts. | Caliptra shall run on a dedicated microcontroller, isolated physically from access by other components in the system. | |
If Critical Platform Firmware uses RAM for temporary data storage, then this memory shall be protected from software running on the Platform until the data’s use is complete. | +If critical platform firmware uses RAM for temporary data storage, then this memory shall be protected from software running on the platform until the data’s use is complete. | Caliptra shall run on a dedicated microcontroller, isolated physically from access by other components in the system. | ||
Software shall not be able to interfere with the intended function of Critical Platform Firmware. For example, by denying execution, modifying the processor mode, or polluting caches. | +Software shall not be able to interfere with the intended function of critical platform firmware. For example, by denying execution, modifying the processor mode, or polluting caches. | Caliptra shall run on a dedicated microcontroller, isolated physically from access by other components in the system. In addition, the Caliptra subsystem begins execution before other firmware is allowed to run. | ||
4.2.4 | Critical data shall be modifiable only through the device itself or defined interfaces provided by device firmware. Examples of defined interfaces include proprietary or public application programming interfaces (APIs) used by the device’s firmware, or standards-based interfaces. Symbiont devices may rely on their host devices to meet this requirement. | -Caliptra receives firmware and configuration input only via defined interfaces within the SoC. See chapter on Mailboxes. | +Caliptra receives firmware and configuration input only via defined interfaces within the SoC. See the Mailboxes section. | |
4.2.1.3 | The authenticated update mechanism shall be capable of preventing unauthorized updates of the device firmware to an earlier authentic version that has a security weakness or would enable updates to a version with a known security weakness. | -Caliptra supports a mechanism for detecting and preventing execution of a prior firmware image that is no longer authorized. See chapter on Anti-rollback Support. | +Caliptra supports a mechanism for detecting and preventing execution of a prior firmware image that is no longer authorized. See the Anti-rollback Support section. | |
4.3.1 | -A successful attack which corrupts the active critical data or the firmware image, or subverts their protection mechanisms, shall not in and of itself result in a successful attack on the RTD or the information necessary to detect corruption of the firmware image. | -Caliptra shall verify the signature of any firmware it loads during each boot. If the signature verification fails, Caliptra shall notify the SoC that firmware recovery must be performed. Refer to [Error Reporting and Handling](#error-reporting-and-handling). | +A successful attack that corrupts the active critical data or the firmware image, or subverts their protection mechanisms, shall not in and of itself result in a successful attack on the RTD or the information necessary to detect corruption of the firmware image. | +Caliptra shall verify the signature of any firmware it loads during each boot. If the signature verification fails, Caliptra shall notify the SoC that firmware recovery must be performed. See the Error Reporting and Handling section. |
Verify integrity, using an approved digital signature algorithm or cryptographic hash, of device firmware code prior to execution of code outside the RTD. | -Caliptra shall perform digital signature verification of its FMC code, as well as that of the SoC Security Processor FMC before they are allowed to execute. | +Caliptra shall perform digital signature verification of its FMC code, as well as that of the SoC security processor FMC, before they are allowed to execute. | ||
If firmware corruption is detected, the RTD or CTD should be capable of starting a recovery process to restore the device firmware code back to an authentic version. | @@ -848,7 +845,7 @@ Table 8: NIST SP800-193 Requirements describes the NIST SP800-193 requirements t||||
The RTD or CTD should be capable of creating notifications of data corruption. | -Refer to [Error Reporting and Handling](#error-reporting-and-handling). | +See the Error Reporting and Handling section. | ||
The detection mechanism should be capable of logging events when data corruption is detected. | @@ -857,11 +854,11 @@ Table 8: NIST SP800-193 Requirements describes the NIST SP800-193 requirements t