| @@ -1,85 +1,26 @@ |
| 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/blob/64ed6c378cc955014f8ed7823d0a24d0b9f4a5d2/doc/caliptra_20/Caliptra.ocp" target="_blank">chipsalliance/Caliptra/doc/caliptra_20/Caliptra.ocp</a> @ <code>64ed6c3</code> |
| 2 | +📄 Source: <a href="https://github.com/chipsalliance/Caliptra/blob/64ed6c378cc955014f8ed7823d0a24d0b9f4a5d2/doc/Caliptra.md" target="_blank">chipsalliance/Caliptra/doc/Caliptra.md</a> @ <code>64ed6c3</code> |
| 3 | 3 | </div> |
| 4 | 4 | |
| 5 | | -# Revision table |
| 6 | | - |
| 7 | | -| Date | Revision | Description | |
| 8 | | -| --- | --- | --- | |
| 9 | | -| March 2024 | 1.0 | Initial release. | |
| 10 | | -| July 2025 | 2.0 | Major changes. Addition of Caliptra Subsystem. | |
| 11 | | - |
| 12 | | -# License |
| 13 | | - |
| 14 | | -## Open Web Foundation (OWF) CLA |
| 15 | | - |
| 16 | | -Contributions to this Specification are made under the terms and conditions set forth in **Modified Open Web Foundation Agreement 0.9 (OWFa 0.9)**. (As of October 16, 2024) (“Contribution License”) by: |
| 17 | | - |
| 18 | | -- AMD |
| 19 | | -- Google |
| 20 | | -- Microsoft |
| 21 | | -- Nvidia |
| 22 | | - |
| 23 | | -Usage of this Specification is governed by the terms and conditions set forth in **Modified OWFa 0.9 Final Specification Agreement (FSA)** (As of October 16, 2024) **(“Specification License”)**. |
| 24 | | - |
| 25 | | -You can review the applicable Specification License(s) referenced above by the contributors to this Specification on the OCP website at <https://www.opencompute.org/contributions/templates-agreements>. |
| 26 | | - |
| 27 | | -For actual executed copies of either agreement, please contact OCP directly. |
| 28 | | - |
| 29 | | -NOTWITHSTANDING THE FOREGOING LICENSES, THIS SPECIFICATION IS PROVIDED BY OCP "AS IS" AND OCP EXPRESSLY DISCLAIMS ANY WARRANTIES (EXPRESS, IMPLIED, OR OTHERWISE), INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, OR TITLE, RELATED TO THE SPECIFICATION. NOTICE IS HEREBY GIVEN, THAT OTHER RIGHTS NOT GRANTED AS SET FORTH ABOVE, INCLUDING WITHOUT LIMITATION, RIGHTS OF THIRD PARTIES WHO DID NOT EXECUTE THE ABOVE LICENSES, MAY BE IMPLICATED BY THE IMPLEMENTATION OF OR COMPLIANCE WITH THIS SPECIFICATION. OCP IS NOT RESPONSIBLE FOR IDENTIFYING RIGHTS FOR WHICH A LICENSE MAY BE REQUIRED IN ORDER TO IMPLEMENT THIS SPECIFICATION. THE ENTIRE RISK AS TO IMPLEMENTING OR OTHERWISE USING THE SPECIFICATION IS ASSUMED BY YOU. IN NO EVENT WILL OCP BE LIABLE TO YOU FOR ANY MONETARY DAMAGES WITH RESPECT TO ANY CLAIMS RELATED TO, OR ARISING OUT OF YOUR USE OF THIS SPECIFICATION, INCLUDING BUT NOT LIMITED TO ANY LIABILITY FOR LOST PROFITS OR ANY CONSEQUENTIAL, INCIDENTAL, INDIRECT, SPECIAL OR PUNITIVE DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS SPECIFICATION, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND EVEN IF OCP HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 30 | | - |
| 31 | | -<!--- |
| 32 | | -THE UPDATED DEFAULT CONTRIBUTOR LICENSE AGREEMENT (CLA) IS [OWFa 0.9](https://146a55aca6f00848c565-a7635525d40ac1c70300198708936b4e.ssl.cf1.rackcdn.com/images/ed0befaf86bee2568ad720ff4a9a554d1f4260f7.pdf). |
| 33 | | -PLEASE VERIFY THE CORRECT CLA/FSA IS USED AND EXECUTED FOR THIS CONTRIBUTION. |
| 34 | | - |
| 35 | | -# Compliance with OCP Tenets |
| 36 | | - |
| 37 | | -<!--- |
| 38 | | -Please describe how this Specification complies with the OCP tenets. |
| 39 | | -A full explanation of the OCP core tenets can be seen [here](https://146a55aca6f00848c565-a7635525d40ac1c70300198708936b4e.ssl.cf1.rackcdn.com/images/bf648bb75091907147e76846cad590f402660d2e.pdf). |
| 40 | | - |
| 41 | | -## Openness |
| 42 | | - |
| 43 | | -The Caliptra source for RTL and firmware are licensed using the Apache 2.0 license. See |
| 44 | | -[caliptra.io](https://caliptra.io) for links to all code repositories and companion specifications. |
| 45 | | - |
| 46 | | -## Efficiency |
| 47 | | - |
| 48 | | -Caliptra is used during the boot sequence and upgrade cycles, so it cannot yield a measurable impact on |
| 49 | | -system efficiency. |
| 50 | | - |
| 51 | | -## Impact |
| 52 | | - |
| 53 | | -Caliptra brings consistency and transparency to a foundational area of security and confidential compute. |
| 54 | | -Open source in-package RoTs have not been attempted before in the industry. It is challenging to align |
| 55 | | -partners, and it is challenging to align a common core of functionality everyone agrees upon in this space. |
| 56 | | -Caliptra breaches multiple traditional blockers and creates new ground for the industry and for open |
| 57 | | -ecosystems. |
| 58 | | - |
| 59 | | -## Scale |
| 60 | | - |
| 61 | | -Caliptra is a committed intercept for Google and Microsoft first party Cloud silicon. It is also a committed |
| 62 | | -intercept for AMD server silicon products. This scale covers both a significant portion of the Cloud market |
| 63 | | -as well as one of the two key CPU vendors in hyperscale and enterprise. |
| 64 | | - |
| 65 | | -## Sustainability |
| 66 | | - |
| 67 | | -Caliptra is synthesized to about a quarter of a square millimeter in modern tapeout processes. It boots |
| 68 | | -and generates a DICE chain in less than 200 milliseconds, executing at 400MHz. During the rest of |
| 69 | | -execution, the RISC-V core is idle waiting for mailbox requests. We anticipate millions of Caliptra |
| 70 | | -instances to consume mere Joules per year, which is conducive to sustainability. |
| 71 | | - |
| 72 | | -# Base specification |
| 73 | | - |
| 74 | | -## Introduction |
| 5 | + |
| 6 | + |
| 7 | +<p style="text-align: center;">Caliptra: A Datacenter System on a Chip (SoC) Root of Trust (RoT)</p> |
| 8 | + |
| 9 | +<p style="text-align: center;">Revision 2.1</p> |
| 10 | + |
| 11 | +<p style="text-align: center;">Version 0.1</p> |
| 12 | + |
| 13 | +<div style="page-break-after: always"></div> |
| 14 | + |
| 15 | +# Introduction |
| 75 | 16 | |
| 76 | 17 | Caliptra[^1] was originally created as part of the Open Compute Project ([OCP](https://www.opencompute.org/)). The major revisions of the Caliptra specifications are published at OCP. The evolving source code and documentation for Caliptra are in this repository within the [CHIPS Alliance Project](https://chipsalliance.org/), a Series of LF Projects, LLC. |
| 77 | 18 | |
| 78 | 19 | The objective of Caliptra is to define core RoT capabilities that must be implemented in the System on Chip (SoC) or ASIC of any device in a cloud platform. The collection of these RoT capabilities is referred to as the ***Silicon RoT Services (Silicon RoT).*** |
| 79 | 20 | |
| 80 | | -## Background |
| 21 | +<div style="page-break-after: always"></div> |
| 22 | + |
| 23 | +# Background |
| 81 | 24 | |
| 82 | 25 | The overall security posture of silicon devices depends on establishing a core root of trust (RoT) and chain of trust. The core root of trust and chain of trust must attest to the integrity of configuration and mutable code. |
| 83 | 26 | |
| @@ -91,7 +32,7 @@ |
| 91 | 32 | |
| 92 | 33 | The OCP Security WG specifications are making progress toward establishing the platform and peripheral security architecture [recommendations](https://docs.google.com/document/d/1-bfAF86cEKcn1guF-Qj2C2HhMM2oJ2njNGdHxZeetR0/edit#heading=h.pdkwdxyrhnco) that are necessary to attain the desired consistency in platform security orchestration. |
| 93 | 34 | |
| 94 | | -### Silicon RoT goals |
| 35 | +## Silicon RoT goals |
| 95 | 36 | |
| 96 | 37 | To drive agility of specification definition and to maximize applicability, the scope of Caliptra is deliberately minimalistic. This minimalist approach drives industry alignment, consistency, and faster adoption of foundational device security primitives. A well and narrowly defined specification maximizes architectural composability; reusability across CSPs, products, and vendors; and feasibility of open sourcing. |
| 97 | 38 | |
| @@ -137,28 +78,28 @@ |
| 137 | 78 | * Post manufacture test and initialization (OSAT) |
| 138 | 79 | * Certification |
| 139 | 80 | |
| 140 | | -### Use cases |
| 81 | +## Use cases |
| 141 | 82 | |
| 142 | 83 | The Silicon RoT use cases can be supported through the adoption of specific industry standards, and association and consortium specifications. For more information, see specific documents in [References](#references). |
| 143 | 84 | |
| 144 | 85 | In this version of the specification, the desired capabilities address the basics of supply chain security use cases. |
| 145 | 86 | |
| 146 | | -#### Supply chain security |
| 147 | | - |
| 148 | | -* **Mutable code integrity:** The objective is to prove the device is running genuine firmware such that the device manufacturer can vouch for its authenticity and integrity, and the device owner can ensure only authorized updates are applied to the device. This flow is aligned with *OCP Security WG: Ownership Transfer* and can be achieved with dual signature verification of equal imposition. |
| 87 | +### Supply chain security |
| 88 | + |
| 89 | +* **Mutable code integrity:** The objective is to prove the device is running genuine firmware such that the device manufacturer can vouch for its authenticity and integrity, and the device owner can ensure only authorized updates are applied to the device. This flow is aligned with [Reference 9](#ref-9) and can be achieved with dual signature verification of equal imposition. |
| 149 | 90 | * **Configuration and lifecycle management**: The objective is to allow the platform owner to securely configure the RoT capabilities, and to enable and authorize lifecycle state transitions of the SoC. |
| 150 | 91 | |
| 151 | | -#### DICE Protection Environment |
| 92 | +### DICE Protection Environment |
| 152 | 93 | |
| 153 | 94 | Caliptra implements the DICE Protection Environment (DPE) API, allowing it to derive and wield a DICE identity on behalf of other elements within the SoC. Use cases for this API include serving as a signing oracle for a Security Protocol and Data Model (SPDM) responder that is executing in a SoC application processor (in passive mode) or in the Manufacturer Control Unit (MCU in subsystem mode), as well as authentication to a discrete TPM device. |
| 154 | 95 | |
| 155 | | -## Industry standards and specifications |
| 96 | +# Industry standards and specifications |
| 156 | 97 | |
| 157 | 98 | This specification follows the industry standards and specifications listed in [References](#references). |
| 158 | 99 | |
| 159 | | -### NIST SP 800-193 Platform Firmware Resiliency |
| 160 | | - |
| 161 | | -Per [Platform Firmware Resiliency Guidelines](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-193.pdf), RoT subsystems are required to fulfill three principles: *protection, detection* and *recovery*. The associated RoT services are referred to as: |
| 100 | +## NIST SP 800-193 Platform Firmware Resiliency |
| 101 | + |
| 102 | +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: |
| 162 | 103 | |
| 163 | 104 | * **The Root of Trust for Update (RTU)** is responsible for authenticating firmware updates and critical data changes to support platform protection capabilities. |
| 164 | 105 | * **The Root of Trust for Detection (RTD)** is responsible for firmware and critical data corruption detection capabilities. |
| @@ -175,7 +116,7 @@ |
| 175 | 116 | * Cryptographically verify & measure its code and configuration |
| 176 | 117 | * Sign these measurements with a unique attestation key |
| 177 | 118 | * Report measurements to a host or external entity, which can further verify the authenticity and integrity of the device (also known as *attestation*) |
| 178 | | -* **Recovery** follows Open Compute Project Secure Recovery flows and Streaming Boot. (See [Section](#ocp-recovery-hw-specs) for links.) |
| 119 | +* **Recovery** follows Open Compute Project Secure Recovery flows and Streaming Boot. (FIXME: Add links to released specs; they are in draft mode now) |
| 179 | 120 | |
| 180 | 121 | **Measurements** and **Verification** include **Code** and **Configuration**. Configuration includes invasive capabilities that impact the user service level agreement (SLA) on confidentiality; for example, the enablement of debug capabilities that grant an operator access to raw, unencrypted registers for any tenant context. In order to measure and attest configuration, the Silicon RoT must be in control of the configuration. |
| 181 | 122 | |
| @@ -185,23 +126,23 @@ |
| 185 | 126 | |
| 186 | 127 | For further details about how Caliptra addresses NIST SP 800-193, see [Device Resilience](#device-resilience). |
| 187 | 128 | |
| 188 | | -### Trusted Computing Group (TCG) DICE Attestation |
| 189 | | - |
| 190 | | -In accordance with OCP Attestation specification [Attestation of System Components v1.0 Requirements and Recommendations](https://www.opencompute.org/documents/attestation-v1-0-20201104-pdf), devices must have a cryptographic identity for the endorsement of attestation quotes. The RTM implementation follows TCG DICE (for information, see [TCG DICE Layering Architecture Version 1.0 Revision 0.19](https://trustedcomputinggroup.org/wp-content/uploads/DICE-Layering-Architecture-r19_pub.pdf), [TCG DICE Attestation Architecture Version 1.00 Revision 0.23](https://trustedcomputinggroup.org/wp-content/uploads/DICE-Attestation-Architecture-r23-final.pdf), and [Hardware Requirements for a Device Identifier Composition Engine Version 1.0 Revision 0.91](https://trustedcomputinggroup.org/wp-content/uploads/Hardware-Requirements-for-a-Device-Identifier-Composition-Engine-Version-1.0-Revision-0.91_pub.pdf). One of the benefits of TCG DICE device identities is having renewable security. This renewability complements ownership transfer and circular economy. The new owner is not burdened with the identity of the previous owner, nor is the new owner burdened with trusting an irrevocable hardware identity certificate. This benefits the transferee, as their identities can be revoked through standard PKI mechanisms. DICE based certificates are fully compatible with Public Key Infrastructure (PKI), including full lifecycle management and PKI Certificate Revocation List (CRL). |
| 129 | +## Trusted Computing Group (TCG) DICE Attestation |
| 130 | + |
| 131 | +In accordance with OCP Attestation specification [Reference 8](#ref-8), devices must have a cryptographic identity for the endorsement of attestation quotes. The RTM implementation follows TCG DICE (for information, see [Reference 4](#ref-4), [Reference 5](#ref-5), and [Reference 6](#ref-6)). One of the benefits of TCG DICE device identities is having renewable security. This renewability complements ownership transfer and circular economy. The new owner is not burdened with the identity of the previous owner, nor is the new owner burdened with trusting an irrevocable hardware identity certificate. This benefits the transferee, as their identities can be revoked through standard PKI mechanisms. DICE based certificates are fully compatible with Public Key Infrastructure (PKI), including full lifecycle management and PKI Certificate Revocation List (CRL). |
| 191 | 132 | |
| 192 | 133 | Operational security during the manufacturing process is critical, to ensure the DICE entropy is securely initialized, certified, and registered. Operational security avoids any pilfering of this asset by eavesdroppers. Operational security is outside the scope of this specification. |
| 193 | 134 | |
| 194 | | -## Threat model |
| 135 | +# Threat model |
| 195 | 136 | |
| 196 | 137 | The Caliptra threat model describes attacker profiles, assets and attack surfaces, and paths to these assets based on attacker profiles. Subsections provide further details. |
| 197 | 138 | |
| 198 | 139 | Threat scenarios as comprehended by assets and possible attack paths are as complete as possible but focus on the worst case scenarios. Thus not every attack path to asset is captured in this threat model. |
| 199 | 140 | |
| 200 | | -### Attacker profiles |
| 141 | +## Attacker profiles |
| 201 | 142 | |
| 202 | 143 | An attacker profile is based on factors like the tools that are accessible to the attacker, the level of access to the target of evaluation, and expertise of the attacker to use these methods. These factors are described in the following tables. |
| 203 | 144 | |
| 204 | | -**Table: Tools accessible to attacker** {#tools-accessible-to-attacker} |
| 145 | +*Table 1: Tools accessible to attacker* |
| 205 | 146 | |
| 206 | 147 | | **Attack tools** | **Type of attack** | **Purpose and usage** | |
| 207 | 148 | | :--------- | :--------- | :--------- | |
| @@ -211,7 +152,7 @@ |
| 211 | 152 | | Microscopic imaging, reverse engineering, scanning electron microscope imaging, and focused ion beam (FIB) | Chip invasive attacks | Decapsulation, depackaging, and rebonding to probe the internals of the chip. | |
| 212 | 153 | |
| 213 | 154 | |
| 214 | | -**Table: Type of access to level of access** {#type-level-of-access} |
| 155 | +*Table 2: Type of access to level of access* |
| 215 | 156 | |
| 216 | 157 | | **Type of access** | **Levels of access** | **Attack paths available** | |
| 217 | 158 | | :--------- | :--------- | :--------- | |
| @@ -219,17 +160,18 @@ |
| 219 | 160 | | Remote access | Limited access for attacks with both privileged and unprivileged access rights. | Chip non-invasive attacks and network attacks | |
| 220 | 161 | |
| 221 | 162 | |
| 222 | | -**Table: Definition of expertise (JIL)** {#definition-of-expertise} |
| 223 | | - |
| 224 | | -| Proficiency level | Definition | Detailed definition | |
| 225 | | -| --- | --- | --- | |
| 226 | | -| **Expert** | Can use chip invasive, fault injections, side channels, and logical tools. Understands hardware and software in depth. Familiar with implementation: - Algorithms - Protocols - Hardware structures - Principle and security concepts | Developer-level knowledge of algorithms, protocols, hardware structure, and principles. Understands techniques and tools for attacks. | |
| 163 | +*Table 3: Definition of expertise (JIL)* |
| 164 | + |
| 165 | +| **Proficiency level** | **Definition** | **Detailed definition** | |
| 166 | +| :--------- | :--------- | :--------- | |
| 167 | +| **Expert** | Can use chip invasive, fault injections, side channels, and logical tools. Understands hardware and software in depth.<br>Familiar with implementation:<br> - Algorithms<br> - Protocols<br> - Hardware structures<br> - Principle and security concepts | Developer-level knowledge of algorithms, protocols, hardware structure, and principles. Understands techniques and tools for attacks. | |
| 227 | 168 | | **Proficient** | Can use fault injections, side channels, and logical tools. Has reasonable understanding of hardware and software. Familiar with security behavior. | Familiar with security behavior and classical attacks. | |
| 228 | 169 | | **Layperson** | No particular expertise. | No particular expertise. | |
| 229 | 170 | |
| 230 | | -### Types of attacks |
| 231 | | - |
| 232 | | -#### Physical attacks |
| 171 | + |
| 172 | +## Types of attacks |
| 173 | + |
| 174 | +### Physical attacks |
| 233 | 175 | |
| 234 | 176 | A physical attacker has full access to the electrical and physical components. This includes access to interfaces, connectors, and ports of the SoC/ASIC in which Caliptra is integrated without restriction. |
| 235 | 177 | |
| @@ -240,49 +182,53 @@ |
| 240 | 182 | * Power and electromagnetic analysis attacks |
| 241 | 183 | * *Counter measurements - as strong recommendation* |
| 242 | 184 | |
| 243 | | -**Table: Attack types** {#attack-types} |
| 244 | | - |
| 245 | | -| Attack | Description | Threat model scope | |
| 246 | | -| --- | --- | --- | |
| 247 | | -| Electromagnetic – passive | Attacker observes the electromagnetic power spectrum and signals radiated from the product. | - Includes all attacks at all frequency ranges, including radio frequencies, infrared, optical, and ultraviolet. - Excludes attacks that require removing the package lid. | |
| 248 | | -| Electromagnetic – active | Attacker directs electromagnetic radiation at the product or portions of the product. | - Includes all attacks at all frequency ranges, including radio frequencies, infrared, optical, and ultraviolet. - Excludes attacks that require removing the package lid. | |
| 249 | | -| Electric – passive | Attacker probes the external pins of the package and observes electrical signals and characteristics including capacitance, current, and voltage signal. | - Includes both analog attacks and digital signal attacks. - Excludes attacks that require removing the package lid. | |
| 250 | | -| Electric – active | Attacker alters the electrical signal or characteristics of external pins. | - Includes both analog attacks and digital signal attacks. - Excludes attacks that require removing the package lid. | |
| 251 | | -| Temperature – passive | Attacker observes the temperature of the product or portions of the product. | - Excludes attacks that require removing the package lid. | |
| 252 | | -| Temperature – active | Attacker applies external heat sources or sinks to alter the temperature of the product, possibly in a rapid fashion. | - Includes all temperature ranges (for example, pouring liquid nitrogen over the package or heating the package to above 100 C). - Excludes attacks that require removing the package lid. | |
| 253 | | -| Sound - passive | Attacker observes the sounds emitted by the product. | - Includes all frequencies. - Excludes attacks that require removing the package lid. | |
| 254 | | - |
| 255 | | -**Table: Logical attacks** {#logical-attacks} |
| 256 | | - |
| 257 | | -| Attack | Description | Threat model scope | |
| 258 | | -| --- | --- | --- | |
| 185 | +*Table 4: Attack types* |
| 186 | + |
| 187 | +| **Attack** | **Description** | **Threat model scope** | |
| 188 | +| :--------- | :--------- | :--------- | |
| 189 | +| Electromagnetic – passive | Attacker observes the electromagnetic power spectrum and signals radiated from the product. | - Includes all attacks at all frequency ranges, including radio frequencies, infrared, optical, and ultraviolet.<br> - Excludes attacks that require removing the package lid. | |
| 190 | +| Electromagnetic – active | Attacker directs electromagnetic radiation at the product or portions of the product. | - Includes all attacks at all frequency ranges, including radio frequencies, infrared, optical, and ultraviolet.<br> - Excludes attacks that require removing the package lid. | |
| 191 | +| Electric – passive | Attacker probes the external pins of the package and observes electrical signals and characteristics including capacitance, current, and voltage signal. | - Includes both analog attacks and digital signal attacks.<br> - Excludes attacks that require removing the package lid. | |
| 192 | +| Electric – active | Attacker alters the electrical signal or characteristics of external pins. | - Includes both analog attacks and digital signal attacks.<br> - Excludes attacks that require removing the package lid. | |
| 193 | +| Temperature – passive | Attacker observes the temperature of the product or portions of the product. | Excludes attacks that require removing the package lid. | |
| 194 | +| Temperature – active | Attacker applies external heat sources or sinks to alter the temperature of the product, possibly in a rapid fashion. | - Includes all temperature ranges (for example, pouring liquid nitrogen over the package or heating the package to above 100 C).<br> - Excludes attacks that require removing the package lid. | |
| 195 | +| Sound - passive | Attacker observes the sounds emitted by the product. | - Includes all frequencies.<br> - Excludes attacks that require removing the package lid. | |
| 196 | + |
| 197 | + |
| 198 | +*Table 5: Logical attacks* |
| 199 | + |
| 200 | +| **Attack** | **Description** | **Threat model scope** | |
| 201 | +| :--------- | :--------- | :--------- | |
| 259 | 202 | | Debug and register interfaces | Manipulation of externally accessible registers of Caliptra. | Includes all buses that are accessible to components external to Caliptra, including JTAG. | |
| 260 | 203 | | Software interfaces | Attacker invokes software interfaces that are exposed by Caliptra to external components. | Includes all externally exposed software interfaces from both non-RoT firmware as well as interfaces accessed by external IP blocks. Includes exploiting both design and implementation flaws. For high value assets only (see next subsection), the attacker is assumed to fully control all mutable code of the SoC, including privileged Caliptra mutable code. | |
| 261 | 204 | | Side channel - timing | Attacker observes the elapsed time of different sensitive operations. | Includes attacks where the attacker actively stimulates the sensitive operations while timing. | |
| 262 | 205 | | Cryptographic analysis | Attacker observes plaintext, ciphertext, related data, or immediate values in cryptography to overcome cryptographic controls. | Includes all practical cryptanalysis attacks. Assumes NIST-unapproved algorithms provide no security (for example, SHA-1, Single DES, ChaCha20). Assumes any cryptographic algorithm that provides less than 128 bits of security (as determined by NIST SP 800-57) provides no security. | |
| 263 | 206 | |
| 264 | | -#### Trust boundaries |
| 207 | + |
| 208 | +### Trust boundaries |
| 265 | 209 | |
| 266 | 210 | The following figure shows trust boundaries for the discussion of threat modeling. SoCs based on Caliptra are expected to have Caliptra as silicon RoT, and are expected to have a platform or SoC security engine to orchestrate SoC security needs for the rest of the SoC. |
| 267 | 211 | |
| 268 | 212 | Trust levels of Caliptra and the SoC security engine are not hierarchical. These two entities are responsible for different security aspects of the chip. |
| 269 | 213 | |
| 270 | | -{#caliptra-trust-boundaries} |
| 271 | | - |
| 272 | | -#### Caliptra interactions |
| 214 | +*Figure 1: Caliptra trust boundaries* |
| 215 | + |
| 216 | + |
| 217 | + |
| 218 | +### Caliptra interactions |
| 273 | 219 | |
| 274 | 220 | The Caliptra Core blocks consume the Tc and Tcw trust level components. This boundary includes crypto accelerators, hardware key sequencer, key vault, Caliptra microcontroller, ROM, and subsystem interconnects. The Caliptra Core provides deterministic Caliptra behavior. Caliptra Core interacts with components in the Tse and Trs trust levels; while Caliptra Subsystem abosrbs the Tse functions. |
| 275 | 221 | |
| 276 | | -#### Caliptra assets and threats {#assets} |
| 222 | +### <a id="assets"></a>Caliptra assets and threats |
| 277 | 223 | |
| 278 | 224 | 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. |
| 279 | 225 | |
| 280 | 226 | 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. |
| 281 | 227 | |
| 282 | | -**Table: Assets** {#assets} |
| 228 | +*Table 6: Assets* |
| 283 | 229 | |
| 284 | 230 | | Asset category | Asset | Security property | Attack profile | Attack path | Mitigation | |
| 285 | | -| --- | --- | --- | --- | --- | --- | |
| 231 | +| :------------- | :--------- | :---------------- | :------------- | :---------- | :--------- | |
| 286 | 232 | | Fuse/OTP high value secrets | UDS Seed | Confidentiality and integrity | Expert | Malicious manufacturing spoofing of UDS Seeds | UDS obfuscation with class RTL key | |
| 287 | 233 | | Fuse/OTP high value secrets | UDS Seed | Confidentiality and integrity | Expert | Invasive attack (fuse analysis) | Shield fuse IP | |
| 288 | 234 | | Fuse/OTP high value secrets | UDS Seed | Confidentiality and integrity | Expert | Boot path tampering while retrieving UDS values | UDS obfuscation with class RTL key | |
| @@ -291,36 +237,40 @@ |
| 291 | 237 | | Fuse/OTP high value secrets | Field entropy | Confidentiality and integrity | Expert | Invasive attack (fuse analysis) | Shield fuse IP | |
| 292 | 238 | | Fuse/OTP high value secrets | Field entropy | Confidentiality and integrity | Expert | Boot path tampering while retrieving field entropy values | Field entropy obfuscation with class RTL key | |
| 293 | 239 | | Fuse/OTP high value secrets | Field entropy | Confidentiality and integrity | Expert | Attempting to derive die specific keys by knowing field entropy | Confine unobfuscated field entropy and subsequent derivations to key vault | |
| 294 | | -| Fuse/OTP high value secrets | FW authentication keys | Integrity | Proficient | Glitching | 1. Redundant decision making on critical code execution 2. Error check before consuming values from fuses 3. Environmental monitoring and protection | |
| 240 | +| Fuse/OTP high value secrets | FW authentication keys | Integrity | Proficient | Glitching | 1. Redundant decision making on critical code execution<br>2. Error check before consuming values from fuses<br>3. Environmental monitoring and protection | |
| 295 | 241 | | Fuse/OTP high value secrets | Versioning information from fuses | Integrity | Proficient | Glitching | Environmental monitoring and protection | |
| 296 | | -| Fuse/OTP high value secrets | IDEVID CERT chain | Integrity | Proficient | Glitching | 1. Environmental monitoring and protection 2. Error check before consuming values from fuse in various ways | |
| 297 | | -| Die unique assets | UDS (802.1AR Unique Device Secret) | Confidentiality and integrity | Proficient | 1. Software reading actual secrets 2. Side channel attack to infer secrets | 1. Secrets locked in key vault, not readable by software 2. SCA protections | |
| 298 | | -| Die unique assets | CDI~n~ (DICE compound device identifier for Layer n) | Confidentiality and integrity | Proficient | 1. Software reading actual secrets 2. Side channel attack to infer secrets | 1. Secrets locked in key vault, not readable by software 2. SCA protections | |
| 299 | | -| Die unique assets | IDevID~Priv~ | Confidentiality and integrity | Proficient | 1. Software reading actual secrets 2. Side channel attack to infer secrets | 1. Secrets locked in key vault, not readable by software 2. SCA protections | |
| 300 | | -| Die unique assets | LDevID~Priv~ | Confidentiality and integrity | Proficient | 1. Software reading actual secrets 2. Side channel attack to infer secrets | 1. Secrets locked in key vault, not readable by software 2. SCA protections | |
| 301 | | -| Die unique assets | Obfuscation key | Confidentiality and integrity | Proficient | 1. Software reading actual secrets 2. Side channel attack to infer secrets | 1. Secrets locked in key vault, not readable by software 2. SCA protections | |
| 302 | | -| Die unique assets | AliasFMC_Key~Priv~ | Confidentiality and integrity | Proficient | 1. Software reading actual secrets 2. Side channel attack to infer secrets | 1. Secrets locked in key vault, not readable by software 2. SCA protections | |
| 303 | | -| Die unique assets | AliasRT_Key~Priv~ | Confidentiality and integrity | Proficient | 1. Software reading actual secrets 2. Side channel attack to infer secrets | 1. Secrets locked in key vault, not readable by software 2. SCA protections | |
| 304 | | -| Root of trust execution | ROM FW | Integrity | Proficient | Glitching | 1. Redundant decision making on critical code execution 2. Environmental monitoring and protection | |
| 242 | +| Fuse/OTP high value secrets | IDEVID CERT chain | Integrity | Proficient | Glitching | 1. Environmental monitoring and protection<br>2. Error check before consuming values from fuse in various ways | |
| 243 | +| Fuse/OTP high value secrets | OCP L.O.C.K. HEK RATCHET SEED | Confidentiality | Proficient | 1. Glitching<br>2. Software writing to modify the valid seed | 1. Consuming it after obfuscating with class RTL key<br>2. Environmental monitoring and protection<br>3. Error check before consuming values from fuse in various ways | |
| 244 | +| Die unique assets | UDS (802.1AR Unique Device Secret) | Confidentiality and integrity | Proficient | 1. Software reading actual secrets<br>2. Side channel attack to infer secret | 1. Secrets locked in key vault, not readable by software<br>2. SCA protections | |
| 245 | +| Die unique assets | CDI<sub>n</sub> (DICE compound device identifier for Layer n) | Confidentiality and integrity | Proficient | 1. Software reading actual secrets<br>2. Side channel attack to infer secret | 1. Secrets locked in key vault, not readable by software<br>2. SCA protections | |
| 246 | +| Die unique assets | IDevID<sub>Priv</sub> | Confidentiality and integrity | Proficient | 1. Software reading actual secrets<br>2. Side channel attack to infer secret | 1. Secrets locked in key vault, not readable by software<br>2. SCA protections | |
| 247 | +| Die unique assets | LDevID<sub>Priv</sub> | Confidentiality and integrity | Proficient | 1. Software reading actual secrets<br>2. Side channel attack to infer secret | 1. Secrets locked in key vault, not readable by software<br>2. SCA protections | |
| 248 | +| Die unique assets | Obfuscation key | Confidentiality and integrity | Proficient | 1. Software reading actual secrets<br>2. Side channel attack to infer secret | 1. Secrets locked in key vault, not readable by software<br>2. SCA protections | |
| 249 | +| Die unique assets | AliasFMC_Key<sub>Priv</sub> | Confidentiality and integrity | Proficient | 1. Software reading actual secrets<br>2. Side channel attack to infer secret | 1. Secrets locked in key vault, not readable by software<br>2. SCA protections | |
| 250 | +| Die unique assets | AliasRT_Key<sub>Priv</sub> | Confidentiality and integrity | Proficient | 1. Software reading actual secrets<br>2. Side channel attack to infer secret | 1. Secrets locked in key vault, not readable by software<br>2. SCA protections | |
| 251 | +| Root of trust execution | ROM FW | Integrity | Proficient | Glitching | 1. Redundant decision making on critical code execution<br>2. Environmental monitoring and protection | |
| 305 | 252 | | Root of trust execution | Execution unauthorized runtime FW | Authenticity and integrity | Proficient | Modify boot media | Authenticity and integrity check using PKI DSA upon power on | |
| 306 | 253 | | Root of trust execution | Execution unauthorized runtime FW | Authenticity and integrity | Proficient | Arbitrary payload pushed into execution | Authenticity and integrity check using PKI DSA during software updates and power on | |
| 307 | | -| Root of trust execution | Rollback Attack | Versioning | Proficient | 1. Modify boot media to host older versions 2. Bypass version check during boot | 1. Authenticity and integrity check using PKI DSA upon power on 2. Failproof, audited boot code implementation responsible for loading images | |
| 308 | | -| Root of trust execution | Control flow | Integrity and confidentiality if applicable | Proficient | 1. Return and jump addresses manipulation 2. Return values and errors tampering 3. Stack overflow 4. Buffer overflows 5. Privilege escalations and hijacking | 1. Various control flow integrity measures 2. Secure coding practices and auditing implementation | |
| 309 | | -| Boot measurements protected by Caliptra | Boot measurements that Caliptra gathers, stores, and reports | Integrity | Expert | 1. Manipulate measurements AiTM while in transit to Caliptra 2. SoC sends manipulated measurements to Caliptra || |
| 254 | +| Root of trust execution | Rollback Attack | Versioning | Proficient | 1. Modify boot media to host older versions<br>2. Bypass version check during boot | 1. Authenticity and integrity check using PKI DSA upon power on<br>2. Failproof, audited boot code implementation responsible for loading images | |
| 255 | +| Root of trust execution | Control flow | Integrity and confidentiality if applicable | Proficient | 1. Return and jump addresses manipulation<br>2. Return values and errors tampering <br>3. Stack overflow <br>4. Buffer overflows <br>5. Privilege escalations and hijacking | 1. Various control flow integrity measures<br> 2. Secure coding practices and auditing implementation | |
| 256 | +| Boot measurements protected by Caliptra | Boot measurements that Caliptra gathers, stores, and reports | Integrity | Expert | 1. Manipulate measurements AiTM while in transit to Caliptra <br>2. SoC sends manipulated measurements to Caliptra || |
| 310 | 257 | | Caliptra inputs | Security state | Integrity | Proficient | Glitching | Environmental monitoring and protection | |
| 311 | 258 | | Caliptra inputs | Mode selection (Boot Media Integrated and dependent selections) | Integrity | Proficient | Glitching | Environmental monitoring and protection | |
| 312 | 259 | | Caliptra inputs | AXI_USER attribute | Integrity | Proficient | Glitching | Environmental monitoring and protection | |
| 313 | | -| Caliptra inputs | Design-for-Test (DFT) and Design-for-Debug (DFD) | Integrity | Proficient | 1. Attempt to manipulate RoT execution via DFT or DFD flows to flows that are not plan-of-record 2. Attempt to retrieve device secrets via DFT or DFD flows when product is field-deployed 3. Attempt to retrieve device secrets via DFT or DFD flows while the product is being developed and debugged | Implement scan mode and debug unlock management within Caliptra with the required SoC support | |
| 314 | | - |
| 315 | | -## High level architecture |
| 260 | +| Caliptra inputs | Design-for-Test (DFT) and Design-for-Debug (DFD) | Integrity | Proficient | 1. Attempt to manipulate RoT execution via DFT or DFD flows to flows that are not plan-of-record<br>2. Attempt to retrieve device secrets via DFT or DFD flows when product is field-deployed<br>3. Attempt to retrieve device secrets via DFT or DFD flows while the product is being developed and debugged | Implement scan mode and debug unlock management within Caliptra with the required SoC support | |
| 261 | + |
| 262 | + |
| 263 | +# High level architecture |
| 316 | 264 | |
| 317 | 265 | The following figure shows the basic high-level blocks of Caliptra. |
| 318 | 266 | |
| 319 | | -{#high-level-blocks} |
| 267 | +*Figure 2: Caliptra high level blocks* |
| 268 | + |
| 269 | + |
| 320 | 270 | |
| 321 | 271 | See the [hardware section](#hardware) for a detailed discussion. |
| 322 | 272 | |
| 323 | | -From Caliptra 2.x onwards, Caliptra introduces two modes of operation. **Passive** mode which was supported in 1.x architecture and **Subsystem** mode. Fundamental difference between passive mode and subsystem mode is that in the subsystem mode Caliptra is the RoT for the SoC and provides streaming boot, secure boot and attestation. In Subsystem mode, Caliptra also provides various crypto API services such as encryption/decryption of SoC FWs, Key releases, Key wraps, hashing etc. to name a few. Please see [Caliptra runtime cryptographic mailbox commands documentation](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/runtime/README.md#cryptographic-mailbox-commands-new-in-20) for more details. |
| 273 | +From Caliptra 2.x onwards, Caliptra introduces two modes of operation. **Passive** mode which was supported in 1.x architecture and **Subsystem** mode. Fundamental difference between passive mode and subsystem mode is that in the subsystem mode Caliptra is the RoT for the SoC and provides streaming boot, secure boot and attestation. In Subsystem mode, Caliptra also provides various crypto API services such as encryption/decryption of SoC FWs, Key releases, Key wraps, hashing etc. to name a few. Please see Caliptra subsystem mode Crypto API section for more details (**FIXME**: section name & details). |
| 324 | 274 | |
| 325 | 275 | **Passive Mode High Level Flow** |
| 326 | 276 | |
| @@ -340,11 +290,14 @@ |
| 340 | 290 | |
| 341 | 291 | See [Error Reporting and Handling](#error-reporting-and-handling) for details about Caliptra and SoC firmware load and verification error handling. |
| 342 | 292 | |
| 343 | | -{#passive-boot-flow} |
| 293 | +*Figure 3: Passive Caliptra boot flow* |
| 294 | + |
| 295 | + |
| 344 | 296 | |
| 345 | 297 | **Subsystem Mode Boot Flow** |
| 346 | 298 | |
| 347 | 299 | MCU (Manufacturer Control Unit), that is holds platform & SoC specific FW and Caliptra are among the first microcontrollers taken out of reset by the power-on reset logic. Caliptra is responsible for the start of the firmware chain-of-trust with the immutable component of the MCU ROM. After the Caliptra ROM completes initialization, it provides a "stash measurement" API and callback signals for MCU ROM (subsystem mode) to proceed with the boot process. Caliptra ROM supports stashing of at most eight measurements prior to the boot of Caliptra RT firmware. Then Caliptra FW is loaded through OCP streaming boot flow. The OCP streaming boot flow uses an I3C controller with commands defined by the OCP Recovery specification. This controller constitutes the streaming boot interface in the boot flow below. Any security-sensitive code (eg. PLL programming) or configuration (eg. Fuse based Patching) loaded by the MCU prior to Caliptra firmware boot must be stashed within Caliptra. If the MCU exceeds Caliptra ROM's measurement stash capacity, attestation must be disabled until the next cold reset. |
| 300 | + |
| 348 | 301 | |
| 349 | 302 | Note: This is extremely high level flow, please see the Subsystem Mode Section below for next level specifics. |
| 350 | 303 | |
| @@ -360,34 +313,37 @@ |
| 360 | 313 | |
| 361 | 314 | **FIXME: ADD a pic** |
| 362 | 315 | |
| 363 | | -### Identity |
| 316 | + |
| 317 | +## Identity |
| 364 | 318 | |
| 365 | 319 | Caliptra must provide its runtime (RT) code with a cryptographic identity in accordance with the TCG DICE specification. This identity must be rooted in ROM, and provides an attestation over the security state of the RTM as well as the code that the RTM booted. |
| 366 | 320 | |
| 367 | 321 | To ensure quantum-resistant RTM, each certificate includes a dual signatures based on ECC Secp384r1 and PQC MLDSA-87. |
| 368 | 322 | |
| 369 | | -{#dice-key-gen} |
| 370 | | - |
| 371 | | -#### UDS |
| 323 | +*Figure 4: DICE Cert/Key generation* |
| 324 | + |
| 325 | + |
| 326 | + |
| 327 | +### UDS |
| 372 | 328 | |
| 373 | 329 | A combination of mask ROM and HW macros must implement the DICE key derivation and power-on latch, hiding the UDS seed and only making the CDI-derived signing key 'handle' visible to ROM. Real UDS will only be calculated during the cold boot in hardware, used for CDI derivation and immediately gets cleared. |
| 374 | 330 | |
| 375 | 331 | The Caliptra UDS seed is stored as ciphertext in fuses, deobfuscated only on cold boot using a obfuscation key[^2] known only to the Caliptra Hardware. Once read by Caliptra HW at boot, the unobfuscated UDS is then used to derive the IDevID identity and immediately cleared by hardware. |
| 376 | 332 | |
| 377 | | -#### IDevID key |
| 333 | +### IDevID key |
| 378 | 334 | |
| 379 | 335 | Caliptra's IDevID key is a hardware identity generated by Caliptra ROM during manufacturing. This key "handle" must be solely wielded by Caliptra ROM, and shall never be exposed externally at any phase of the Caliptra lifecycle. IDevID is used to endorse LDevID. Caliptra supports both classic and post-quantum algorithms for endorsement based on ECDSA Secp384r1 and PQC MLDSA-87, respectively. |
| 380 | | -The [IDevID certificate](#idevid-certificate) is endorsed by the vendor’s provisioning CA (pCA) that is implemented via a HSM appliance connected to High Volume Manufacturing (HVM) flows (see provisioning CA in [Attestation of System Components v1.0 Requirements and Recommendations](https://www.opencompute.org/documents/attestation-v1-0-20201104-pdf)). |
| 381 | | - |
| 382 | | -See [Provisioning IDevID During Manufacturing](#sec:idev-during-manufacturing) for further details on IDevID provisioning. |
| 383 | | - |
| 384 | | -#### LDevID key |
| 336 | +The [IDevID certificate](#idevid-certificate) is endorsed by the vendor’s provisioning CA (pCA) that is implemented via a HSM appliance connected to High Volume Manufacturing (HVM) flows (see provisioning CA in [Reference 8](#ref-8)). |
| 337 | + |
| 338 | +See [Provisioning IDevID During Manufacturing](#provisioning-idevid-during-manufacturing) for further details on IDevID provisioning. |
| 339 | + |
| 340 | +### LDevID key |
| 385 | 341 | |
| 386 | 342 | Caliptra shall support field-programmable entropy, which factors into the device's LDevID identity. The [LDevID certificate](#ldevid-certificate) is endorsed by IDevID and in turn endorses the FMC alias key. Caliptra supports both classic and post-quantum algorithms for endorsement based on ECDSA Secp384r1 and PQC MLDSA-87, respectively. |
| 387 | 343 | |
| 388 | | -Caliptra's field-programmable entropy shall consist of four 8-byte slots. All slots are used to derive LDevID. An owner may decide to program as few or as many slots as they wish. Upon programming new entropy, on the next reset the device begins wielding its fresh LDevID. Owners need to validate the new LDevID by using IDevID. |
| 389 | | - |
| 390 | | -#### Commentary: threat analysis |
| 344 | +Caliptra's field-programmable entropy shall consist of two 16-byte slots. All slots are used to derive LDevID. An owner may decide to program as few or as many slots as they wish. Upon programming new entropy, on the next reset the device begins wielding its fresh LDevID. Owners need to validate the new LDevID by using IDevID. |
| 345 | + |
| 346 | +### Commentary: threat analysis |
| 391 | 347 | |
| 392 | 348 | An ideal IDevID has the following properties: |
| 393 | 349 | |
| @@ -427,51 +383,52 @@ |
| 427 | 383 | |
| 428 | 384 | Owners are not required to program field entropy. Caliptra generates LDevID from the value of the field entropy fuses, which could be all zeroes or ones. Caliptra LDevID derivation descends from UDS so that LDevID properties are no worse than IDevID. Field entropy is expected to be stored in fuses to achieve an equivalent physical attack barrier to UDS. |
| 429 | 385 | |
| 430 | | -It is the responsibility of the owner or the user to identify the certificate they wish to trust, and to potentially endorse with their own certificate authority: pCA, IDevID, LDevID, or Alias~FMC~. |
| 431 | | - |
| 432 | | -#### FMC alias key |
| 433 | | - |
| 434 | | -The LDevID CDI is mixed with a hash of FMC, as well as the security state of the device, via a FIPS-compliant HMAC, to produce CDI~FMC~. ROM uses CDI~FMC~ to derive the Alias~FMC~ keypair. ROM wields LDevID to issue a certificate for Alias. The [Alias~FMC~ certificate](#aliasfmc-certificate) includes measurements of the security state and FMC. ROM makes CDI~FMC~, Alias~FMC~, and its certificate, available to FMC. |
| 435 | | - |
| 436 | | -FMC mixes CDI~FMC~ with a hash of runtime firmware to produce CDI~RT~. FMC uses CDI~RT~ to derive the Alias~RT~ alias keypair. FMC wields Alias~FMC~ to issue a certificate for Alias~RT~. This alias certificate includes measurements of runtime firmware. FMC makes CDI~RT~, Alias~RT~, and its certificate, available to application firmware, while withholding CDI~FMC~ and Alias~FMC~. |
| 437 | | - |
| 438 | | -#### Security state |
| 386 | +It is the responsibility of the owner or the user to identify the certificate they wish to trust, and to potentially endorse with their own certificate authority: pCA, IDevID, LDevID, or Alias<sub>FMC</sub>. |
| 387 | + |
| 388 | +### FMC alias key |
| 389 | + |
| 390 | +The LDevID CDI is mixed with a hash of FMC, as well as the security state of the device, via a FIPS-compliant HMAC, to produce CDI<sub>FMC</sub>. ROM uses CDI<sub>FMC</sub> to derive the Alias<sub>FMC</sub> keypair. ROM wields LDevID to issue a certificate for Alias. The [Alias<sub>FMC</sub> certificate](#aliasfmc-certificate) includes measurements of the security state and FMC. ROM makes CDI<sub>FMC</sub>, Alias<sub>FMC</sub>, and its certificate, available to FMC. |
| 391 | + |
| 392 | +FMC mixes CDI<sub>FMC</sub> with a hash of runtime firmware to produce CDI<sub>RT</sub>. FMC uses CDI<sub>RT</sub> to derive the Alias<sub>RT</sub> alias keypair. FMC wields Alias<sub>FMC</sub> to issue a certificate for Alias<sub>RT</sub>. This alias certificate includes measurements of runtime firmware. FMC makes CDI<sub>RT</sub>, Alias<sub>RT</sub>, and its certificate, available to application firmware, while withholding CDI<sub>FMC</sub> and Alias<sub>FMC</sub>. |
| 393 | + |
| 394 | +### Security state |
| 439 | 395 | |
| 440 | 396 | Devices may support features like debug unlock, DFT, or DFD flows that globally affect SoC state. These features, when enabled, significantly alter the security state of the device. The configuration of these features shall be captured in the device's DICE identity. The security state shall be captured as an input to the FMC's CDI, and represented within the FMC's alias certificate. |
| 441 | 397 | |
| 442 | | -#### Owner authorization |
| 398 | +### Owner authorization |
| 443 | 399 | |
| 444 | 400 | Caliptra firmware shall be signed by the vendor. In addition, this firmware shall also be signed by an owner key. Caliptra must extract the owner's public key from the firmware image during cold boot, and latch the owner key into Caliptra's RAM for the remainder of its uptime[^3]. Caliptra then uses both the vendor key and owner key to verify hitless firmware updates. |
| 445 | 401 | |
| 446 | | -Caliptra shall attest to the value of the owner key, enabling external verifiers to ensure that the correct owner key was provisioned into the device. To perform this attestation, Caliptra includes the owner key as an input to the FMC's CDI (as part of "other attributes" from [Figure](#dice-key-gen) above), and represents it within the FMC's alias certificate. |
| 402 | +Caliptra shall attest to the value of the owner key, enabling external verifiers to ensure that the correct owner key was provisioned into the device. To perform this attestation, Caliptra includes the owner key as an input to the FMC's CDI (as part of "other attributes" from Figure 4 above), and represents it within the FMC's alias certificate. |
| 447 | 403 | |
| 448 | 404 | The SoC may support a fuse bank for representing the hash of the owner's public key. If the SoC reports this value to Caliptra, Caliptra refuses to boot firmware unless the firmware was dual-signed by the key reported by SoC ROM's fuse registers. |
| 449 | 405 | |
| 450 | 406 | The owner key, when represented in fuses or in the FMC's alias certificate, is a SHA384 hash of a structure that contains a list of owner public keys. This supports key rotation. |
| 451 | 407 | |
| 452 | | -### Provisioning UDS during Manufacturing (Subsystem Mode) |
| 408 | +## Provisioning UDS during Manufacturing (Subsystem Mode) |
| 453 | 409 | **Note:** In passive mode, SoC follows the same flows/restrictions as Caliptra 1.x |
| 454 | 410 | |
| 455 | | -{#subsystem-uds-manufacturing-flow} |
| 456 | | - |
| 457 | | -There are two ways of generating a UDS seed: |
| 458 | | - |
| 459 | | -1. Use the internal TRNG to directly generate a 512-bit random number. |
| 460 | | -2. Use an entity external to Caliptra such as an HSM or SoC-specific methodology to produce the 512-bit random number for the UDS seed that is pushed into the fuse controller (same as Caliptra 1.0). |
| 411 | + |
| 412 | + |
| 413 | +*Figure 6: Subsystem Mode: UDS manufacturing flow* |
| 414 | + |
| 415 | +There are three ways of generating a UDS_SEED |
| 416 | +Use the internal TRNG to directly generate a 384-bit random number. |
| 417 | +Use an entity external to Caliptra such as an HSM or SoC-specific methodology to produce UDS-seed 384-bit random number that is pushed into the fuse controller (same as Caliptra 1.0). |
| 418 | +Combine the internal TRNG output with a Manufacturing time provided value to produce a 384-bit output. |
| 461 | 419 | |
| 462 | 420 | **UDS Manufacturing** |
| 463 | | - |
| 464 | | -To use the internal TRNG to generate the UDS seed during manufacturing in subsystem mode: |
| 465 | | - |
| 466 | | -1. When SoC life cycle is in MANUFACTURING MODE, set the manufacturing service register bit [SS_DBG_MANUF_SERVICE_REG_REQ[2]](https://chipsalliance.github.io/caliptra-rtl/v2_0/internal-regs/?p=clp.soc_ifc_reg.SS_DBG_MANUF_SERVICE_REG_REQ#UDS_PROGRAM_REQ.desc) through JTAG to request the UDS seed programming flow. |
| 467 | | -2. Caliptra ROM will sample this bit on power up; when this bit is set, Caliptra ROM rechecks that the life cycle state is manufacturing mode and reads the iTRNG for a 512-bit value. |
| 468 | | -3. Caliptra ROM writes the 512-bit value to the address available through registers named SS_UDS_SEED_BASE_ADDR_L and SS_UDS_SEED_BASE_ADDR_H (which are strapped by SoC at integration time) by using Caliptra's DMA. |
| 469 | | -4. Caliptra ROM sets the corresponding status bit in SS_DBG_MANUF_SERVICE_REG_RSP to indicate the flow completion. |
| 470 | | -5. Manufacturing flow will poll/read this bit and then do the fuse burning flow as specified by the fuse controller spec and SoC-specific VR methodologies (e.g., fuse macro voltage elevation flows). |
| 471 | | - |
| 472 | | -### Provisioning IDevID during manufacturing {#idev-during-manufacturing} |
| 473 | | - |
| 474 | | -{#device-manufacturing-identity-flow} |
| 421 | +1. When SoC life cycle is in MANUFACTURING MODE, manufacturing service register bit [CPTRA_DBG_MANUF_SERVICE_REG[2]] is set to request for UDS seed programming flow. |
| 422 | +2. Caliptra ROM will sample this bit on power up; when this bit is set and Caliptra ROM rechecks that the life cycle state is manufacturing mode, it reads the iTRNG for a 512-bit value. |
| 423 | +3. Caliptra ROM writes the 512-bit value to the address available through a register named UDS_SEED_OFFSET which is strapped by SoC at integration time by using DMA HW assist macro available at ROM’s disposal. |
| 424 | +4. Caliptra ROM sets the corresponding status bit in CPTRA_DBG_MANUF_SERVICE_REG to indicate the flow completion. |
| 425 | +5. Manufacturing flow will poll/read this bit and then do the fuse burning flow as specified by the fuse controller spec and SoC specific VR methodologies (eg. Fuse macro voltage elevation flows etc.). |
| 426 | + |
| 427 | +## Provisioning IDevID during manufacturing |
| 428 | + |
| 429 | + |
| 430 | + |
| 431 | +*Figure 7: Passive Mode: Device manufacturing identity flow* |
| 475 | 432 | |
| 476 | 433 | 1. High Volume Manufacturing (HVM) programs the IDevID certificate attributes fuses. See [IDevID Certificate](#idevid-certificate) for encodings. |
| 477 | 434 | 2. 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. |
| @@ -486,22 +443,22 @@ |
| 486 | 443 | 11. HVM must clear bit 0 of CPTRA\_DBG\_MANUF\_SERVICE\_REG, indicating that it completed reading the CSR. |
| 487 | 444 | 12. Caliptra ROM opens the Caliptra Mailbox for SoC usages, such as FW loading (if required in some HVM flows). The SoC is only allowed to request a lock of the AXI-exposed mailbox interface after this CSR operation is complete. |
| 488 | 445 | |
| 489 | | -### Certificate format |
| 446 | +## Certificate format |
| 490 | 447 | |
| 491 | 448 | Caliptra certificates follow the X.509 v3 format described in RFC 5280. After vendor provisioning, Caliptra's certificate chain contains the following certificates: |
| 492 | 449 | |
| 493 | 450 | 1. Provisioner CA (may be one or more certificates) |
| 494 | 451 | 2. IDevID |
| 495 | 452 | 3. LDevID |
| 496 | | -4. Alias~FMC~ |
| 497 | | -5. Alias~RT~ |
| 453 | +4. Alias<sub>FMC</sub> |
| 454 | +5. Alias<sub>RT</sub> |
| 498 | 455 | 6. DPE |
| 499 | 456 | |
| 500 | | -After owner provisioning, an Owner CA may endorse the IDevID, LDevID, or Alias~FMC~ public keys. Owner CA provisioning is outside the scope of this specification. |
| 501 | | - |
| 502 | | -Caliptra generates the LDevID, Alias~FMC~, Alias~RT~, and DPE certificates. The vendor, and optionally the owner, generate all other certificates. |
| 503 | | - |
| 504 | | -#### Serial number algorithm ### |
| 457 | +After owner provisioning, an Owner CA may endorse the IDevID, LDevID, or Alias<sub>FMC</sub> public keys. Owner CA provisioning is outside the scope of this specification. |
| 458 | + |
| 459 | +Caliptra generates the LDevID, Alias<sub>FMC</sub>, Alias<sub>RT</sub>, and DPE certificates. The vendor, and optionally the owner, generate all other certificates. |
| 460 | + |
| 461 | +### Serial number algorithm ### |
| 505 | 462 | |
| 506 | 463 | Caliptra uses certificate templates to avoid implementing fully capable X.509 v3 parsers and generators. Templates require certificates to be fixed length. This imposes constraints on the certificate serial numbers: |
| 507 | 464 | |
| @@ -517,17 +474,17 @@ |
| 517 | 474 | 4. OR the least-significant-byte with 0x04. |
| 518 | 475 | 5. Perform byte-wise copies of the least-significant 20 bytes into the certificate template. |
| 519 | 476 | |
| 520 | | -#### Provisioner CA |
| 521 | | - |
| 522 | | -Provisioner CA (pCA) is a set of one or more certificates issued by the vendor. The vendor is responsible for provisioning pCA to the SoC. Caliptra does not consume pCA. See [TCG DICE Attestation Architecture Version 1.00 Revision 0.23](https://trustedcomputinggroup.org/wp-content/uploads/DICE-Attestation-Architecture-r23-final.pdf) for guidance on pCA. |
| 523 | | - |
| 524 | | -#### IDevID certificate |
| 525 | | - |
| 526 | | -The vendor issues the IDevID certificate during SoC manufacturing. As part of [provisioning IDevID during manufacturing](#sec:idev-during-manufacturing), Caliptra uses the UDS to derive the IDevID key pair and generate a CSR. The vendor's pCA uses the CSR to generate and sign the IDevID certificate. The CSR uses the format defined in PKCS#10. |
| 527 | | - |
| 528 | | -For IDevID to endorse LDevID, Caliptra requires the vendor to implement an X.509 v3 IDevID certificate described in RFC 5280 with the field values specified in [Table](#idevid-cert-fields). The vendor shall also populate all extensions from the "Requested Extensions" attribute in the CSR. It is also recommended that the vendor add the Authority Information Access (AIA) extension to the IDevID certificate and maintain an Online Certificate Status Protocol (OCSP) responder with a URL pointed to by the AIA extension. |
| 529 | | - |
| 530 | | -**Table: IDevID certificate fields** {#idevid-cert-fields} |
| 477 | +### Provisioner CA |
| 478 | + |
| 479 | +Provisioner CA (pCA) is a set of one or more certificates issued by the vendor. The vendor is responsible for provisioning pCA to the SoC. Caliptra does not consume pCA. See [Reference 5](#ref-5) for guidance on pCA. |
| 480 | + |
| 481 | +### IDevID certificate |
| 482 | + |
| 483 | +The vendor issues the IDevID certificate during SoC manufacturing. As part of [provisioning IDevID during manufacturing](#provisioning-idevid-during-manufacturing), Caliptra uses the UDS to derive the IDevID key pair and generate a CSR. The vendor's pCA uses the CSR to generate and sign the IDevID certificate. The CSR uses the format defined in PKCS#10. |
| 484 | + |
| 485 | +For IDevID to endorse LDevID, Caliptra requires the vendor to implement an X.509 v3 IDevID certificate described in RFC 5280 with the field values specified in *Table 7: IDevID certificate fields*. The vendor shall also populate all extensions from the "Requested Extensions" attribute in the CSR. It is also recommended that the vendor add the Authority Information Access (AIA) extension to the IDevID certificate and maintain an Online Certificate Status Protocol (OCSP) responder with a URL pointed to by the AIA extension. |
| 486 | + |
| 487 | +*Table 7: IDevID certificate fields* |
| 531 | 488 | |
| 532 | 489 | | Field | Sub field | Value |
| 533 | 490 | | ------------- | --------- | --------- |
| @@ -559,7 +516,7 @@ |
| 559 | 516 | * Subject Key ID (bytes 4 to 23): if Flags = 3, the IDevID Subject Key Identifier to use as the LDevID Authority Key Identifier. |
| 560 | 517 | * UEID type (byte 24): UEID type as defined in [IETF RATS specification](https://www.ietf.org/archive/id/draft-ietf-rats-eat-21.html#section-4.2.1.1). Used for TCG UEID extension. |
| 561 | 518 | * Reserved (bytes 25 to 27) |
| 562 | | -* Manufacturer Serial Number (bytes 28 to 43): the 128-bit unique serial number of the device to be used for the TCG UEID extension in the Caliptra-generated LDevID, Alias~FMC~, and Alias~RT~ certificates. |
| 519 | +* Manufacturer Serial Number (bytes 28 to 43): the 128-bit unique serial number of the device to be used for the TCG UEID extension in the Caliptra-generated LDevID, Alias<sub>FMC</sub>, and Alias<sub>RT</sub> certificates. |
| 563 | 520 | |
| 564 | 521 | The IDevID certificate is unique for each device and non-renewable. The SoC must be able to retrieve the IDevID certificate at runtime. To save flash space and aid in recoverability, it is recommended that the vendor define an IDevID certificate template such that the SoC at runtime can reconstruct the same certificate that the pCA endorsed. The SoC is recommended to store the IDevID certificate signature in fuses and the IDevID certificate template in the firmware image. Caliptra runtime firmware provides APIs to aid in reconstructing the certificate: |
| 565 | 522 | |
| @@ -568,11 +525,11 @@ |
| 568 | 525 | |
| 569 | 526 | Caliptra does not allocate fuses in its fuse map for the IDevID certificate signature. Caliptra allocates "IDEVID MANUF HSM IDENTIFIER" fuses that the vendor can use to aid certificate reconstruction. |
| 570 | 527 | |
| 571 | | -#### LDevID certificate |
| 528 | +### LDevID certificate |
| 572 | 529 | |
| 573 | 530 | Caliptra ROM generates the LDevID certificate and endorses it with the IDevID private key. The LDevID certificate implements the following field values: |
| 574 | 531 | |
| 575 | | -**Table: LDevID certificate fields** {#ldevid-cert-fields} |
| 532 | +*Table 8: LDevID certificate fields* |
| 576 | 533 | |
| 577 | 534 | | Field | Sub field | Value |
| 578 | 535 | | ------------- | --------- | --------- |
| @@ -599,11 +556,11 @@ |
| 599 | 556 | |
| 600 | 557 | Caliptra does not generate an LDevID CSR. Owners that wish to endorse LDevID must do so with proprietary flows. |
| 601 | 558 | |
| 602 | | -#### Alias~FMC~ certificate |
| 603 | | - |
| 604 | | -Caliptra ROM generates the Alias~FMC~ certificate and endorses it with the LDevID private key. The Alias~FMC~ certificate implements the following field values: |
| 605 | | - |
| 606 | | -**Table: Alias~FMC~ certificate fields** {#alias-fmc-cert-fields} |
| 559 | +### Alias<sub>FMC</sub> certificate |
| 560 | + |
| 561 | +Caliptra ROM generates the Alias<sub>FMC</sub> certificate and endorses it with the LDevID private key. The Alias<sub>FMC</sub> certificate implements the following field values: |
| 562 | + |
| 563 | +*Table 9: Alias<sub>FMC</sub> certificate fields* |
| 607 | 564 | |
| 608 | 565 | | Field | Sub field | Value |
| 609 | 566 | | ------------- | --------- | --------- |
| @@ -644,13 +601,13 @@ |
| 644 | 601 | | | | owner public key hash |
| 645 | 602 | | | | [1] SHA384 digest of FMC |
| 646 | 603 | |
| 647 | | -Caliptra does not generate an Alias~FMC~ CSR. Owners that wish to endorse Alias~FMC~ must do so with proprietary flows. |
| 648 | | - |
| 649 | | -#### Alias~RT~ certificate |
| 650 | | - |
| 651 | | -Caliptra FMC generates the Alias~RT~ certificate and endorses it with the Alias~FMC~ private key. The Alias~RT~ certificate implements the following field values: |
| 652 | | - |
| 653 | | -**Table: Alias~RT~ certificate fields** {#alias-rt-cert-fields} |
| 604 | +Caliptra does not generate an Alias<sub>FMC</sub> CSR. Owners that wish to endorse Alias<sub>FMC</sub> must do so with proprietary flows. |
| 605 | + |
| 606 | +### Alias<sub>RT</sub> certificate |
| 607 | + |
| 608 | +Caliptra FMC generates the Alias<sub>RT</sub> certificate and endorses it with the Alias<sub>FMC</sub> private key. The Alias<sub>RT</sub> certificate implements the following field values: |
| 609 | + |
| 610 | +*Table 10: Alias<sub>RT</sub> certificate fields* |
| 654 | 611 | |
| 655 | 612 | | Field | Sub field | Value |
| 656 | 613 | | ------------- | --------- | --------- |
| @@ -677,15 +634,17 @@ |
| 677 | 634 | | tcg-dice-TcbInfo | SVN | Firmware SVN |
| 678 | 635 | | | FWIDs | [0] SHA384 digest of RT |
| 679 | 636 | |
| 680 | | -Caliptra does not generate an Alias~RT~ CSR. Owners that wish to endorse Alias~RT~ must do so with proprietary flows. |
| 681 | | - |
| 682 | | -#### DPE certificate |
| 683 | | - |
| 684 | | -Caliptra RT generates the DPE certificate and endorses it with the Alias~RT~ private key. The DPE certificate fields are described in the [Caliptra Runtime specification](https://github.com/chipsalliance/caliptra-sw/blob/main/runtime/README.md). DPE also supports issuance of CSRs. |
| 685 | | - |
| 686 | | -### Caliptra security states |
| 687 | | - |
| 688 | | -{#caliptra-security-states} |
| 637 | +Caliptra does not generate an Alias<sub>RT</sub> CSR. Owners that wish to endorse Alias<sub>RT</sub> must do so with proprietary flows. |
| 638 | + |
| 639 | +### DPE certificate |
| 640 | + |
| 641 | +Caliptra RT generates the DPE certificate and endorses it with the Alias<sub>RT</sub> private key. The DPE certificate fields are described in the [Caliptra Runtime specification](https://github.com/chipsalliance/caliptra-sw/blob/main/runtime/README.md). DPE also supports issuance of CSRs. |
| 642 | + |
| 643 | +## Caliptra security states |
| 644 | + |
| 645 | + |
| 646 | + |
| 647 | +*Figure 6: Caliptra security states* |
| 689 | 648 | |
| 690 | 649 | **Definitions** |
| 691 | 650 | |
| @@ -705,25 +664,26 @@ |
| 705 | 664 | * Lower 2 bits are mapped to device lifecycle (unprovisioned, manufacturing, production). |
| 706 | 665 | * SoC’s security state may also be influenced by its own device lifecycle. A HW state machine must drive the SoC security state. |
| 707 | 666 | * Caliptra’s security state determines Caliptra’s debug state and the state of its security assets. |
| 708 | | -* 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](#sec:assets) for information. |
| 709 | | - |
| 710 | | -**Table: Security states** {#security-states} |
| 667 | +* 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. |
| 668 | + |
| 669 | +*Table 11: Security states* |
| 711 | 670 | |
| 712 | 671 | | Security state, device lifecycle state [2:0] | State | Definition | State transition requirement | |
| 713 | | -| --- | --- | --- | --- | |
| 714 | | -| 000b | DebugUnlocked and unprovisioned | This shall be the default state value for Caliptra’s security state; it is used for development and early Caliptra bring up. This state is not used to provision the Caliptra assets. In this state: - UDS and all other identity critical assets shall not be programmed in fuses. Un-programmed fuse bits shall be read as 0s (zero). The debug UDS shall be obfuscated and de-obfuscated using the debug obfuscation key. - Obfuscation key: The debug obfuscation key shall be used. - Caliptra JTAG is unlocked and allows microcontroller debug. - Caliptra JTAG can access IP internal registers through FW. | Unprovisioned to any other state requires a cold boot of Caliptra and SoC. | |
| 715 | | -| 101b | DebugLocked and manufacturing | Caliptra must be placed in this state during the secure HVM process. In this state: - UDS and other identity critical assets shall be programmed into fuses. They are written into Caliptra fuse registers, similar to the ‘Secure’ state. - All security assets shall be in production mode (production UDS and obfuscation shall be used). - Upon pwrgood assertion, Caliptra JTAG shall be locked; microcontroller debug shall be disabled. - Caliptra microcontroller can be interrupted through JTAG mailbox. | Manufacturing -> insecure state transition is allowed with warm reset and Caliptra clears all of the security critical assets and registers before JTAG is opened. Manufacturing -> secured state is allowed ONLY with a cold boot. See [Provisioning During Manufacturing]( #sec:idev-during-manufacturing) for details. | |
| 716 | | -| 111b | DebugLocked and production | All security assets are in production mode. In this state: - Production UDS and obfuscation key shall be used. - CPU execution shall be enabled. - All ‘backdoor’ functionality shall be disabled (for example, developer functions and functionality that could reveal sensitive information or result in escalation of privileges). - Debug functions shall be disabled. Caliptra JTAG is locked – microcontroller debug shall be disabled. Caliptra microcontroller shall not be interruptible through JTAG mailbox. - DFT functions shall be disabled. | DebugLocked -> DebugUnlocked is possible without cold boot and Caliptra clears all of the security critical assets and registers before JTAG is opened. | |
| 717 | | -| 011b | DebugUnlocked and production | This state is used when debugging of Caliptra is required. When in this state: UDS and other identity critical assets are programmed into fuses. They may not have been written into Caliptra fuse registers if the insecure state entered before Caliptra is out of reset. If the insecure state transition happened after fuses are written to Caliptra, they are cleared when the security state transitions from secure/production -> insecure. Caliptra state: All security assets are in debug mode (UDS and obfuscation key are in production state). - UDS: Reverts to a ‘well-known’ debug value. - Obfuscation key: Switched to debug key. - Key Vault is also cleared. - Caliptra JTAG is unlocked and allows microcontroller debug. - Caliptra JTAG can access IP internal registers through FW or directly. | DebugUnlocked -> DebugLocked is allowed ONLY with a cold boot. | |
| 672 | +| ------------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | |
| 673 | +| 000b | DebugUnlocked and unprovisioned | This shall be the default state value for Caliptra’s security state; it is used for development and early Caliptra bring up. This state is not used to provision the Caliptra assets. In this state:<br> - UDS and all other identity critical assets shall not be programmed in fuses. Un-programmed fuse bits shall be read as 0s (zero). The debug UDS shall be obfuscated and de-obfuscated using the debug obfuscation key.<br> - Obfuscation key: The debug obfuscation key shall be used.<br> - Caliptra JTAG is unlocked and allows microcontroller debug.<br> - Caliptra JTAG can access IP internal registers through FW. | Unprovisioned to any other state requires a cold boot of Caliptra and SoC. | |
| 674 | +| 101b | DebugLocked and manufacturing | Caliptra must be placed in this state during the secure HVM process. In this state:<br> - UDS and other identity critical assets shall be programmed into fuses. They are written into Caliptra fuse registers, similar to the ‘Secure’ state.<br> - All security assets shall be in production mode (production UDS and obfuscation shall be used).<br> - Upon pwrgood assertion, Caliptra JTAG shall be locked; microcontroller debug shall be disabled.<br> - Caliptra microcontroller can be interrupted through JTAG mailbox. | Manufacturing -> insecure state transition is allowed with warm reset and Caliptra clears all of the security critical assets and registers before JTAG is opened.<br> Manufacturing -> secured state is allowed ONLY with a cold boot. See [Provisioning During Manufacturing](#provisioning-idevid-during-manufacturing) for details. | |
| 675 | +| 111b | DebugLocked and production | All security assets are in production mode. In this state:<br> - Production UDS and obfuscation key shall be used.<br> - CPU execution shall be enabled.<br> - All ‘backdoor’ functionality shall be disabled (for example, developer functions and functionality that could reveal sensitive information or result in escalation of privileges).<br> - Debug functions shall be disabled. Caliptra JTAG is locked – microcontroller debug shall be disabled. Caliptra microcontroller shall not be interruptible through JTAG mailbox.<br> - DFT functions shall be disabled. | DebugLocked -> DebugUnlocked is possible without cold boot and Caliptra clears all of the security critical assets and registers before JTAG is opened. | |
| 676 | +| 011b | DebugUnlocked and production | This state is used when debugging of Caliptra is required. When in this state: UDS and other identity critical assets are programmed into fuses. They may not have been written into Caliptra fuse registers if the insecure state entered before Caliptra is out of reset. If the insecure state transition happened after fuses are written to Caliptra, they are cleared when the security state transitions from secure/production -> insecure.<br> Caliptra state: All security assets are in debug mode (UDS and obfuscation key are in production state).<br> - UDS: Reverts to a ‘well-known’ debug value.<br> - Obfuscation key: Switched to debug key.<br> - Key Vault is also cleared.<br> - Caliptra JTAG is unlocked and allows microcontroller debug.<br> - Caliptra JTAG can access IP internal registers through FW or directly. | DebugUnlocked -> DebugLocked is allowed ONLY with a cold boot. | |
| 677 | + |
| 718 | 678 | |
| 719 | 679 | **Notes:** |
| 720 | 680 | |
| 721 | 681 | * End-of-life state is owned by SoC. In end-of-life device lifecycle state, Caliptra shall not not be brought out of reset. |
| 722 | 682 | * Other encodings are reserved and always assumed to be in a secure state. |
| 723 | 683 | |
| 724 | | -Each of these security states may be mapped to different SoC level debug and security states. SoC’s requirement is that if the SoC enters a debug state, then Caliptra must also be in an unsecured state where all assets are cleared. Caliptra security state is captured by hardware on every warm reset; therefore SoC integrators enforce the security state transition policies for cold boot events. These policies are described in the preceding table. |
| 725 | | - |
| 726 | | -### Service surface |
| 684 | +Each of these security states may be mapped to different SoC level debug and security states. SoC’s requirement is that if the SoC enters a debug state, then Caliptra must also be in an insecure state where all assets are cleared. Caliptra security state is captured by hardware on every warm reset; therefore SoC integrators enforce the security state transition policies for cold boot events. These policies are described in the preceding table. |
| 685 | + |
| 686 | +## Service surface |
| 727 | 687 | |
| 728 | 688 | The service surface of Caliptra has multiple vectors. All use cases are control plane services, useful to power on a system or start a task. Supporting line rate high performance IO cryptography or any other data path capability is not required. |
| 729 | 689 | |
| @@ -734,13 +694,13 @@ |
| 734 | 694 | * **Measurement Vault**: Caliptra shall support stashing of measurements for the code and configuration of the SoC. Caliptra can provide these measurements via PCR Quote API or via DPE. |
| 735 | 695 | * **FW Authentication**: Caliptra supports ECDSA and PQC MLDSA-87 verification for SoC firmware beyond its own. The SHA384 block exposes a HW API for hashing firmware. The runtime firmware exposes an ECDSA and MLDSA-87 verification API that uses the hash computed by the SHA384 block. |
| 736 | 696 | |
| 737 | | -### Device resilience |
| 738 | | - |
| 739 | | -As noted earlier, Caliptra plays a role in maintaining the resilience posture of the SoC as defined by NIST SP 800-193 Platform Firmware Resiliency Guidelines (see [Platform Firmware Resiliency Guidelines](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-193.pdf)). As the Silicon RTM and RTI, Caliptra is either responsible for, or participates in, various protection and detection requirements described in the NIST publication. |
| 697 | +## Device resilience |
| 698 | + |
| 699 | +As noted earlier, Caliptra plays a role in maintaining the resilience posture of the SoC as defined by NIST SP 800-193 Platform Firmware Resiliency Guidelines (see [Reference 1](#ref-1)). As the Silicon RTM and RTI, Caliptra is either responsible for, or participates in, various protection and detection requirements described in the NIST publication. |
| 740 | 700 | |
| 741 | 701 | The following table describes the NIST SP 800-193 requirements that Caliptra shall meet, either on its own or in conjunction with other components within the SoC or platform. Requirements not listed are assumed to be not covered and out-of-scope for Caliptra. In particular, most requirements related to firmware update and recovery are out-of-scope and must be handled by other components of the system. |
| 742 | 702 | |
| 743 | | -**Table: NIST SP 800-193 requirements** {#nist-sp-800-193-requirements} |
| 703 | +*Table 12: NIST SP 800-193 requirements* |
| 744 | 704 | |
| 745 | 705 | | NIST SP 800-193 Chapter | Requirement | Caliptra responsibility | |
| 746 | 706 | | :---------------------- | :---------- | :---------------------- | |
| @@ -769,13 +729,13 @@ |
| 769 | 729 | | 4.3.2 | The detection mechanism should be capable of logging events when data corruption is detected. | It is the responsibility of the SoC to log any corruption events upon notification by Caliptra. | |
| 770 | 730 | |
| 771 | 731 | |
| 772 | | -### Secure boot flow |
| 773 | | - |
| 774 | | -Caliptra shall follow and implement the secure boot guidelines as described in [Open Compute Project Secure Boot Specification](https://www.opencompute.org/documents/secure-boot-2-pdf). |
| 775 | | - |
| 776 | | -For the detailed flow, see the [hardware section](#hardware) and [firmware verifcation section](#sec:firmware-verification). |
| 777 | | - |
| 778 | | -### Hitless update |
| 732 | +## Secure boot flow |
| 733 | + |
| 734 | +Caliptra shall follow and implement the secure boot guidelines as described in [Reference 3](#ref-3). |
| 735 | + |
| 736 | +For the detailed flow, see the [hardware section](#hardware) and [firmware verifcation section](#firmware-verification). |
| 737 | + |
| 738 | +## Hitless update |
| 779 | 739 | |
| 780 | 740 | A ‘hitless’ (aka ‘impactless’) update occurs when an update is applied to Caliptra’s executing firmware without requiring a SoC or machine reboot. A hitless update allows Caliptra FW[^4] to remain up to date with FW security and/or functional patches while preventing or reducing machine downtime. Hitless update shall take effect immediately upon application (post-cryptographic verification). Updates to the machine’s persistent storage are still required because they ensure that Caliptra reboots to the latest FW if the system requires a restart or reboot. |
| 781 | 741 | |
| @@ -789,7 +749,7 @@ |
| 789 | 749 | |
| 790 | 750 | Caliptra contains 32 384-bit PCR banks that are extendable by the SHA engine, and readable by Caliptra firmware. The usage of the PCR banks is as follows: |
| 791 | 751 | |
| 792 | | -**Table: PCR bank usage** {#pcr-bank-usage} |
| 752 | +*Table 13: PCR bank usage* |
| 793 | 753 | |
| 794 | 754 | | **PCR number** | **Type** | **Extend control** | **Description** | |
| 795 | 755 | | - | - | - | - | |
| @@ -819,14 +779,13 @@ |
| 819 | 779 | 4. Digest of FMC |
| 820 | 780 | |
| 821 | 781 | Caliptra ROM fails to boot if the following values do not remain constant across a hitless update: |
| 822 | | - |
| 823 | 782 | * Owner public key hash |
| 824 | 783 | * ECDSA vendor public key index |
| 825 | 784 | * MLDSA-87 vendor public key index |
| 826 | 785 | * LMS vendor public key index |
| 827 | 786 | * FMC digest |
| 828 | 787 | |
| 829 | | -#### Attestation of Caliptra's update journey |
| 788 | +### Attestation of Caliptra's update journey |
| 830 | 789 | |
| 831 | 790 | Upon every cold boot and hitless update, Caliptra ROM extends Caliptra's FMC measurement and ROM policy configuration into PCR0 (current) and PCR1 (cumulative). Upon every cold boot and hitless update, Caliptra FMC extends Caliptra's runtime firmware and firmware manifest measurements into PCR2 (current) and PCR3 (cumulative). The current measurement of the FMC, ROM policy configuration, RT, and FW manifest are used to derive a CDI and an alias key given to runtime firmware. FMC places runtime firmware's measurements into runtime firmware's alias key certificate, and signs that certificate with FMC's alias key. |
| 832 | 791 | |
| @@ -842,7 +801,7 @@ |
| 842 | 801 | |
| 843 | 802 | Caliptra firmware will attest to PCR3 by including it as an input in all DPE leaf key derivations and as evidence in all DPE leaf key certificates. |
| 844 | 803 | |
| 845 | | -##### Commentary: recovery from a bad hitless update |
| 804 | +#### Commentary: recovery from a bad hitless update |
| 846 | 805 | |
| 847 | 806 | Suppose the following Caliptra firmware images exist: |
| 848 | 807 | |
| @@ -856,17 +815,17 @@ |
| 856 | 815 | 1. Caliptra's vendor-signed certificate over IDevID, and an IDevID-signed certificate over LDevID. |
| 857 | 816 | 2. An owner-signed certificate over IDevID, and an IDevID-signed certificate over LDevID. |
| 858 | 817 | 3. An owner-signed certificate over LDevID. |
| 859 | | -2. An LDevID-signed certificate over Alias~FMC~, which includes FMC's measurements as captured by ROM. |
| 860 | | -3. An Alias~FMC~-signed certificate over Alias~RT~, which includes runtime firmware's measurements as captured by FMC. |
| 861 | | -4. An Alias~RT~-signed certificate over a leaf DPE key, which includes PCR3 as read by runtime firmware, along with other measurements previously stashed in SRAM. |
| 818 | +2. An LDevID-signed certificate over Alias<sub>FMC</sub>, which includes FMC's measurements as captured by ROM. |
| 819 | +3. An Alias<sub>FMC</sub>-signed certificate over Alias<sub>RT</sub>, which includes runtime firmware's measurements as captured by FMC. |
| 820 | +4. An Alias<sub>RT</sub>-signed certificate over a leaf DPE key, which includes PCR3 as read by runtime firmware, along with other measurements previously stashed in SRAM. |
| 862 | 821 | 5. A log structure[^6] that represents the measurements that have been extended into PCR3. |
| 863 | 822 | 6. A leaf-DPE-signed blob[^7] containing the freshness nonce. |
| 864 | 823 | |
| 865 | 824 | The remote verifier evaluates (1) according to ownership policies to determine whether the Caliptra device is trustworthy, before proceeding to verify the rest of the attestation response. |
| 866 | 825 | |
| 867 | | -Thus satisfied in the trustworthiness of the Caliptra device, the remote verifier can then evaluate the trustworthiness of FMC by inspecting the measurements in (2), Alias~FMC~'s certificate. The verifier can reject the attestation if those measurements do not conform to a known-good value. |
| 868 | | - |
| 869 | | -Thus satisfied in the trustworthiness of FMC, the remote verifier can then evaluate the trustworthiness of runtime firmware by inspecting the measurements in (3), Alias~RT~'s certificate. If version A or C is running, then the PCR3 measurement present in (4), the leaf DPE key certificate, is presumed to be an honest reflection of the hardware register as read by runtime firmware. The verifier can reject the attestation if Alias~RT~'s certificate indicates that version B is currently running. |
| 826 | +Thus satisfied in the trustworthiness of the Caliptra device, the remote verifier can then evaluate the trustworthiness of FMC by inspecting the measurements in (2), Alias<sub>FMC</sub>'s certificate. The verifier can reject the attestation if those measurements do not conform to a known-good value. |
| 827 | + |
| 828 | +Thus satisfied in the trustworthiness of FMC, the remote verifier can then evaluate the trustworthiness of runtime firmware by inspecting the measurements in (3), Alias<sub>RT</sub>'s certificate. If version A or C is running, then the PCR3 measurement present in (4), the leaf DPE key certificate, is presumed to be an honest reflection of the hardware register as read by runtime firmware. The verifier can reject the attestation if Alias<sub>RT</sub>'s certificate indicates that version B is currently running. |
| 870 | 829 | |
| 871 | 830 | Thus satisfied that version B is not currently running and that PCR3 is an accurate reflection of the hardware register, the remote verifier can then compare the log in (5) to PCR3 in (4) to confirm its authenticity, then walk the log to confirm that FMC never launched version B since cold-boot. If version B did run, that firmware could have maliciously modified DPE measurements stashed in SRAM, but could not have modified the contents of PCR3 to erase the evidence that version B ran at all, and could not have influenced the behavior of firmware versions A or C to prevent them from accurately reporting the contents of PCR3. |
| 872 | 831 | |
| @@ -874,7 +833,7 @@ |
| 874 | 833 | |
| 875 | 834 | Finally, the verifier can confirm freshness by comparing the nonce in (6) to the one emitted in the original challenge. Because DPE only allows a derived leaf key to be used if the measurements present in its leaf certificate are a reflection of the current state, the fact that the freshness nonce was signed by DPE is evidence that the measurements in (4) are fresh. |
| 876 | 835 | |
| 877 | | -##### Commentary: maintaining sealed secrets across a power cycle |
| 836 | +#### Commentary: maintaining sealed secrets across a power cycle |
| 878 | 837 | |
| 879 | 838 | Caliptra does not seal secrets directly. However, Caliptra does implement DPE, which allows secrets to be sealed to an external sealer such as a TPM, with a policy that only allows those secrets to be unsealed if Caliptra allows the host to wield a particular leaf DPE key. This leaf DPE key is permuted based on the hitless update journey of the various components whose measurements are stored within Caliptra. |
| 880 | 839 | |
| @@ -886,7 +845,7 @@ |
| 886 | 845 | |
| 887 | 846 | Note: as all DPE leaf keys are derived using Caliptra runtime firmware's CDI, a DPE simulation context cannot predict the leaf key that would be available if a different Caliptra firmware image were to boot (because one Caliptra firmware image does not have access to a different image's CDI). Therefore, if a different Caliptra firmware image is staged to persistent storage, Caliptra must first be hitlessly updated to that image before a simulation context can be used to predict public keys that will be available to that image on the next cold boot. |
| 888 | 847 | |
| 889 | | -#### Attestation of SoC update journey |
| 848 | +### Attestation of SoC update journey |
| 890 | 849 | |
| 891 | 850 | Caliptra shall also attest to the journeys of SoC components. A SoC component's journey may change independently of other components. For example, SoC components may implement partial resets or hitless updates that cause the component's firmware or configuration to reload. |
| 892 | 851 | |
| @@ -899,9 +858,9 @@ |
| 899 | 858 | |
| 900 | 859 | The corresponding journey measurement computation is the chained extension of \[A->A->B->B->B\]. The verifier can ascertain this through the two event log entries. |
| 901 | 860 | |
| 902 | | -### Anti-rollback support |
| 903 | | - |
| 904 | | -Caliptra shall provide fuse banks (refer to [Table](#caliptra-fuse-map)) that are used for storing monotonic counters to provide anti-rollback enforcement for Caliptra mutable firmware. Each distinctly signed boot stage shall be associated with its own anti-rollback fuse field. Together with the vendor, Caliptra allows owners to enforce strong anti-rollback requirements, in addition to supporting rollback to a previous firmware version. This is a critical capability for hyperscalers. |
| 861 | +## Anti-rollback support |
| 862 | + |
| 863 | +Caliptra shall provide fuse banks (refer to *Table 21: Caliptra Fuse Map*) that are used for storing monotonic counters to provide anti-rollback enforcement for Caliptra mutable firmware. Each distinctly signed boot stage shall be associated with its own anti-rollback fuse field. Together with the vendor, Caliptra allows owners to enforce strong anti-rollback requirements, in addition to supporting rollback to a previous firmware version. This is a critical capability for hyperscalers. |
| 905 | 864 | |
| 906 | 865 | Caliptra firmware shall include an SVN value in the signed header. If the firmware's SVN value is less than the current counter value in the fuse bank, Caliptra shall refuse to boot that firmware, regardless of whether the signature is valid. |
| 907 | 866 | |
| @@ -909,7 +868,7 @@ |
| 909 | 868 | |
| 910 | 869 | Each of Caliptra's internal anti-rollback fuse banks shall support a minimum counter value of 64. This feature is expected to be used sparingly. |
| 911 | 870 | |
| 912 | | -### Physical attack countermeasures |
| 871 | +## Physical attack countermeasures |
| 913 | 872 | |
| 914 | 873 | Caliptra shall implement countermeasures designed to deter both glitching (also referred to fault-injection (FI)) and side-channel attacks (simple power analysis (SPA) and differential power analysis (DPA)). |
| 915 | 874 | |
| @@ -919,21 +878,21 @@ |
| 919 | 878 | |
| 920 | 879 | Randomly generated per-part entropy is subject to physical inspection attacks in the supply chain as well. The fuses that store the UDS entropy shall be protected to a degree that forces an attacker to perform a destructive operation to read their values. Decapping and fibbing attacks should at least penetrate enough layers and metal shielding to render the part useless, if not being outright impossible to carry out. Entropy tied to a damaged asset typically requires injection of counterfeit devices in the supply chain, which is a very powerful adversary model. |
| 921 | 880 | |
| 922 | | -Another way to obtain access to secret entropy with “unlimited supply chain time” is to observe side channels while the SoC is executing. Because Caliptra is expected to be a <1 mm^2^ fraction of a large SoC, side-channel mitigation is required only against extremely resourceful attackers that can wade through and discern a large number of confounding signals and power profiles. With that priority in mind, DPA and DMA attacks should be mitigated via decoy value generation. |
| 881 | +Another way to obtain access to secret entropy with “unlimited supply chain time” is to observe side channels while the SoC is executing. Because Caliptra is expected to be a <1 mm<sup>2</sup> fraction of a large SoC, side-channel mitigation is required only against extremely resourceful attackers that can wade through and discern a large number of confounding signals and power profiles. With that priority in mind, DPA and DMA attacks should be mitigated via decoy value generation. |
| 923 | 882 | |
| 924 | 883 | Any private key material or symmetric key material embedded in the RTL (and therefore “global”) must be treated as having low value, reaching zero value in a number of quarters. A supply chain attacker can destructively obtain the key material, and loss of one part is not going to trigger any alarms. |
| 925 | 884 | |
| 926 | | -Mitigation against SCA is not trivial and may be implemented in a variety of ways. [Side-Channel Attacks: Ten Years After Its Publication and the Impacts on Cryptographic Module Security Testing](https://csrc.nist.gov/csrc/media/events/physical-security-testing-workshop/documents/papers/physecpaper19.pdf) provides a comprehensive overview of methods and techniques used in various SCA as well as recommendations for countermeasures against such attacks (including feasibility and applicability). Additionally, there are academic papers available from NIST and other resources that discuss SCA and their countermeasures. |
| 927 | | - |
| 928 | | -### Compliance and certification requirements |
| 885 | +Mitigation against SCA is not trivial and may be implemented in a variety of ways. [Reference 7](#ref-7) provides a comprehensive overview of methods and techniques used in various SCA as well as recommendations for countermeasures against such attacks (including feasibility and applicability). Additionally, there are academic papers available from NIST and other resources that discuss SCA and their countermeasures. |
| 886 | + |
| 887 | +## Compliance and certification requirements |
| 929 | 888 | |
| 930 | 889 | Due to the identity service surface offered to other SoC subsystems, Caliptra may fall under the Target of Evaluation (ToE) of an application that wishes to attain a specific compliance level for business reasons. |
| 931 | 890 | |
| 932 | 891 | It is important to highlight that it’s not necessary for the RTM itself to unilaterally attain (for example, FIPS 140-3 L3). It is only relevant when the RTM is included in the “bag” that wants to obtain a compliance certification. For example, it is relevant when a cloud provider wants to FIPS-certify PCIe link encryption in transit rooted to an ASIC identity emanating from a Caliptra instance. |
| 933 | 892 | |
| 934 | | -See [Attestation of System Components v1.0 Requirements and Recommendations](https://www.opencompute.org/documents/attestation-v1-0-20201104-pdf) for requirements related to keys, entropy, random bits, cryptographic modules, and algorithms. |
| 935 | | - |
| 936 | | -#### Known Answer Test (KAT) support |
| 893 | +See [Reference 8](#ref-8) for requirements related to keys, entropy, random bits, cryptographic modules, and algorithms. |
| 894 | + |
| 895 | +### Known Answer Test (KAT) support |
| 937 | 896 | |
| 938 | 897 | To certify a cryptographic module, pre-operational self-tests must be performed when the system is booted. Implementing KATs is required for FIPS certification. However, regardless of FIPS certification, it is considered a security best practice to ensure that the supported cryptographic algorithms are functioning properly to guarantee correct security posture. |
| 939 | 898 | |
| @@ -944,7 +903,7 @@ |
| 944 | 903 | |
| 945 | 904 | A detailed description of the POST and CAST KATs can be found at csrc.nist.gov. |
| 946 | 905 | |
| 947 | | -**Table: KAT failure mitigations** {#kat-failure-mitigations} |
| 906 | +*Table 14: KAT failure mitigations* |
| 948 | 907 | |
| 949 | 908 | | KAT type | If fails | |
| 950 | 909 | | - | - | |
| @@ -952,7 +911,7 @@ |
| 952 | 911 | | CAST | Failure of a CAST KAT shall cause Caliptra to fail any operation that has a dependency on the associated cryptographic algorithm. | |
| 953 | 912 | |
| 954 | 913 | |
| 955 | | -**Table: POST/CAST usage** {#post-cast-usage} |
| 914 | +*Table 15: POST/CAST usage* |
| 956 | 915 | |
| 957 | 916 | | **Crypto algorithm** | **Caliptra Boot ROM** | **Caliptra FMC** | **Caliptra Runtime FW** |
| 958 | 917 | | -------------------- | --------------------- | ---------------- | ----------------------- |
| @@ -964,19 +923,20 @@ |
| 964 | 923 | | HMAC | Yes (CDI generation) | No | No |
| 965 | 924 | | KDF | Yes | Yes | No |
| 966 | 925 | |
| 967 | | -As shown in [Table](#post-cast-usage), since the cryptographic algorithms required by the Caliptra Boot ROM are considered POSTs, and those same algorithms are used by Caliptra FMC and FW, there is no requirement that FMC and Runtime FW implement CASTs for those algorithms. |
| 968 | | - |
| 969 | | -### Firmware image format and verification {#firmware-verification} |
| 970 | | - |
| 971 | | -Caliptra supports verifying firmware with ECDSA P384 and MLDSA-87 signatures and [Leighton-Micali Hash-based Signatures (LMS)](#post-quantum-cryptography-pqc-requirements) in accordance with the requirements described in [Open Compute Project Secure Boot Specification](https://www.opencompute.org/documents/secure-boot-2-pdf). |
| 972 | | - |
| 973 | | -Caliptra firmware is composed of two images: an FMC image and an application firmware image. A single firmware manifest describes these images. The manifest consists of a preamble ([Table](#fw-manifest-preamble)), a header ([Table](#fw-manifest-header)), and a Table of Contents (TOC) ([Table](#toc)). The image layout is shown in [Figure](#firmware-image-layout). |
| 974 | | - |
| 975 | | -{#firmware-image-layout} |
| 926 | +As shown in *Table 15: POST/CAST usage*, since the cryptographic algorithms required by the Caliptra Boot ROM are considered POSTs, and those same algorithms are used by Caliptra FMC and FW, there is no requirement that FMC and Runtime FW implement CASTs for those algorithms. |
| 927 | + |
| 928 | +## Firmware image format and verification |
| 929 | + |
| 930 | +Caliptra supports verifying firmware with ECDSA P384 and MLDSA-87 signatures and [Leighton-Micali Hash-based Signatures (LMS)](#post-quantum-cryptography-pqc-requirements) in accordance with the requirements described in [Reference 3](#ref-3). |
| 931 | + |
| 932 | +Caliptra firmware is composed of two images: an FMC image and an application firmware image. A single firmware manifest describes these images. The manifest consists of a preamble (*Table 16*), a header (*Table 17*), and a Table of Contents (TOC) (*Table 18*). The image layout is shown in *Figure 7: firmware image layout*. |
| 933 | + |
| 934 | + |
| 935 | + |
| 936 | +*Figure 7: Firmware image layout* |
| 976 | 937 | |
| 977 | 938 | To verify the firmware, Caliptra ROM performs the following steps: |
| 978 | | - |
| 979 | | -1. Calculates the hash of the vendor [key](#tbl:ecc-pub-key-descriptor) [descriptors](#tbl:pqc-pub-key-descriptor) in the preamble and compares it against the hash in fuses (key_manifest_pk_hash). If the lifecycle is not "unprovisioned" and the hashes do not match, the boot fails. |
| 939 | +1. Calculates the hash of the vendor [key descriptors](#table-17-public-key-descriptor) in the preamble and compares it against the hash in fuses (key_manifest_pk_hash). If the lifecycle is not "unprovisioned" and the hashes do not match, the boot fails. |
| 980 | 940 | 2. Calculates the hashes of the active vendor public keys and compares it against the hashes in the key descriptors identified by the corresponding active key indices. |
| 981 | 941 | 3. Calculates the hash of the owner public keys in the preamble and compares it against the hash in fuses (owner_pk_hash). If the owner_pk_hash fuse is not zero (i.e., unprovisioned) and hashes do not match, the boot fails. See the [Owner authorization](#owner-authorization) section. |
| 982 | 942 | 4. Ensures the vendor public key(s) selected by the preamble indices are not revoked based on fuse: key_manifest_pk_hash_mask for ECDSA public key, pqc_revocation for LMS or MLDSA public key. |
| @@ -991,80 +951,82 @@ |
| 991 | 951 | |
| 992 | 952 | In addition to cold boot, Caliptra ROM performs firmware verification on hitless updates. See the [hitless update](#hitless-update) section for details. |
| 993 | 953 | |
| 994 | | -Fields in Tables [-[Table](#fw-manifest-preamble)], [-[Table](#ecc-pub-key-descriptor)], [-[Table](#pqc-pub-key-descriptor)], [-[Table](#fw-manifest-header)], and [-[Table](#toc)] that are 4-byte dwords are little endian unless described otherwise. |
| 995 | | -Hashes must be stored with each 32-bit dword having swapped endianness from the SHA2 standard byte order. |
| 996 | | -Signatures are stored in the byte order indicated in the standard. |
| 997 | | - |
| 998 | | -**Table: Firmware manifest preamble** {#fw-manifest-preamble} |
| 954 | +*Table 16: Firmware manifest preamble* |
| 955 | + |
| 956 | +Fields are little endian unless described otherwise. |
| 999 | 957 | |
| 1000 | 958 | | Field | Size (bytes) | Description | |
| 1001 | | -| --- | --- | --- | |
| 1002 | | -| Firmware Manifest Marker | 4 | Magic Number marking the start of the package manifest. The value must be 0x434D4E32 (‘CMN2’ in ASCII) in big endian order | |
| 959 | +| ------- | -------- | ------------ | |
| 960 | +| Firmware Manifest Marker | 4 | Magic Number marking the start of the package manifest. The value must be 0x434D414E (‘CMAN’ in ASCII) | |
| 1003 | 961 | | Firmware Manifest Size | 4 | Size of the full manifest structure | |
| 1004 | | -| Firmware Manifest Type | 4 | **Byte0:** - Type - 0x1 – ECDSA & MLDSA Keys - 0x3 – ECDSA & LMS Keys **Byte1-Byte3:** Reserved | |
| 962 | +| Firmware Manifest Type | 4 | **Byte0:** - Type <br> 0x1 – ECDSA & LMS Keys <br> 0x2 – ECDSA & MLDSA Keys <br> **Byte1-Byte3:** Reserved | |
| 1005 | 963 | | Vendor ECDSA Key Descriptor | 196 | Public Key Descriptor for ECDSA keys | |
| 1006 | 964 | | Vendor LMS or MLDSA Key Descriptor | 1540 | Public Key Descriptor for LMS (1540 bytes) or MLDSA (196 bytes + 1344 unused bytes) keys | |
| 1007 | 965 | | Active ECDSA Key Index | 4 | Public Key Index for the active ECDSA key | |
| 1008 | | -| Active ECDSA Key | 96 | ECDSA P384 public key used to verify the Firmware Manifest Header Signature - **X-Coordinate:** Public Key X-Coordinate (48 bytes, big endian) - **Y-Coordinate:** Public Key Y-Coordinate (48 bytes, big endian) | |
| 966 | +| Active ECDSA Key | 96 | ECDSA P384 public key used to verify the Firmware Manifest Header Signature <br> **X-Coordinate:** Public Key X-Coordinate (48 bytes, big endian) <br> **Y-Coordinate:** Public Key Y-Coordinate (48 bytes, big endian) | |
| 1009 | 967 | | Active LMS or MLDSA Key Index | 4 | Public Key Index for the active LMS or MLDSA key | |
| 1010 | | -| Active LMS or MLDSA Key | 2592 | LMS public key (48 bytes + 2544 unused bytes) used to verify the Firmware Manifest Header Signature. - **tree_type:** LMS Algorithm Type (4 bytes, big endian) Must equal 12. - **otstype:** LM-OTS Algorithm Type (4 bytes, big endian) Must equal 7. - **id:** (16 bytes) - **digest:** (24 bytes) **OR** MLDSA-87 public key used to verify the Firmware Manifest Header Signature. (2592 bytes) | |
| 1011 | | -| Vendor ECDSA Signature | 96 | Vendor ECDSA P384 signature of the Firmware Manifest header hashed using SHA384. - **R-Coordinate:** Random Point (48 bytes, big endian) - **S-Coordinate:** Proof (48 bytes, big endian) | |
| 1012 | | -| Vendor LMS or MLDSA Signature | 4628 | Vendor LMS signature (1620 bytes + 3008 unused bytes) of the Firmware Manifest header hashed using SHA384. - **q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes) - **ots:** LM-OTS Signature (1252 bytes) - **tree_type:** LMS Algorithm Type (4 bytes, big endian) Must equal 12. - **tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes) **OR** Vendor MLDSA-87 signature of the Firmware Manifest header hashed using SHA512 (4627 bytes + 1 Reserved byte). | |
| 1013 | | -| Owner ECDSA Public Key | 96 | ECDSA P384 public key used to verify the Firmware Manifest Header Signature. - **X-Coordinate:** Public Key X-Coordinate (48 bytes, big endian) - **Y-Coordinate:** Public Key Y-Coordinate (48 bytes, big endian) | |
| 1014 | | -| Owner LMS or MLDSA Public Key | 2592 | LMS public key (48 bytes + 2544 unused bytes) used to verify the Firmware Manifest Header Signature. - **tree_type:** LMS Algorithm Type (4 bytes, big endian) Must equal 12. - **otstype:** LM-OTS Algorithm Type (4 bytes, big endian) Must equal 7. - **id:** (16 bytes) - **digest:** (24 bytes) **OR** MLDSA-87 public key used to verify the Firmware Manifest Header Signature. (2592 bytes) | |
| 1015 | | -| Owner ECDSA Signature | 96 | Vendor ECDSA P384 signature of the Firmware Manifest header hashed using SHA384. - **R-Coordinate:** Random Point (48 bytes, big endian) - **S-Coordinate:** Proof (48 bytes, big endian) | |
| 1016 | | -| Owner LMS or MLDSA Signature | 4628 | Owner LMS signature (1620 bytes + 3008 unused bytes) of the Firmware Manifest header hashed using SHA384. - **q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes) - **ots:** LM-OTS Signature (1252 bytes) - **tree_type:** LMS Algorithm Type (4 bytes, big endian) Must equal 12. - **tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes) **OR** Owner MLDSA-87 signature of the Firmware Manifest header hashed using SHA512 (4627 bytes + 1 Reserved byte). | |
| 968 | +| Active LMS or MLDSA Key | 2592 | LMS public key (48 bytes + 2544 unused bytes) used to verify the Firmware Manifest Header Signature. <br> **tree_type:** LMS Algorithm Type (4 bytes, big endian) Must equal 12. <br> **otstype:** LM-OTS Algorithm Type (4 bytes, big endian) Must equal 7. <br> **id:** (16 bytes) <br> **digest:** (24 bytes) <br><br>**OR**<br><br>MLDSA-87 public key used to verify the Firmware Manifest Header Signature. <br> (2592 bytes) | |
| 969 | +| Vendor ECDSA Signature | 96 | Vendor ECDSA P384 signature of the Firmware Manifest header hashed using SHA384. <br> **R-Coordinate:** Random Point (48 bytes, big endian) <br> **S-Coordinate:** Proof (48 bytes, big endian) | |
| 970 | +| Vendor LMS or MLDSA Signature | 4628 | Vendor LMS signature (1620 bytes + 3008 unused bytes) of the Firmware Manifest header hashed using SHA384. <br> **q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes) <br> **ots:** LM-OTS Signature (1252 bytes) <br> **tree_type:** LMS Algorithm Type (4 bytes, big endian) Must equal 12. <br> **tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes) <br><br>**OR**<br><br> Vendor MLDSA-87 signature of the Firmware Manifest header hashed using SHA512 (4627 bytes + 1 Reserved byte). | |
| 971 | +| Owner ECDSA Key Descriptor | 52 | Public Key Descriptor for ECDSA key | |
| 972 | +| Owner LMS or MLDSA Key Descriptor | 52 | Public Key Descriptor for LMS or MLDSA key | |
| 973 | +| Owner ECDSA Public Key | 96 | ECDSA P384 public key used to verify the Firmware Manifest Header Signature. <br> **X-Coordinate:** Public Key X-Coordinate (48 bytes, big endian) <br> **Y-Coordinate:** Public Key Y-Coordinate (48 bytes, big endian) | |
| 974 | +| Owner LMS or MLDSA Public Key | 2592 | LMS public key (48 bytes + 2544 unused bytes) used to verify the Firmware Manifest Header Signature. <br> **tree_type:** LMS Algorithm Type (4 bytes, big endian) Must equal 12. <br> **otstype:** LM-OTS Algorithm Type (4 bytes, big endian) Must equal 7. <br> **id:** (16 bytes) <br> **digest:** (24 bytes) <br><br>**OR**<br><br>MLDSA-87 public key used to verify the Firmware Manifest Header Signature. <br> (2592 bytes) | |
| 975 | +| Owner ECDSA Signature | 96 | Vendor ECDSA P384 signature of the Firmware Manifest header hashed using SHA384. <br> **R-Coordinate:** Random Point (48 bytes, big endian) <br> **S-Coordinate:** Proof (48 bytes, big endian) | |
| 976 | +| Owner LMS or MLDSA Signature | 4628 | Owner LMS signature (1620 bytes + 3008 unused bytes) of the Firmware Manifest header hashed using SHA384. <br> **q:** Leaf of the Merkle tree where the OTS public key appears (4 bytes) <br> **ots:** LM-OTS Signature (1252 bytes) <br> **tree_type:** LMS Algorithm Type (4 bytes, big endian) Must equal 12. <br> **tree_path:** Path through the tree from the leaf associated with the LM-OTS signature to the root. (360 bytes) <br><br>**OR**<br><br> Owner MLDSA-87 signature of the Firmware Manifest header hashed using SHA512 (4627 bytes + 1 Reserved byte). | |
| 1017 | 977 | | Reserved | 8 | Reserved 8 bytes | |
| 1018 | 978 | |
| 1019 | | -**Table: ECC Manufacturer Public Key Descriptor** {#ecc-pub-key-descriptor} |
| 979 | + |
| 980 | +#### *Table 17: Public Key Descriptor* |
| 981 | + |
| 982 | +Fields are little endian unless described otherwise. |
| 1020 | 983 | |
| 1021 | 984 | | Field | Size (bytes) | Description | |
| 1022 | | -| --- | --- | --- | |
| 1023 | | -| Key Descriptor Version | 2 | Version of the Key Descriptor. The value must be 0x2 for Caliptra 2.x | |
| 1024 | | -| Reserved | 1 || |
| 985 | +| ------- | -------- | ------------ | |
| 986 | +| Key Descriptor Version | 1 | Version of the Key Descriptor. The value must be 0x1 for Caliptra 2.x | |
| 987 | +| Intent | 1 | Type of the descriptor <br> 0x1 - Vendor <br> 0x2 - Owner | |
| 988 | +| Key Type | 1 | Type of the key in the descriptor <br> 0x1 - ECC <br> 0x2 - LMS <br> 0x3 - MLDSA | |
| 1025 | 989 | | Key Hash Count | 1 | Number of valid public key hashes | |
| 1026 | | -| Public Key Hash(es) | 48 * n | List of valid and invalid (if any) SHA2-384 public key hashes. ECDSA: n = 4. Note: hashes must be stored with each 32-bit dword having swapped endianness | |
| 1027 | | - |
| 1028 | | -**Table: PQC Manufacturer Public Key Descriptor** {#pqc-pub-key-descriptor} |
| 990 | +| Public Key Hash(es) | 48 * n | List of valid and invalid (if any) SHA2-384 public key hashes. ECDSA: n = 4, LMS: n = 32, MLDSA: n = 4 | |
| 991 | + |
| 992 | +<br> |
| 993 | + |
| 994 | +*Table 18: Firmware manifest header* |
| 995 | + |
| 996 | +Fields are little endian unless described otherwise. |
| 1029 | 997 | |
| 1030 | 998 | | Field | Size (bytes) | Description | |
| 1031 | | -| --- | --- | --- | |
| 1032 | | -| Key Descriptor Version | 2 | Version of the Key Descriptor. The value must be 0x2 for Caliptra 2.x | |
| 1033 | | -| Key Type | 1 | Type of the key in the descriptor - 0x1 - MLDSA - 0x3 - LMS | |
| 1034 | | -| Key Hash Count | 1 | Number of valid public key hashes | |
| 1035 | | -| Public Key Hash(es) | 48 * n | List of valid and invalid (if any) SHA2-384 public key hashes. LMS: n = 32, MLDSA: n = 4. Note: hashes must be stored with each 32-bit dword having swapped endianness | |
| 1036 | | - |
| 1037 | | -**Table: Firmware manifest header** {#fw-manifest-header} |
| 1038 | | - |
| 1039 | | -| Field | Size (bytes) | Description | |
| 1040 | | -| --- | --- | --- | |
| 999 | +| ------- | -------- | ------------ | |
| 1041 | 1000 | | Revision | 8 | 8-byte version of the firmware image bundle | |
| 1042 | 1001 | | Vendor ECDSA public key hash index | 4 | The hint to ROM to indicate which ECDSA public key hash it should use to validate the active ECDSA public key. | |
| 1043 | 1002 | | Vendor LMS or MLDSA public key hash index | 4 | The hint to ROM to indicate which LMS or MLDSA public key hash it should use to validate the active public key. | |
| 1044 | | -| Flags | 4 | Feature flags. - **Bit0:** - Interpret the pl0_axi_user field. If not set, all AXI_USERs are PL1 - **Bit1-Bit31:** Reserved | |
| 1003 | +| Flags | 4 | Feature flags. <br> **Bit0:** - Interpret the pl0_axi_user field. If not set, all AXI_USERs are PL1 <br>**Bit1-Bit31:** Reserved | |
| 1045 | 1004 | | TOC Entry Count | 4 | Number of entries in TOC. | |
| 1046 | 1005 | | PL0 AXI_USER | 4 | The AXI_USER with PL0 privileges. This value is used by the RT FW to verify the caller privilege against its AXI_USER. The AXI_USER is wired through AXI. | |
| 1047 | | -| TOC Digest | 48 | SHA384 Digest of table of contents. Note: hashes must be stored with each 32-bit dword having swapped endianness | |
| 1048 | | -| Vendor Data | 40 | Vendor Data. - **Not Before:** Vendor Start Date [ASN1 Time Format] for Caliptra-issued certificates (15 bytes) - **Not After:** Vendor End Date [ASN1 Time Format] for Caliptra-issued certificates (15 bytes) - **Reserved:** (10 bytes) | |
| 1049 | | -| Owner Data | 40 | Owner Data. - **Not Before:** Owner Start Date [ASN1 Time Format] for Caliptra-issued certificate. Takes precedence over vendor start date (15 bytes) - **Not After:** Owner End Date [ASN1 Time Format] for Caliptra-issued certificates. Takes precedence over vendor end date (15 bytes) - **Reserved:** (10 bytes) | |
| 1050 | | - |
| 1051 | | -**Table: Table of contents** {#toc} |
| 1006 | +| TOC Digest | 48 | SHA384 Digest of table of contents. | |
| 1007 | +| SVN | 4 | Security Version Number for the firmware, checked against the SVN fuses. | |
| 1008 | +| Vendor Data | 40 | Vendor Data. <br> **Not Before:** Vendor Start Date [ASN1 Time Format] for Caliptra-issued certificates (15 bytes) <br> **Not After:** Vendor End Date [ASN1 Time Format] for Caliptra-issued certificates (15 bytes) <br> **Reserved:** (10 bytes) | |
| 1009 | +| Owner Data | 40 | Owner Data. <br> **Not Before:** Owner Start Date [ASN1 Time Format] for Caliptra-issued certificate. Takes precedence over vendor start date (15 bytes) <br> **Not After:** Owner End Date [ASN1 Time Format] for Caliptra-issued certificates. Takes precedence over vendor end date (15 bytes) <br> **Reserved:** (10 bytes) | |
| 1010 | + |
| 1011 | + |
| 1012 | +*Table 19: Table of contents* |
| 1013 | + |
| 1014 | +Fields are little endian unless described otherwise. |
| 1052 | 1015 | |
| 1053 | 1016 | | Field | Size (bytes) | Description | |
| 1054 | | -| --- | --- | --- | |
| 1055 | | -| TOC Entry Id | 4 | TOC Entry ID. The fields can have the following values: - **0x0000_0001:** FMC - **0x0000_0002:** Runtime | |
| 1056 | | -| Image Type | 4 | Image Type that defines the format of the image section - **0x0000_0001:** Executable | |
| 1057 | | -| Image Revision | 20 | git commit SHA1 hash of the build | |
| 1017 | +| ------- | -------- | ------------ | |
| 1018 | +| TOC Entry Id | 4 | TOC Entry ID. The fields can have the following values: <br> **0x0000_0001:** FMC <br> **0x0000_0002:** Runtime | |
| 1019 | +| Image Type | 4 | Image Type that defines the format of the image section <br> **0x0000_0001:** Executable | |
| 1020 | +| Image Revision | 20 | Git Commit hash of the build | |
| 1058 | 1021 | | Image Version | 4 | Firmware release number | |
| 1059 | | -| Image SVN | 4 | Security Version Number for the firmware, checked against the FW SVN fuses. FMC TOC entry's SVN field is ignored. | |
| 1060 | | -| Reserved. | 4 || |
| 1061 | 1022 | | Image Load Address | 4 | Load address | |
| 1062 | 1023 | | Image Entry Point | 4 | Entry point to start the execution from | |
| 1063 | 1024 | | Image Offset | 4 | Offset from beginning of the image | |
| 1064 | 1025 | | Image Size | 4 | Image Size | |
| 1065 | | -| Image Hash | 48 | SHA384 hash of image Note: hashes must be stored with each 32-bit dword having swapped endianness | |
| 1066 | | - |
| 1067 | | -#### Post-Quantum Cryptography (PQC) requirements |
| 1026 | +| Image Hash | 48 | SHA384 hash of image | |
| 1027 | + |
| 1028 | + |
| 1029 | +### Post-Quantum Cryptography (PQC) requirements |
| 1068 | 1030 | |
| 1069 | 1031 | Recent guidance from the US Government, [CNSA 2.0](https://media.defense.gov/2022/Sep/07/2003071834/-1/-1/0/CSA_CNSA_2.0_ALGORITHMS_.PDF), requests the use of LMS by 2025. Caliptra has an option to require LMS signatures in addition to ECDSA signatures (vendor and owner). |
| 1070 | 1032 | |
| @@ -1075,19 +1037,21 @@ |
| 1075 | 1037 | |
| 1076 | 1038 | Caliptra has an option starting in 2.0 to use ML-DSA-87 signatures in addition to ECDSA to support FIPS 204 and CNSA 2.0 requirements for category 5. |
| 1077 | 1039 | |
| 1078 | | -Caliptra 2.1 provides cryptographic servies to support ML-KEM (in addition to ECDH) key exchanges. |
| 1079 | | - |
| 1080 | | -#### Key rotation |
| 1081 | | - |
| 1082 | | -Firmware signing key rotation shall follow the requirements described in [Open Compute Project Secure Boot Specification](https://www.opencompute.org/documents/secure-boot-2-pdf). |
| 1083 | | - |
| 1084 | | -## Hardware |
| 1085 | | - |
| 1086 | | -Please refer to [Caliptra HW specification](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraHardwareSpecification.md) |
| 1087 | | - |
| 1088 | | -### Passive Caliptra FW Load flow |
| 1089 | | - |
| 1090 | | -{#passive-fw-load-flow} |
| 1040 | +Caliptra provides cryptographic services to support ML-KEM (in addition to ECDH) key exchanges. |
| 1041 | + |
| 1042 | +### Key rotation |
| 1043 | + |
| 1044 | +Firmware signing key rotation shall follow the requirements described in [Reference 3](#ref-3). |
| 1045 | + |
| 1046 | +# Hardware |
| 1047 | + |
| 1048 | +Please refer to Caliptra HW specification -> https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/CaliptraHardwareSpecification.md |
| 1049 | + |
| 1050 | +## Passive Caliptra FW Load flow |
| 1051 | + |
| 1052 | +*Figure 10: Passive Caliptra FW load flow* |
| 1053 | + |
| 1054 | + |
| 1091 | 1055 | |
| 1092 | 1056 | 1. After the Caliptra microcontroller is out of reset, ROM starts executing and triggers the crypto block to run the UDS decrypt flow. |
| 1093 | 1057 | 2. Caliptra ROM enables the mailbox. (Until this point, any accidental or non-accidental writes that target the mailbox are dropped by the hardware.) |
| @@ -1096,13 +1060,15 @@ |
| 1096 | 1060 | 5. Caliptra’s mailbox HW asserts an interrupt to the microcontroller after the GO is written, per mailbox protocol. See [Mailbox](#mailbox) for specifics. |
| 1097 | 1061 | 6. After Caliptra’s FW is authenticated and loaded into ICCM, microcontroller runs the firmware and asserts READY\_FOR\_RTFLOWS wire. |
| 1098 | 1062 | |
| 1099 | | -### Subsystem FW Load flow for Subsystem Mode |
| 1063 | +## Subsystem FW Load flow for Subsystem Mode |
| 1100 | 1064 | |
| 1101 | 1065 | Please see the subsystem architecture section below. |
| 1102 | 1066 | |
| 1103 | | -### CPU warm reset or PCIe hot reset flow → Caliptra IP reset {#reset-flow} |
| 1104 | | - |
| 1105 | | -{#hardare-reset-flow} |
| 1067 | +## <a id="reset-flow"></a>CPU warm reset or PCIe hot reset flow → Caliptra IP reset |
| 1068 | + |
| 1069 | +*Figure 11: Hardware reset flow* |
| 1070 | + |
| 1071 | + |
| 1106 | 1072 | |
| 1107 | 1073 | **Note:** Since Caliptra IP may be placed in an ACPI S5 domain of the device, there may be devices where Caliptra IP may not go through reset on a device hot reset or CPU warm reset. But the flow shows what happens when such a reset happens. |
| 1108 | 1074 | |
| @@ -1117,15 +1083,16 @@ |
| 1117 | 1083 | **Note:** The cold reset flow is not explicitly mentioned but it is the same as the cold boot flow because Caliptra IP has no state through a cold reset. |
| 1118 | 1084 | **Note:** Subsystem mode's warm reset flow is the same as above, except the warm reset action is triggered/managed by MCU. |
| 1119 | 1085 | |
| 1120 | | -### Random Number Generator |
| 1086 | + |
| 1087 | +## Random Number Generator |
| 1121 | 1088 | |
| 1122 | 1089 | TRNG is the digital logic and algorithms that are required for random number generation. It requires a physical entropy source input. See the Caliptra hardware specification and integration specification [here](https://github.com/chipsalliance/caliptra-rtl/blob/main/docs/) for more information on the implementation and connectivity of TRNG. |
| 1123 | 1090 | - For SoCs that want to use their own legacy TRNG, Caliptra provides a HW API to push the random number on the request/response handshake. Details on this are also available in the Caliptra hardware specification and integration specification. This mode is advised for early development but discouraged for production tape outs due to the lower security assurances of an external TRNG. |
| 1124 | 1091 | - In Subsystem mode, Caliptra integrators are required to use the internal TRNG. |
| 1125 | 1092 | |
| 1126 | | -### Mailbox |
| 1127 | | - |
| 1128 | | -The Caliptra Mailbox is a 256 KiB buffer that is used to exchange data between the SoC and the Caliptra microcontroller. |
| 1093 | +## Mailbox |
| 1094 | + |
| 1095 | +The Caliptra Mailbox is a 128 KiB buffer that is used to exchange data between the SoC and the Caliptra microcontroller. |
| 1129 | 1096 | |
| 1130 | 1097 | The SoC communicates with the mailbox over an AXI interface. This allows the SoC to identify the device that is using the interface. This ensures that the mailbox, control registers, and fuses are read or written only by the appropriate device. |
| 1131 | 1098 | |
| @@ -1135,7 +1102,7 @@ |
| 1135 | 1102 | |
| 1136 | 1103 | Mailboxes are generic data passing structures, and the Caliptra hardware only enforces the protocol for writing to and reading from the mailbox. How the command and data are interpreted by the FW and SoC are not enforced in Caliptra. |
| 1137 | 1104 | |
| 1138 | | -#### Sender protocol |
| 1105 | +### Sender protocol |
| 1139 | 1106 | |
| 1140 | 1107 | **Sending data to the mailbox:** |
| 1141 | 1108 | |
| @@ -1159,9 +1126,11 @@ |
| 1159 | 1126 | **Notes on behavior:** |
| 1160 | 1127 | After LOCK is granted, the mailbox is locked until that device has concluded its operation. The mailbox is responsible only for accepting writes from the device that requested and locked the mailbox. |
| 1161 | 1128 | |
| 1162 | | -{#mailbox-sender-flow} |
| 1163 | | - |
| 1164 | | -#### Receiver protocol |
| 1129 | +*Figure 12: Mailbox sender flow* |
| 1130 | + |
| 1131 | + |
| 1132 | + |
| 1133 | +### Receiver protocol |
| 1165 | 1134 | |
| 1166 | 1135 | Upon receiving an indication that the mailbox is populated, the appropriate device can read the mailbox. This is indicated by a dedicated wire that is asserted when Caliptra populates the mailbox for SoC consumption. |
| 1167 | 1136 | |
| @@ -1179,9 +1148,11 @@ |
| 1179 | 1148 | 1. If response data was provided, STATUS should be written to DATA\_READY. |
| 1180 | 1149 | 2. Otherwise, STATUS should be written to CMD\_COMPLETE (or CMD\_FAILURE). |
| 1181 | 1150 | |
| 1182 | | -{#mailbox-receiver-flow} |
| 1183 | | - |
| 1184 | | -#### User attributes |
| 1151 | +*Figure 13: Mailbox receiver flow* |
| 1152 | + |
| 1153 | + |
| 1154 | + |
| 1155 | +### User attributes |
| 1185 | 1156 | |
| 1186 | 1157 | The AXI_USER field of the AXI interface is used to encode device attributes for the requester that is utilizing the SoC interface. These values can be used for: |
| 1187 | 1158 | |
| @@ -1189,11 +1160,11 @@ |
| 1189 | 1160 | * Prioritizing who is next granted the LOCK. |
| 1190 | 1161 | * Mailbox user 0xFFFF_FFFF is reserved for Caliptra internal use. Caliptra firmware will fail any SoC requests from this user. |
| 1191 | 1162 | |
| 1192 | | -#### Mailbox commands |
| 1163 | +### Mailbox commands |
| 1193 | 1164 | |
| 1194 | 1165 | The Caliptra mailbox commands are specified in the [Caliptra runtime firmware specification](https://github.com/chipsalliance/caliptra-sw/blob/main/runtime/README.md#maibox-commands). |
| 1195 | 1166 | |
| 1196 | | -#### Cryptographic mailbox commands |
| 1167 | +### Cryptographic mailbox commands |
| 1197 | 1168 | |
| 1198 | 1169 | Cryptographic mailbox (CM) commands are a flexible set of mailbox commands that provide access to Caliptra's cryptographic cabilities. |
| 1199 | 1170 | This is meant for key storage and use to support protocols like SPDM and OCP LOCK. |
| @@ -1206,13 +1177,16 @@ |
| 1206 | 1177 | |
| 1207 | 1178 | The [runtime firmware specification](https://github.com/chipsalliance/caliptra-sw/blob/main/runtime/README.md#cryptographic-mailbox-commands-new-in-20) contains further details. |
| 1208 | 1179 | |
| 1209 | | -### Hash calculation HW API (Subsystem mode only) |
| 1210 | | - |
| 1211 | | -Caliptra provides a HW API to do a SHA384 hash calculation. The SoC can access the accelerator through the Caliptra FW API only in subsystem mode. Caliptra FW API uses the internal SHA accelerator and its DMA widget to hash the required data and present it back to Calitpra FW. |
| 1212 | | - |
| 1213 | | -### JTAG/TAP debug |
| 1214 | | - |
| 1215 | | -{#debug-flow} |
| 1180 | + |
| 1181 | +## Hash calculation HW API (Subsystem mode only) |
| 1182 | + |
| 1183 | +Caliptra provides a HW API to do a SHA384 hash calculation. The SoC can access the accelerator through the Caliptra FW API only in subsystem mode. Caliptra FW API uses the internal SHA accelerator and its DMA widget be hash the required data and present it back to Calitpra FW. |
| 1184 | + |
| 1185 | +## JTAG/TAP debug |
| 1186 | + |
| 1187 | +*Figure 14: Debug flow* |
| 1188 | + |
| 1189 | + |
| 1216 | 1190 | |
| 1217 | 1191 | 1. SoC drives the security state indicating that it is a debug flow. See [Caliptra security states](#caliptra-security-states) for encodings. |
| 1218 | 1192 | 2. 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. |
| @@ -1223,10 +1197,10 @@ |
| 1223 | 1197 | 7. Microcontroller executes the appropriate debug service. |
| 1224 | 1198 | 8. Specific SoC interface registers are accessible over the JTAG interface in debug (or manufacturing mode). The following are the JTAG register addresses for these registers. |
| 1225 | 1199 | |
| 1226 | | -**Table: JTAG accessible registers** {#jtag-accessible-registers} |
| 1200 | +*Table 20: JTAG accessible registers* |
| 1227 | 1201 | |
| 1228 | 1202 | | Register name | JTAG address | Accessibility | |
| 1229 | | -| --- | --- | --- | |
| 1203 | +| --------------- | -------------- | --------------- | |
| 1230 | 1204 | | MBOX_LOCK | 7'h75 | RO | |
| 1231 | 1205 | | MBOX_CMD | 7'h76 | RW | |
| 1232 | 1206 | | MBOX_DLEN | 7'h50 | RW | |
| @@ -1264,6 +1238,7 @@ |
| 1264 | 1238 | | SS_DBG_UNLOCK_LEVEL1 | 7'h73 | RW | |
| 1265 | 1239 | | SS_STRAP_CALIPTRA_DMA_AXI_USER | 7'h74 | RW | |
| 1266 | 1240 | |
| 1241 | + |
| 1267 | 1242 | Note: These are injected as TAP register read/write commands as defined in the [VeeR Specification](https://github.com/chipsalliance/Cores-VeeR-EL2). |
| 1268 | 1243 | |
| 1269 | 1244 | **Notes:** |
| @@ -1275,11 +1250,11 @@ |
| 1275 | 1250 | 5. Setting scan mode at a random time after cptra\_pwrgood: flushes out all internal Caliptra secrets, assets, key vault, and crypto intermediate state. |
| 1276 | 1251 | 6. Scan mode assertion does not automatically open Caliptra JTAG. |
| 1277 | 1252 | |
| 1278 | | -### Architectural registers |
| 1253 | +## Architectural registers |
| 1279 | 1254 | |
| 1280 | 1255 | These registers are accessible over AXI to be read according to the register access permissions. For more information, see the register reference manual at <https://ereg.caliptra.org>. |
| 1281 | 1256 | |
| 1282 | | -### Fuse requirements |
| 1257 | +## Fuse requirements |
| 1283 | 1258 | |
| 1284 | 1259 | Fuse registers are programmable whenever IP goes through reset (after cptra\_rst\_b asserts and de-asserts) and before the fuse registers are locked from writes. If the lock was set, the writes are dropped. The lock is sticky across a warm reset. |
| 1285 | 1260 | |
| @@ -1290,15 +1265,15 @@ |
| 1290 | 1265 | * For the production lifecycle state, if JTAG is enabled pre or post SoC reset, then Caliptra's dedicated fuses shall not be accessible (shall not be readable, shall not be writable) by Caliptra or other SoC IP. This restriction shall be applicable to Caliptra's fuse shadow registers as well (see [Physical Attack Countermeasures](#physical-attack-countermeasures)). |
| 1291 | 1266 | * SoC should ensure that the integrity of each fuse is maintained through the life of the part. The integrity of the fuses can be maintained by fuse redundancy, ECC, or other means determined sufficient by the SoC. |
| 1292 | 1267 | |
| 1293 | | -#### Fuse programming |
| 1294 | | - |
| 1295 | | -All fuse based cryptographic keying material and seeds (for example, UDS Seed) shall be generated (on-chip or off-chip) per requirements described in [Attestation of System Components v1.0 Requirements and Recommendations](https://www.opencompute.org/documents/attestation-v1-0-20201104-pdf). |
| 1268 | +### Fuse programming |
| 1269 | + |
| 1270 | +All fuse based cryptographic keying material and seeds (for example, UDS Seed) shall be generated (on-chip or off-chip) per requirements described in [Reference 8](#ref-8). |
| 1296 | 1271 | |
| 1297 | 1272 | SoC shall support in-field programmable fusing. [Fuse Map](#fuse-map) shows which fuses are expected to be in-field programmable. SoCs shall implement authorization for in-field programmable fusing to mitigate denial-of-service attacks. Authorization design is outside the scope of this specification. In Subsystem mode, SoC may use MCU RT FW for these actions. |
| 1298 | 1273 | |
| 1299 | 1274 | SoC shall support a field entropy programming API. The API shall support retrieving an input value from an external interface. It should cryptographically mix that value with the output of an on-die TRNG to generate the field entropy value. The API implementation shall burn the field entropy value into the first available field entropy fuse slot (or fail if no slots are available). Caliptra is expected to be in any security state. The device owner is expected to call this API in a “clean room environment” to minimize risk of attack on the programming process. In Subsystem mode, SoC may use MCU RT FW for these actions. |
| 1300 | 1275 | |
| 1301 | | -#### Fuse zeroing |
| 1276 | +### Fuse zeroing |
| 1302 | 1277 | |
| 1303 | 1278 | Caliptra assumes that the unfused value in fuses is '0' and the fused value is '1'. With this context, zeroization refers to destroying a secret value by fusing it to all ones. |
| 1304 | 1279 | |
| @@ -1312,44 +1287,48 @@ |
| 1312 | 1287 | * SoC shall ensure authorization for this API to guard against denial-of-service attacks. The authorization design is left to the vendor. |
| 1313 | 1288 | * Note: In Subsystem mode, SoC should use MCU RT FW with the corresponding subsystem HW components for these actions. |
| 1314 | 1289 | |
| 1315 | | -#### Fuse map |
| 1290 | +### Fuse map |
| 1316 | 1291 | |
| 1317 | 1292 | **FIXME:** Needs updates for Caliptra 2p0 & Subsystem |
| 1318 | 1293 | The following table describes Caliptra's fuse map: |
| 1319 | 1294 | |
| 1320 | | -**Table: Caliptra Fuse Map** {#caliptra-fuse-map} |
| 1321 | | - |
| 1322 | | -| Name | Size (bits) | ACL | Fuse programming time | Description | |
| 1323 | | -| --- | --- | --- | --- | --- | |
| 1324 | | -| UDS SEED (obfuscated) | 512 | HW read, ROM write | SoC manufacturing | DICE Unique Device Secret Seed. This seed is unique per device. The seed is scrambled using an obfuscation function. | |
| 1325 | | -| FIELD ENTROPY (obfuscated) | 256 | HW read, ROM FMC RUNTIME | Device owner in-field programmable | Field-programmable by the owner, used to hedge against UDS disclosure in the supply chain. | |
| 1295 | +*Table 21: Caliptra Fuse Map* |
| 1296 | + |
| 1297 | +| **Name** | **Size (bits)** | **ACL** | **Fuse programming time** | **Description** | |
| 1298 | +| ------------------------------- | --------------- | --------------- | ----------------------------------------------- | --------------- | |
| 1299 | +| UDS SEED (obfuscated) | 512 | ROM | SoC manufacturing | DICE Unique Device Secret Seed. This seed is unique per device. The seed is scrambled using an obfuscation function. | |
| 1300 | +| FIELD ENTROPY (obfuscated) | 256 | ROM | Device owner in-field programmable | Field-programmable by the owner, used to hedge against UDS disclosure in the supply chain. | |
| 1326 | 1301 | | VENDOR PK HASH | 384 | ROM FMC RUNTIME | SoC manufacturing | SHA384 hash of the Vendor ECDSA P384 and LMS or MLDSA Public Key Descriptors. | |
| 1327 | 1302 | | ECC REVOCATION | 4 | ROM FMC RUNTIME | In-field programmable | One-hot encoded list of revoked Vendor ECDSA P384 Public Keys (up to 4 keys). | |
| 1328 | 1303 | | OWNER PK HASH | 384 | ROM FMC RUNTIME | In-field programmable | SHA384 hash of the Owner ECDSA P384 and LMS or MLDSA Public Keys. | |
| 1329 | 1304 | | FMC KEY MANIFEST SVN | 32 | ROM FMC RUNTIME | In-field programmable | FMC security version number. (Deprecated in 2.0, will be removed in a future RTL revision.) | |
| 1330 | 1305 | | RUNTIME SVN | 128 | ROM FMC RUNTIME | In-field programmable | Firmware security version number. | |
| 1331 | 1306 | | ANTI-ROLLBACK DISABLE | 1 | ROM FMC RUNTIME | SoC manufacturing or in-field programmable | Disables anti-rollback support from Caliptra. (For example, if a Platform RoT is managing FW storage and anti-rollback protection external to the SoC.) | |
| 1332 | | -| IDEVID CERT IDEVID ATTR | 768, 352 used | ROM FMC RUNTIME | SoC manufacturing | IDevID Certificate Generation Attributes. See [IDevID certificate section]( #idevid-certificate). Caliptra only uses 352 bits. Integrator is not required to back the remaining 416 bits with physical fuses. | |
| 1307 | +| IDEVID CERT IDEVID ATTR | 768, 352 used | ROM FMC RUNTIME | SoC manufacturing | IDevID Certificate Generation Attributes. See [IDevID certificate section](#idevid-certificate). Caliptra only uses 352 bits. Integrator is not required to back the remaining 416 bits with physical fuses. | |
| 1333 | 1308 | | IDEVID MANUF HSM IDENTIFIER | 128, 0 used | ROM FMC RUNTIME | SoC manufacturing | Spare bits for Vendor IDevID provisioner CA identifiers. Caliptra does not use these bits. Integrator is not required to back these with physical fuses. | |
| 1334 | | -| LIFE CYCLE | 2 | ROM FMC RUNTIME | SoC manufacturing | **Caliptra Boot Media Integrated mode usage only**. SoCs that build with a Boot Media Dependent profile don’t have to account for these fuses. - '00 - Unprovisioned - '01 - Manufacturing - '10 - Undefined - '11 - Production **Reset:** Can only be reset on powergood. | |
| 1309 | +| LIFE CYCLE | 2 | ROM FMC RUNTIME | SoC manufacturing | **Caliptra Boot Media Integrated mode usage only**. SoCs that build with a Boot Media Dependent profile don’t have to account for these fuses.<br> - '00 - Unprovisioned <br> - '01 - Manufacturing<br> - '10 - Undefined<br> - '11 - Production<br> **Reset:** Can only be reset on powergood. | |
| 1335 | 1310 | | LMS REVOCATION | 32 | ROM | In-field programmable | One-hot encoded list of revoked Vendor LMS Public Keys (up to 32 keys). | |
| 1336 | 1311 | | MLDSA REVOCATION | 4 | ROM | In-field programmable | One-hot encoded list of revoked Vendor MLDSA Public Keys (up to 4 keys). | |
| 1337 | 1312 | | SOC STEPPING ID | 16 | ROM FMC RUNTIME | SoC manufacturing | Identifier assigned by vendor to differentiate silicon steppings. | |
| 1338 | | -| MANUF DEBUG UNLOCK TOKEN | 512 | ROM | SoC manufacturing | Digest value for manufacturing debug unlock token secret value for authorization. | |
| 1339 | | -| PQC Key Type | 2 | ROM FMC RUNTIME | In-field programmable | PQC key type for firmware validation. - 0x1 - MLDSA - 0x3 - LMS | |
| 1313 | +| MANUF_DEBUG_UNLOCK_TOKEN | 512 | ROM | SoC manufacturing | Digest value for manufacturing debug unlock token secret value for authorization. | |
| 1314 | +| PQC Key Type | 2 | ROM FMC RUNTIME | In-field programmable | One-hot encoded selection of PQC key type for firmware validation. <br> - **Bit 0** - MLDSA <br> - **Bit 1** - LMS<br> | |
| 1340 | 1315 | | SOC MANIFEST SVN | 128 | ROM FMC RUNTIME | In-field programmable | One-hot encoded value for the SOC authorization manifest minimum supported SVN. | |
| 1341 | 1316 | | SOC MANIFEST MAX SVN | 8 | ROM FMC RUNTIME | In-field programmable | Maximum value for the SOC authorization manifest SVN. | |
| 1342 | | - |
| 1343 | | -## Error reporting and handling |
| 1317 | +| HEK RATCHET SEED | 256 | ROM | In-field programmable | OCP L.O.C.K. seed used by hardware to generate HEK | |
| 1318 | + |
| 1319 | + |
| 1320 | + |
| 1321 | +# Error reporting and handling |
| 1344 | 1322 | |
| 1345 | 1323 | This section describes Caliptra error reporting and handling. |
| 1346 | 1324 | |
| 1347 | | -**Table: Hardware and firmware error types** {#hw-fw-error-types} |
| 1325 | +*Table 22: Hardware and firmware error types* |
| 1348 | 1326 | |
| 1349 | 1327 | || Fatal errors | Non-fatal errors | |
| 1350 | | -| --- | --- | --- | |
| 1351 | | -| Hardware | - ICCM, DCCM SRAM ECC. - The second watchdog (WD) timer expiry triggers an NMI, and a FATAL error is signaled to the SoC. - Operating HMAC, ECC, or DOE engines simultaneously. | - Mailbox SRAM ECC (except initial firmware load) - Mailbox incorrect protocol or commands. For example, incorrect access ordering or access without Lock. | |
| 1352 | | -| Firmware | - Control Flow Integrity (CFI) errors. - KAT errors. - FIPS Self Test errors. - Mailbox commands received after FIPS Shutdown request completes. - Hand-off errors detected upon transfer of control from ROM to FMC or FMC to Runtime. - Mailbox protocol violations leading the mailbox to an inconsistent state if encountered by ROM during cold reset flow. - Firmware image verification or authentication failures if encountered by ROM during Cold Reset flow. - Non-aligned access to ICCM or DCCM - AHB access hangs, triggered through WD timer expiry - AHB access outside of the decoding range. | - Firmware image verification or authentication failures if encountered by ROM during Update Reset flow. - Mailbox protocol violations leading the mailbox to an inconsistent state (if encountered by ROM during Update Reset flow). - Cryptography processing errors. | |
| 1328 | +| :- | - | - | |
| 1329 | +| Hardware | - ICCM, DCCM SRAM ECC.<br>- The second watchdog (WD) timer expiry triggers an NMI, and a FATAL error is signaled to the SoC.<br> - Operating HMAC, ECC, or DOE engines simultaneously. <br> | - Mailbox SRAM ECC (except initial firmware load)<br>- Mailbox incorrect protocol or commands. For example, incorrect access ordering or access without Lock. | |
| 1330 | +| Firmware | - Control Flow Integrity (CFI) errors. <br> - KAT errors. <br> - FIPS Self Test errors. <br> - Mailbox commands received after FIPS Shutdown request completes. <br> - Hand-off errors detected upon transfer of control from ROM to FMC or FMC to Runtime. <br> - Mailbox protocol violations leading the mailbox to an inconsistent state if encountered by ROM during cold reset flow. <br> - Firmware image verification or authentication failures if encountered by ROM during Cold Reset flow. <br> - Non-aligned access to ICCM or DCCM <br> - AHB access hangs, triggered through WD timer expiry <br> - AHB access outside of the decoding range <br> | - Firmware image verification or authentication failures if encountered by ROM during Update Reset flow. <br> - Mailbox protocol violations leading the mailbox to an inconsistent state (if encountered by ROM during Update Reset flow). <br> - Cryptography processing errors. | |
| 1331 | + |
| 1353 | 1332 | |
| 1354 | 1333 | **Fatal errors** |
| 1355 | 1334 | |
| @@ -1374,23 +1353,24 @@ |
| 1374 | 1353 | |
| 1375 | 1354 | Please refer to [the Caliptra code base](https://github.com/chipsalliance/caliptra-sw/blob/main/error/src/lib.rs) for a list of the error codes. |
| 1376 | 1355 | |
| 1377 | | -## Caliptra Security Subsystem |
| 1356 | +# Caliptra Security Subsystem |
| 1378 | 1357 | The Caliptra subsystem offers a complete RoT subsystem, with open source programmable components for customization of SoC boot flows. |
| 1379 | 1358 | |
| 1380 | | -{#caliptra-security-subsystem} |
| 1381 | | - |
| 1382 | | -## Caliptra Subsystem Trademark Compliance |
| 1359 | +*Figure: Caliptra security subsystem* |
| 1360 | + |
| 1361 | + |
| 1362 | +# Caliptra Subsystem Trademark Compliance |
| 1383 | 1363 | - Caliptra subsystem trademark compliance shall have Caliptra Core 2.0, Life Cycle Controller, Fuse Controller, I3C with OCP streaming boot interface, Manufacture Control Unit (MCU) and Manufacturer Control Interface (MCI) taken as is without change to ensure there is hardware transparency and consistency. |
| 1384 | 1364 | - Caliptra subsystem provides life cycle state to the SoC. |
| 1385 | 1365 | |
| 1386 | | -## SoC Integration Flexibility |
| 1366 | +# SoC Integration Flexibility |
| 1387 | 1367 | - SoC may choose to add PLLs (Phase Locked Loop for stable clock generation), SoC specific mailboxes, SoC specific firewalls & address translations, environmental circuitry as some examples. |
| 1388 | 1368 | - Caliptra subsystem provides flexibility to SoC to remap subsystem driven debug levels to SoC specific debug policies. |
| 1389 | | -- Please see Subsystem [hardware](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSHardwareSpecification.md) and [integration](https://github.com/chipsalliance/caliptra-ss/blob/main/docs/CaliptraSSIntegrationSpecification.md) specifications for additional details on subsystem configurability. |
| 1390 | | - |
| 1391 | | -## Caliptra Subsystem Architectural Flows |
| 1392 | | - |
| 1393 | | -## Subsystem (Pre-FW Load) Boot Flow |
| 1369 | +- Please see Subsystem hardware and integration specifications for additional details on subsystem configurability (FIXME: Add md versions once available; right now they are uploaded as pdfs in Caliptra-SS repository's doc folder). |
| 1370 | + |
| 1371 | +# Caliptra Subsystem Architectural Flows |
| 1372 | + |
| 1373 | +# Subsystem (Pre-FW Load) Boot Flow |
| 1394 | 1374 | |
| 1395 | 1375 | **Note:** Any step done by MCU HW/ROM would have been performed by “SoC Manager” in Caliptra 1p0. |
| 1396 | 1376 | |
| @@ -1405,7 +1385,7 @@ |
| 1405 | 1385 | 9. Caliptra will go through its boot flow of bringing up uC. |
| 1406 | 1386 | 10. Caliptra ROM starts and executes various KATs flows. |
| 1407 | 1387 | |
| 1408 | | -## Subsystem Boot Flow |
| 1388 | +# Subsystem Boot Flow |
| 1409 | 1389 | |
| 1410 | 1390 | **_If (Caliptra-Passive-Mode)_** |
| 1411 | 1391 | |
| @@ -1416,7 +1396,7 @@ |
| 1416 | 1396 | 1. Caliptra ROM waits for SoC infrastructure readiness indication. If this indication is set, Caliptra will do the identity derviation flows. If it is not set, then this flow is run when the SoC infrastructure readiness indication is set. |
| 1417 | 1397 | 2. Caliptra ROM uses the streaming boot interface to load its firmware. Please see the specific section for next level specifics; At a high level, Caliptra ROM sets the device ready in the I3C controller and poll I3C for the payloads. |
| 1418 | 1398 | 3. BMC or a similar platform component will send the image (code or data) through OCP streaming boot interface. |
| 1419 | | - 1. Caliptra ROM uses the streaming boot interface to receive 'data' from the BMC or MCU. Examples include SoC specific configuration. Caliptra ROM operation of the streaming boot interface will be identical for receiving either 'code' or 'data'. The data flow and code flow over streaming boot interface is the same from physical interface point of view and follows the OCP recovery spec for streaming boot support as implemented in Caliptra subsystem documentation (please see the recovery section). |
| 1399 | + 1.Caliptra ROM uses the streaming boot interface to receive 'data' from the BMC or MCU. Examples include SoC specific configuration. Caliptra ROM operation of the streaming boot interface will be identical for receiving either 'code' or 'data'. The data flow and code flow over streaming boot interface is the same from physical interface point of view and follows the OCP recovery spec for streaming boot support as implemented in Caliptra subsystem documentation (please see the recovery section). |
| 1420 | 1400 | 2. This need for data flow (from flash or BMC) is indicated by a SOC configuration bit to Caliptra ROM. |
| 1421 | 1401 | 3. This ‘data’ flow is possible only before SOC infra readiness is set. This is specifically used for scenarios where PUF or other characterization data is coming off-chip (say a flash or BMC). **FIXME:** Security and operations impact of this step/flow is being analyzed. This capability/flexibility will be updated or removed once that is finalized. |
| 1422 | 1402 | 4. This data must be hashed into PCR0 |
| @@ -1438,6 +1418,7 @@ |
| 1438 | 1418 | 1. The address of the MCU SRAM is provided to Caliptra’s RT FW through SOC manifest. |
| 1439 | 1419 | 2. Note: From validation front, need to ensure the Caliptra ROM and MCU are aligned in endianness. |
| 1440 | 1420 | 15. Caliptra RT FW will instruct Caliptra HW to read MCU SRAM and generate the hash (Caliptra HW will use the SHA accelerator and AXI mastering capabilities to do this) |
| 1421 | + > **Open**: Should we have a capability to do something like this for decryption too? (Key to be provided by MCU/SOC before running the decryption flow?) |
| 1441 | 1422 | 16. Caliptra RT FW will use this hash and verify it against the hash in the SOC manifest. |
| 1442 | 1423 | 17. Caliptra RT FW after verifying/authorizing the image and if it passes, it will set EXEC/GO bit into the register as specified in the previous command. This register write will also assert a Caliptra interface wire. |
| 1443 | 1424 | 1. MCU ROM will be polling the breadcrumb that the MCU SRAM has valid content and will jump to the MCU SRAM to execute from it. **NOTE:** This breadcrumb should be one of the status bits available on the MCU interface that is set by Caliptra GO bit wires. |
| @@ -1447,7 +1428,8 @@ |
| 1447 | 1428 | 20. MCU RT FW is responsible for responding to all MCTP requests. |
| 1448 | 1429 | 21. MCU RT FW will do the PLDM T5 flow, extract FW or configuration payload, use Caliptra to authenticate and deploy the rest of the images as described in run-time authentication flows. |
| 1449 | 1430 | |
| 1450 | | -{#subsystem-boot-flow} |
| 1431 | +*Figure: Subsystem Boot Flow* |
| 1432 | + |
| 1451 | 1433 | |
| 1452 | 1434 | **Common Run-time Authentication Flows** |
| 1453 | 1435 | |
| @@ -1464,7 +1446,7 @@ |
| 1464 | 1446 | |
| 1465 | 1447 | **FIXME:** Add the visio flow picture |
| 1466 | 1448 | |
| 1467 | | -## Subsystem support for Hitless Updates |
| 1449 | +# Subsystem support for Hitless Updates |
| 1468 | 1450 | |
| 1469 | 1451 | **Caliptra Hitless Update** |
| 1470 | 1452 | |
| @@ -1502,7 +1484,6 @@ |
| 1502 | 1484 | Further SoCs may require the hitless update without impacting the workloads/VMs running on the host or the VMs using the devices. This essentially means that impactless update must happen without causing any timeouts to the in-flight transactions. While the treatment of those transactions are device dependent, Caliptra subsystem must provide a way to be able to authenticate and activate the FW in the shortest time possible. |
| 1503 | 1485 | |
| 1504 | 1486 | Caliptra subsystem provides this architectural capability as follows: |
| 1505 | | - |
| 1506 | 1487 | 1. MCU provides SOC manifest to Caliptra and waits for authentication to be successful. If this wasn’t provided Caliptra will use the latest SOC manifest available. |
| 1507 | 1488 | 1. If failed, MCU uses DSP0267 PLDM for Firmware Update over MCTP to report the same to the update agent using PLDM protocol |
| 1508 | 1489 | 2. MCU stages all the incoming FW payload in an SOC-defined staging memory and provides the MMIO address of the staging SRAM to Caliptra. It is better to keep this as a part of the authenticated SOC manifest (as a configuration) from security perspective. (**FW Arch requirement:** This SOC-defined staging RAM MMIO offset which can be one for all the images or it could be per image, recommended to keep it the later way, should be defined in the SOC manifest.) |
| @@ -1513,7 +1494,7 @@ |
| 1513 | 1494 | 7. Caliptra RT FW will then set the GO bits for all the SoC FWs that are updated (vs what was already running) |
| 1514 | 1495 | 8. SoC specific logic & MCU RT FW will use this information to update the remaining FW using SoC specific architectural flows. **Note:** Since this work is mainly distribution of the FW to the destination uCs, SoC should be built to do this flow as fast as possible to meet workload non-interruption/impactless requirements. |
| 1515 | 1496 | |
| 1516 | | -## Multi-Chiplet Flows |
| 1497 | +# Multi-Chiplet Flows |
| 1517 | 1498 | |
| 1518 | 1499 | This section explain how generic FW Load Flows would function for SoCs with multiple chiplets that are required to have their security controller functions. It is plausible that a SoC is built with a single security controller active on one chiplet and that serves all other chiplets. |
| 1519 | 1500 | |
| @@ -1527,7 +1508,7 @@ |
| 1527 | 1508 | 1. Note that the indication from Caliptra for “next-image” follows the same streaming boot interface protocol. |
| 1528 | 1509 | 2. Note that to load the remaining images of a secondary tile, SOC can choose to do streaming boot flow for rest of the remaining images. Depending on the SOC architecture and chiplets, MCU RT FW may coordinate the SOC to boot in such a way that it “broadcasts” the same image to multiple chiplets that require the same image. This is a SOC optimized flow outside of Caliptra or Subsystem Context. |
| 1529 | 1510 | |
| 1530 | | -## Caliptra Subsystem I3C Streaming Boot Interface |
| 1511 | +# Caliptra Subsystem I3C Streaming Boot Interface |
| 1531 | 1512 | |
| 1532 | 1513 | The streaming boot interface is implemented as an I3C target with commands defined by the OCP Recovery specification. It will have a unique address compared to any other I3C endpoint for the device. It will comply with I3C Basic v1.1.1 specification. It will support I3C read and write transfer operations. It must support Max read and write data transfer of 1-260B excluding the command code (1 Byte), length (2 Byte), and PEC (1 Byte), total 4 Byte I3C header. Therefore, max streaming boot data per transfer will be limited to 256-byte data. |
| 1533 | 1514 | |
| @@ -1537,48 +1518,122 @@ |
| 1537 | 1518 | 2. Updating status registers based on interaction of AC-RoT and other devices |
| 1538 | 1519 | 3. Asserting / Deasserting “payload_available” & “image_activated” signals |
| 1539 | 1520 | |
| 1540 | | -## OCP Recovery Interface Hardware Specifications {#ocp-recovery-hw-specs} |
| 1541 | | - |
| 1542 | | -[OCP Recovery Document](https://docs.google.com/document/d/1Ge_w9i5A6YKG-7nlTp--JhZf6By7I9oB3oW_2_i7JbE/edit?usp=sharing) |
| 1543 | | - |
| 1544 | | -[Flashless Boot using OCP, PCIe, and DMTF Standards](https://docs.google.com/document/d/1Ge_w9i5A6YKG-7nlTp--JhZf6By7I9oB3oW_2_i7JbE/edit?usp=sharing) |
| 1545 | | - |
| 1546 | | -## Caliptra Subsystem Streaming Boot Interface Hardware |
| 1521 | +# OCP Recovery Interface Hardware Specifications |
| 1522 | + |
| 1523 | +- Reference specifications for streaming boot sequence, |
| 1524 | + - [OCP Secure Firmware recovery Spec **rev 1.1-rc6**](https://docs.google.com/document/d/1Ge_w9i5A6YKG-7nlTp--JhZf6By7I9oB3oW_2_i7JbE/edit?tab=t.0#heading=h.gjdgxs) |
| 1525 | + - [I3C core specification](https://github.com/chipsalliance/i3c-core) |
| 1526 | + - [Flashless Boot using OCP, PCIe, and DMTF Standards](https://docs.google.com/document/d/1Ge_w9i5A6YKG-7nlTp--JhZf6By7I9oB3oW_2_i7JbE/edit?usp=sharing) |
| 1527 | + |
| 1528 | +# Caliptra Subsystem Streaming Boot Interface Hardware |
| 1547 | 1529 | |
| 1548 | 1530 | Please refer to Caliptra subsystem Hardware specification. |
| 1549 | 1531 | |
| 1550 | | -## Caliptra Subsystem Streaming Boot Sequence |
| 1551 | | - |
| 1552 | | -1. **Initialization step:** Caliptra ROM initializes PROT_CAP, DEVICE_ID, DEVICE_STATUS, RECOVERY_STATUS, HW_STATUS, INDIRECT_FIFO_STATUS (remove these two reg from ROM initialization) default values. Note: Any I3C initialization is done b/w MCU ROM, I3C target HW and I3C initiator. This is not part of this document. |
| 1553 | | -2. MCU Specific SoC init of I3C & streaming boot interface. |
| 1554 | | - 1. MCU ROM can set HW_STATUS register per recovery spec, at any time based on SOC specific conditions. |
| 1555 | | - 2. MCU ROM will program DEVICE_ID register value based on associated fuse values. |
| 1556 | | - 3. I3C device must update FIFO size (1-256 Byte), Max transfer size and type of region (tie this to 0x1) to INDIRECT_FIFO_STATUS register, which could be read by BMC firmware to understand the size of the FIFO & max transfer size. |
| 1557 | | -3. Caliptra ROM will update PROT_CAP register, bit 11 to set to ‘1 “Flashless boot (From RESET)”. Caliptra ROM will set other register bits based on other recovery capabilities. PROT_CAP will also indicate support for FIFO CMS for I3C device by updating byte 10-11, bit 12 with 0x1 “FIFO CMS Support”. |
| 1558 | | -4. To start streaming boot, Caliptra ROM will write DEVICE_STATUS register to “RECOVERY_MODE” by writing byte 0, with data 0x3. Caliptra ROM will write DEVICE_STATUS register’s byte 2-3 to set the FSB parameter (0x12). |
| 1559 | | -5. I3C streaming boot HW will set byte 1 based on the DEVICE_STATUS register based on the rules defined for this register. This register status will assist BMC operation. |
| 1560 | | -6. Caliptra ROM will write via DMA assist to RECOVERY_STATUS register with data of (byte 0, 0x1) and sets the streaming boot image index to 0x0 |
| 1561 | | -7. BMC or a similar platform component will update INDIRECT_FIFO_CTRL with Component Memory Space (CMS) byte 0 with 0x0, Reset field byte 1 with 0x1 and Image size byte 2 to 5 field to size of the image. |
| 1562 | | -8. BMC or a similar platform component writes to INDIRECT_FIFO_DATA register. I3C device shall return a NACK response for any transfer that would cause the Head Pointer to advance to equal the Tail Pointer. BMC can implement flow control through NACK responses or by monitoring the FIFO space remaining via the Head and Tail Pointers. |
| 1563 | | -9. The I3C device will keep head and tail pointers along with FIFO status up to date into INDIRECT_FIFO_STATUS register. I3C streaming boot interface HW wait for an update to INDIRECT_DATA_REG with 1-256B data from BMC. |
| 1564 | | -10. If there is a write to INDIRECT_DATA_FIFO, I3C device will indicate data availability via side channel implemented as wire “payload_available” ( for more details read here) to Caliptra. Caliptra HW will latch this wire into the register for Caliptra firmware to read. |
| 1565 | | -11. Caliptra ROM arms DMA interface to read INDIRECT_FIFO_CTRL for the image size and programs DMA engine back to read the image data from INDIRECT_FIFO_DATA. |
| 1566 | | -12. Steps 9 through 11 repeat until all the images are pushed over I3C and it matches the image size initialized into the INDIRECT_FIFO_CTRL register. |
| 1567 | | -13. After the above steps, Caliptra ROM Firmware will wait for BMC to activate image indicated to Caliptra via side channel. |
| 1568 | | -14. If the Image is activated, update RECOVERY STATUS to “Booting recovery image” by writing byte0, with data 0x2. If the image is authenticated, then the Caliptra RT FW will update the image index in RECOVERY_STATUS register (0x1 in byte 0, bits 7:4) and then set then update the byte 0, bit 3:0 to “Awaiting for recovery image” (0x1) |
| 1569 | | -15. BMC or a similar platform component will send the next image as requested in the image index, and Caliptra RT FW and I3C HW go through the same flow as above. |
| 1570 | | - |
| 1571 | | -**BMC or a similar platform component requirements for recovery support** |
| 1572 | | - |
| 1573 | | -1. It should not send payload to streaming boot interface (/I3C target) device if RECOVERY_CTRL register has byte 2 indicating Image Activated. BMC must wait to clear the byte 2. (Streaming boot Interface is responsible for clearing this bye by writing 1). |
| 1574 | | -2. It must send payload to I3C target device in chunks of 256 bytes ( header (4B) + FW bytes(256B) as I3C target transfer ) only unless it is the last write for the image. Before sending the payload, it must read FIFO empty status from INDIRECT_FIFO_STATUS register. |
| 1575 | | -3. After last write for the image, it must activate the image after reading INDIRECT_FIFO_STATUS register, FIFO empty status. |
| 1576 | | - |
| 1577 | | -## Lifecycle Controller & SoC Debug Architecture |
| 1532 | +# Caliptra Subsystem Streaming Boot Sequence |
| 1533 | + |
| 1534 | + |
| 1535 | + |
| 1536 | +1. MCU ROM initializes the `PROT_CAP`, `DEVICE_STATUS`, `DEVICE_ID`, and `HW_STATUS` registers. Any other I3C initialization settings must be confirmed against I3C core specification. |
| 1537 | +2. Caliptra ROM updates the `PROT_CAP` register to set "Flashless boot (From RESET)", "FIFO CMS Support", and "Push-C-Image Support". |
| 1538 | +3. To start streaming boot, Caliptra ROM updates the `DEVICE_STATUS` register to "Recovery mode - ready to accept recovery image” for Device status byte (for the first image only) and "Flashless/Streaming Boot (FSB)" for Recovery reason codes. |
| 1539 | +4. Caliptra ROM updates the `RECOVERY_STATUS` register to "Awaiting Recovery Image" for Device recovery status and "image index" for Recovery image index. |
| 1540 | +5. BMC or a similar platform component sends an `INDIRECT_FIFO_CTRL` write command with Component Memory Space (CMS) set to 0x0, reset set to 0x1, and image size set to streaming boot image size. |
| 1541 | +6. BMC or a similar platform component sends an `INDIRECT_FIFO_DATA` write command. I3C device shall return a NACK response for any transfer that would cause the Head Pointer to advance to equal the Tail Pointer. BMC can implement flow control through NACK responses or by monitoring the FIFO space remaining via the Head and Tail Pointers. |
| 1542 | +7. The I3C device keeps head and tail pointers along with FIFO status up to date in the `INDIRECT_FIFO_STATUS` register. I3C streaming boot interface HW waits for an update to `INDIRECT_FIFO_DATA` with exactly 256 bytes of data or less if remaining image data is less than 256 bytes. BMC could send multiple commands to `INDIRECT_FIFO_DATA` register to fill the FIFO, but it must be a multiple of 4 bytes. The I3C device indicates payload availability only if the FIFO is full (256 bytes) or if BMC writes to image activation byte in `RECOVERY_CTRL` register. |
| 1543 | +8. If `INDIRECT_FIFO_DATA` has 256B available to read, I3C device indicates data availability via side channel implemented as wire `payload_available` to Caliptra. For more information, see [Requirement for payload available signal Implementation](#requirement-for-payload-available-signal-implementation). Caliptra HW latches this wire into the register for Caliptra ROM/firmware to read. |
| 1544 | +9. If `payload_available` is asserted for the first time, Caliptra ROM reads `INDIRECT_FIFO_CTRL_IMG_SIZE` for the image size. For each `payload_available` assertion including the first one, Caliptra ROM continues to read the image data from the `INDIRECT_FIFO_DATA` register until it finishes reading the data count specified as the image size. |
| 1545 | +10. Steps 8 and 9 repeat until all the image bytes are pushed over I3C and it matches the image size initialized in the `INDIRECT_FIFO_CTRL_IMG_SIZE` register. |
| 1546 | +11. When all the image bytes are received, Caliptra ROM sets `DEVICE_STATUS` to "Recovery Pending (waiting for activation)". During image authentication, `DEVICE_STATUS` register field device status remains "Recovery Pending (waiting for activation)". |
| 1547 | +12. After the above steps, Caliptra ROM/Firmware waits for BMC to activate the image. Image activation is indicated to Caliptra via either of the following methods: |
| 1548 | + - Side channel `image_activated` signal. For more information, see [Requirement for image activation signal implementation](#requirement-for-image-activation-signal-implementation). |
| 1549 | + - Caliptra ROM polls on `RECOVERY_CTRL` register for image activation status. |
| 1550 | +13. When the image is activated, Caliptra ROM updates `RECOVERY_STATUS` to “Booting recovery image” and moves to image authentication. |
| 1551 | +14. Irrespective of success or failure from image authentication (step 15 or 16), Caliptra ROM clears the image activation status before updating `RECOVERY_STATUS` & `DEVICE_STATUS` registers. |
| 1552 | +15. If the image activation is successful, and another recovery image stage is expected, then Caliptra RT firmware shall increment the “Recovery image index” in `RECOVERY_STATUS` register and set the `RECOVERY_STATUS` to indicate “Awaiting recovery image” (0x1). If no other stages are expected, then Caliptra RT firmware shall set the `RECOVERY_STATUS` to “Recovery successful”. Also, Caliptra ROM/Caliptra RT must update the `DEVICE_STATUS` register to indicate "Running Recovery Image". |
| 1553 | +16. If the image consumption fails for any reason (for example, image authentication failure), Caliptra ROM/firmware updates `RECOVERY_STATUS` register to indicate appropriate recovery status and `DEVICE_STATUS` register to "Fatal Error (Recover Reason Code not populated)". |
| 1554 | +17. BMC or a similar platform component sends the next image as requested in the image index, upon observing “Awaiting recovery image” in `RECOVERY_STATUS` register, and Caliptra RT FW and I3C HW go through the same flow as above. |
| 1555 | + |
| 1556 | +## Streaming Boot Sequence notes |
| 1557 | + |
| 1558 | +- ROM refers to I3C registers by offset, and any change to the offset results in ROM failure or unexpected behavior. |
| 1559 | +- SoC is responsible for booting the I3C Core by configuring clock frequency/sampling rate with the following registers and any other requirements specified in [I3C core specifications](https://github.com/chipsalliance/i3c-core). |
| 1560 | +- SoC is responsible for assigning static addresses to the I3C Core. |
| 1561 | +- Caliptra ROM/runtime firmware updates the `RECOVERY_STATUS` with the recovery image index. |
| 1562 | + - For recovery image index: |
| 1563 | + - `0x0`: Caliptra firmware |
| 1564 | + - `0x1`: SoC Manifest |
| 1565 | + - `0x2`: MCU firmware |
| 1566 | +- SoC/MCU ROM sets the `HW_STATUS` register per recovery spec at any time based on SoC-specific conditions. |
| 1567 | +- MCU ROM programs `DEVICE_ID` register value based on associated fuse values. |
| 1568 | +- SoC/MCU ROM initializes the `PROT_CAP`, `DEVICE_ID`, and `DEVICE_STATUS` registers. |
| 1569 | +- Caliptra ROM performs only read-modify-write (RMW) for updates to registers. |
| 1570 | +- I3C device must update FIFO size (1-256 Byte), Max transfer size and type of region (tie this to 0x1) to `INDIRECT_FIFO_STATUS` register, which could be read by BMC firmware to understand the size of the FIFO and max transfer size. |
| 1571 | +- BMC is responsible for re-sending the transaction if it fails due to PEC error. |
| 1572 | +- ALL Caliptra ROM accesses to recovery interface are completed via DMA assist. |
| 1573 | + |
| 1574 | +## Requirement for Payload Available Signal Implementation |
| 1575 | + |
| 1576 | +- **Name**: `payload_available` |
| 1577 | +- **Type**: 1 bit wire |
| 1578 | +- **Source**: Recovery Interface / I3C Core |
| 1579 | +- **Destination**: Caliptra core |
| 1580 | + |
| 1581 | +### Assertion |
| 1582 | +- The `payload_available` signal must assert under either of the following conditions: |
| 1583 | + - If the recovery FIFO indicates full (256 bytes). |
| 1584 | + - If the image activation status is asserted and the recovery FIFO indicates not empty for the last transfer. |
| 1585 | + |
| 1586 | +### De-assertion |
| 1587 | +- The `payload_available` signal must reset if recovery FIFO indicates empty. |
| 1588 | + |
| 1589 | +## Requirement for Image Activation Signal Implementation |
| 1590 | +- **Name**: `image_activated` |
| 1591 | +- **Type**: 1 bit wire |
| 1592 | +- **Source**: Recovery Interface |
| 1593 | +- **Destination**: Caliptra core |
| 1594 | + |
| 1595 | +### Assertion |
| 1596 | +- The `image_activated` signal must assert when `RECOVERY_CTRL` register byte 2 has value `0xf` (indicating image activation). |
| 1597 | + |
| 1598 | +### De-assertion |
| 1599 | +- The `image_activated` signal must deassert when the `RECOVERY_CTRL` register byte 2 has value `0x0` (indicating image activation is cleared). |
| 1600 | + |
| 1601 | +## Platform component requirements for recovery support |
| 1602 | + |
| 1603 | +1. The BMC, or a similar platform, should not send payload to streaming boot interface (/I3C target) device if `RECOVERY_CTRL` register has byte 2 indicating Image Activated. BMC must wait to clear the byte 2. (Streaming boot interface is responsible for clearing this byte by writing 1). |
| 1604 | +2. The BMC, or a similar platform, sends payload to I3C target device in chunks of 256 bytes (header (4B) + FW bytes(256B) as I3C target transfer) only, unless it is the last write for the image. Before sending the payload, it reads FIFO empty status from `INDIRECT_FIFO_STATUS` register. |
| 1605 | +3. After the last write for the image, the BMC, or a similar platform, activates the image. |
| 1606 | + |
| 1607 | + |
| 1608 | +# Life Cycle Controller & SoC Debug Architecture |
| 1578 | 1609 | |
| 1579 | 1610 | Please refer to Caliptra subsystem hardware specification. |
| 1580 | 1611 | |
| 1581 | | -## Terminology |
| 1612 | +# OCP L.O.C.K. HW Architecture and Security Claims |
| 1613 | + |
| 1614 | +Please refer to Caliptra and Caliptra subsystem hardware specification for HW implementation details and Key Vault (KV) rules. |
| 1615 | + |
| 1616 | +## Security Claims and Assumptions |
| 1617 | + |
| 1618 | +- The OCP LOCK implementation employs NIST approved algorithms (e.g., AES, SHA‑2/HMAC) |
| 1619 | +- Certain secret keys involved in OCP LOCK (HEK/HEK_SEED, de‑obf key, MEK, etc.) are never readable by firmware and are only usable by cryptographic engines or DMA via KV references. KV entries carry lock bits (lock‑write, lock‑use) that enforce non‑observability and immutability until uC reset. |
| 1620 | +- If Caliptra runtime firmware (RT FW) is compromised, it can generate an arbitrary new MEK and release it via the allowed DMA path; this does not break confidentiality of media encrypted under earlier MEKs, because ciphertext written prior to FW compromise remains bound to different keys. |
| 1621 | +- MEK generation flow is not isolated from RT FW. MEK load flow is protected from RT FW and this FW can generate a new MEK (e.g., for rotation) but cannot re‑materialize a previous MEK except by executing the OCP LOCK MEK load flow under ROM‑enabled KV rules and secrets. Recovering a MEK from its wrapped/encrypted form uses LOCK‑scoped KV slots, filtering, and AES write‑path policy; the unwrap/decryption outputs to the designated KV slot, not to FW. |
| 1622 | +- DMA offset used to send MEK is locked when the FUSE_WR_DONE is set to high and cannot be changed until the next cold boot. |
| 1623 | +- Caliptra subsystem’s security boundary ends at the Caliptra core DMA write of MEK into the required destination (offset determined through strap by integrator); confidentiality/integrity beyond that destination is the SoC owner’s responsibility. |
| 1624 | +- KV rules ensure that a KV slot can be used as AES key but cannot be used as AES plaintext or ciphertext, except for MEK encryption KV slot which has its own unique rule. |
| 1625 | +- ROM sequencing & enablement: Caliptra ROM sets OCP_LOCK_IN_PROGRESS before any RT FW OCP LOCK operation, which enables the KV filtering/isolation logic and the Key Release path; if not set, OCP LOCK data paths are disabled. If the OCP LOCK is intended to be used, Caliptra ROM MUST set the OCP_LOCK_IN_PROGRESS to high. |
| 1626 | +- The integrator sets OCP_LOCK enable strap pin (a HW tieoff pin, not modifiable by SW) at integration time and Caliptra ROM sets OCP_LOCK_IN_PROGRESS before any OCP LOCK operation, which enables the KV Slot filtering/isolation logic and the Key Release path; if not set, OCP LOCK data paths are disabled. This rule also ensures that any potential security issue comes from OCP LOCK is under the quarantine of OCP LOCK boundary and does not affect Caliptra’s rest of KV slots. However, KV 16 has a different rule because it is populated by Caliptra ROM, which sets OCP_LOCK_IN_PROGRESS bit. Thus, KV 16 is restricted with OCP_LOCK_ENABLE strap pin but not by OCP_LOCK_IN_PROGRESS. |
| 1627 | +- While OCP LOCK is in progress, AES operations cannot be abused by malicious FW to perform arbitrary AES operation into KV to exfiltrate or implant-control data if it is not for MEK decryption process and MEK decryption KV slots. KV write‑path restrictions are enforced in HW: mode check + key/slot policy; destination is forced to a designated LOCK slot; other AES ops route only to FW data‑out, not KV; write‑enable hardened to prevent mid‑transfer changes. |
| 1628 | +- DMA data FIFOs are flushed after every DMA transfer, ensuring that there is no residue data remaining from MEK after the OCP LOCK flow completion |
| 1629 | +- Caliptra top enforces mutual exclusion (BUSY checks / HW_ERROR) while LOCK flows are active; KV rules enforce single active engine for read/write correctness. |
| 1630 | +- Any KV slot that stores a secret value can be partially overwritten by the HMAC core, since HMAC writes 384 bits of a 512-bit slot. However, the HMAC core always sets the last valid d-word flag when performing this partial overwrite. This flag ensures that any remaining 128 bits in the slot are treated as invalid, preventing an adversary from exploiting the unchanged portion for pre-image recovery. If the last valid d-word flag is set for 384-bit and HMAC is triggered for 512-bit, HMAC core generates an error signal. Similarly, AES cannot perform arbitrary encryption or decryption using partially overwritten KV slots because AES keys are at most 256 bits and always start from the least significant bits (LSB) of the slot. Since HMAC writes a minimum of 384 bits, any AES operation will necessarily use the updated portion of the slot, not any stale data. The same KV slot may also be reused for ML-KEM or ECC operations. These are asymmetric cryptographic operations where the secret is either a private key or a seed used to derive the private key. Partial overwrites do not expose these secrets. While it could be argued that such secrets might be manipulated to sign arbitrary data or perform unauthorized decapsulation, these operations can only occur after ROM execution—at which point Caliptra secrets are either cleared or locked, eliminating this risk. OCP LOCK utilizes ML-KEM and ECDH for the key wrapping operations however these operations do not go through KV and managed by RT FW and thus these are out of scope of this partial write feature. |
| 1631 | +- MEK, HEK seed, MEK encryption key cannot be copied. This is an important isolation guarantee. |
| 1632 | +- Single-encrypted ("obfuscated") MEK is exposed to RT FW of Caliptra. If malicious firmware gains access to the obfuscated MEK it can successfully derive the MEK to KV23 and release it to the SSD controller without requiring any other security inputs (Access Keys, MPK, EPK, etc). Firmware must clear it from memory immediately after use. |
| 1633 | + |
| 1634 | + |
| 1635 | + |
| 1636 | +# Terminology |
| 1582 | 1637 | |
| 1583 | 1638 | The following acronyms and abbreviations are used throughout this document. |
| 1584 | 1639 | |
| @@ -1627,7 +1682,19 @@ |
| 1627 | 1682 | | <a id="MCI"></a>**MCI** | Manufacturer Control Interface | |
| 1628 | 1683 | |
| 1629 | 1684 | |
| 1630 | | -# Acknowledgements |
| 1685 | +# References |
| 1686 | + |
| 1687 | +1. <a id="ref-1"></a>NIST Special Publication 800-193 Platform Firmware Resiliency Guidelines |
| 1688 | +2. <a id="ref-2"></a>Global Platform Technology Root of Trust Definitions and Requirements Version 1.1 Public |
| 1689 | +3. <a id="ref-3"></a>[Open Compute Project Secure Boot Specification](https://www.opencompute.org/documents/secure-boot-2-pdf) |
| 1690 | +4. <a id="ref-4"></a>TCG DICE Layering Architecture Version 1.0 Revision 0.19 July 23, 2020 |
| 1691 | +5. <a id="ref-5"></a>TCG DICE Attestation Architecture Version 1.00 Revision 0.23 March 1, 2021 |
| 1692 | +6. <a id="ref-6"></a>TCG Hardware Requirements for a Device Identifier Composition Engine Family “2.0” Level |
| 1693 | +7. <a id="ref-7"></a>[Side-Channel Attacks: Ten Years After Its Publication and the Impacts on Cryptographic Module Security Testing](https://csrc.nist.gov/csrc/media/events/physical-security-testing-workshop/documents/papers/physecpaper19.pdf) |
| 1694 | +8. <a id="ref-8"></a>[Attestation of System Components v1.0 Requirements and Recommendations](https://www.opencompute.org/documents/attestation-v1-0-20201104-pdf) |
| 1695 | +9. <a id="ref-9"></a>OCP Security WG: Ownership Transfer |
| 1696 | + |
| 1697 | +# Acknowledgments |
| 1631 | 1698 | |
| 1632 | 1699 | The Caliptra Workgroup acknowledges the following individuals for their contributions to this specification. |
| 1633 | 1700 | |
| @@ -1642,17 +1709,22 @@ |
| 1642 | 1709 | * Bharat Pillilli (Microsoft) |
| 1643 | 1710 | * Bryan Kelly (Microsoft) |
| 1644 | 1711 | * Caleb Whitehead (Microsoft) |
| 1712 | +* Clayton Kuchta (Microsoft) |
| 1713 | +* Emre Karabulut (Microsoft) |
| 1645 | 1714 | * Howard Tran (Google) |
| 1646 | 1715 | * James Zhang (NVIDIA) |
| 1647 | 1716 | * Jeff Andersen (Google) |
| 1648 | 1717 | * John Traver (AMD) |
| 1649 | 1718 | * Jordan Hand (Google) |
| 1719 | +* Kiran Upadhyayula (Microsoft) |
| 1650 | 1720 | * Kor Nielsen (Google) |
| 1651 | 1721 | * Louis Ferraro (AMD) |
| 1652 | 1722 | * Marius Schilder (Google) |
| 1653 | 1723 | * Matt Cockrell (Google) |
| 1654 | 1724 | * Michael Norris (Microsoft) |
| 1725 | +* Mojtaba Bisheh Niasar (Microsoft) |
| 1655 | 1726 | * Nathan Nadarajah (AMD) |
| 1727 | +* Nilesh Patel (Microsoft) |
| 1656 | 1728 | * Norman Stewart (AMD) |
| 1657 | 1729 | * Paul Chou (NVIDIA) |
| 1658 | 1730 | * Piotr Kwidzinski (AMD) |
| @@ -1665,11 +1737,13 @@ |
| 1665 | 1737 | * Vishal Soni (Microsoft) |
| 1666 | 1738 | * Vishal Mhatre (Microsoft) |
| 1667 | 1739 | |
| 1740 | +# Footnotes |
| 1741 | + |
| 1668 | 1742 | [^1]: Caliptra is Spanish for “root cap” and describes the deepest part of the root. |
| 1669 | 1743 | |
| 1670 | 1744 | [^2]: This obfuscation key may be a chip-class secret, or a chip-unique PUF, with the latter preferred. |
| 1671 | 1745 | |
| 1672 | | -[^3]: This memory should only be volatile in a power loss event. See details in the [reset flow section](#sec:reset-flow). |
| 1746 | +[^3]: This memory should only be volatile in a power loss event. See details in the [reset flow section](#reset-flow). |
| 1673 | 1747 | |
| 1674 | 1748 | [^4]: When a hitless update occurs, and then following reset, Caliptra shall execute the updated firmware and shall maintain the measurements that it collected during boot. Caliptra shall support the reporting of these measurements with signed attestations. Hitless update of Caliptra’s FMC shall not be supported. Hitless update requires creating a new DICE identity, which would require access to IDevID and LDevID. Retention of IDevID and LDevID (privkeys) during post-boot introduce a security vulnerability. |
| 1675 | 1749 | |