# Open Profile for DICE v2.3 [TOC] ## Background The Trusted Computing Group (TCG) specifies [Hardware Requirements for a Device Identifier Composition Engine](https://trustedcomputinggroup.org/wp-content/uploads/Hardware-Requirements-for-Device-Identifier-Composition-Engine-r78_For-Publication.pdf) (DICE) which provides the context for this document. We'll call this TCG document the _TCG DICE specification_. Concepts like a Unique Device Secret (UDS) and a Compound Device Identifier (CDI) are used as defined in the TCG DICE specification. #### A Note on Nomenclature This document uses the term _hardware_ to refer to anything that is immutable by design after manufacturing. Code in mask ROM, for example, is _hardware_. The terms _firmware_, _software_ and _program_ are all interchangeable; they all refer to mutable code. Often we say _firmware_ for code that runs early in boot, and _program_ for a particular unit of code, but it's really all _software_. #### DICE Primer For those not familiar with DICE, here is a quick primer on the concepts: * **UDS** - Unique Device Secret. This is a per-device hardware-level secret accessible to the DICE but not accessible after the DICE runs. This is one of the DICE inputs. Note that when [layering](#layering-details) DICE computations the UDS is only used for the first computation when transitioning from hardware to software. Mutable software must never have access to the hardware UDS. * **CDI** - Compound Device Identifier. This value represents the hardware/software combination measured by the DICE. This is the DICE output and is passed to the software which has been measured. This is a secret. * **DICE** - Device Identifier Composition Engine. This is a process which mixes the UDS with software hashes and other inputs to produce a CDI and locks down further access to the UDS. This computation occurs at the point of transition from hardware (e.g. ROM) to software (e.g. first bootloader), but we can perform the same computation at the point of transition from one program to another in general to extend CDIs throughout a system. DICE can be implemented with a simple HMAC with the UDS as the key, attributes of the target code or system as the input, and the output is the CDI. However, for a particular implementation there are questions that need to be addressed such as "what is in the input, exactly?", and "how should we use the CDI once we have it?". That's where this profile comes in, it fills in many of these details. ## Overview This document specifies a DICE profile suitable for use in a variety of products and platforms. The [TCG DICE specification](#background) intentionally allows for flexibility in implementation; this document specifies many of these implementation details. This document also fills in various details the TCG DICE specification considers out of scope. In particular, this document specifies: * Cryptographic mechanisms * UDS size and provisioning * DICE input details, including how DICE interacts with verified boot * Additional requirements, including asymmetric key derivation and certification #### Goals The main goals of this document are: * Make it **easier to implement** DICE well, with quality and confidence. * **Consistency for DICE implementers**, whether in hardware, firmware, or software. * **Consistency for attestation verifiers**. There will always be some details in the certificate extensions that are specific to the target system, but those differences can be minimized by adopting some conventions when generating the certificates. #### Non-Goals This document is not intended to: * Be a formal standard * Limit the use of DICE-style mechanisms not described here ## Architecture Diagram This architecture diagram shows the first DICE transition from hardware to software, and uses the UDS in the derivation of both the Attestation CDI and Sealing CDI. Subsequent DICE transitions would use the current CDI values in place of the UDS to compute the subsequent CDI values. See [Layering Details](#layering-details).  ## Use Cases This design is motivated by two use cases: **attestation** and **sealing**. _Attestation_ allows a computing device or program to provide verifiable evidence of its identity and operating state, including hardware identity, software image, security-relevant configuration, operating environment, etc. _Sealing_ allows a computing device or program to encrypt data in such a way that it can only be decrypted by the same device or program operating in the same state as at the time of encryption. With this design, sealing only works well in combination with some kind of verified boot system. For a more sophisticated example of sealing key generation, see [Appendix C: Versioned Sealing Keys](#appendix-c-versioned-sealing-keys). # Profile Design ## Input Values For attestation, DICE inputs should represent all security-relevant properties of the target program. The target program is the program to which control will be passed, along with DICE outputs, after the DICE computations are complete. This profile defines the following types of input, each of which is represented by a fixed length value: 1. **Code (64 bytes)** - This input is computed by hashing the target code. This is the traditional input described most clearly in the [TCG DICE specification](#background). If a software image is too large to load and hash entirely, then a descriptor of the code (like the root hash of a hash tree) may be used instead. Note that this approach requires additional ongoing enforcement to verify pages as they are loaded. A canonical example of this is [dm-verity](https://source.android.com/security/verifiedboot/dm-verity). 2. **Configuration Data (64 bytes)** - This input is a catch-all for any security-relevant configuration or environment properties that characterize the integrity of the system and can be used by an external party to validate its identity and/or its operating state. This may capture verified boot authority selection, device mode, boot location, chip status information, instance identifiers, etc. This value may or may not be a hash of the actual configuration data. When it is a hash, the original data must also be included in certificates. It's ok for this input to be _not stable_, it may change from one boot to the next. 3. **Authority Data (64 bytes)** - This input is computed by hashing a representation of the verified boot trusted authority. For example, this may be a public key, a hash of a public key, or a hash of a descriptor containing a set of public keys. For many SoCs, this representation of the trusted authority is programmed into one-time-programmable (OTP) memory. If a code authorization mechanism is disabled or not supported, this input should be 64 zero bytes. If multiple public keys are supported with runtime selection, this input value must represent all of them. (This is so the value remains stable across a key change, the actual key that was used during boot should be included in the configuration data input value). The authority input value is designed to be stable, it is very unlikely to change during a device lifecycle. 4. **Mode Decision (1 byte)** - This input value is a single-byte mode value. Valid mode values are: **0**: Not Configured, **1**: Normal, **2**: Debug, **3**: Recovery. The mode is determined at runtime based on the other inputs, and only the other inputs. This input is designed to capture a configuration signal in a stable way, and to reflect important decisions a device makes at runtime. In the sealing use case, this enables data to be sealed separately under each mode. See [Mode Value Details](#mode-value-details). 5. **Hidden Inputs (64 bytes)** - This optional input value is _hidden_ in the sense that it does not appear in any certificate. It is used for both attestation and sealing CDI derivation so it is expected to be stable; it should not change under normal operation except when that change is an intentional part of the device lifecycle. If not used, this value should be all zero bytes. While this value can be anything, intended use cases include: * Mixing in an additional secret which may be changed as part of the device lifecycle, for example ownership transfer * Mixing in a rotation nonce or counter to control the rotation of attestation keys and sealing keys * Mixing in stable instance IDs or other internal IDs which may provide differentiation for sealing CDIs * Mixing in stable configuration inputs which appear in Configuration Data but also should be used in the sealing CDI derivation ## CDI Values The [TCG DICE specification](#background) refers to a single CDI, but this profile defines multiple CDIs with different characteristics which can be used for different use cases: 1. **Attestation CDI** - This CDI is derived from the combination of all input values and will change across software updates or configuration changes. This CDI is appropriate for attestation and is _mandatory_ for implementations of this profile. 2. **Sealing CDI** - This CDI is derived from only the authority data, mode decision, and hidden inputs because these are stable. It will reflect this stability and will remain the same across software updates and some configuration changes. This CDI is appropriate for sealing and is _optional_ for implementations of this profile. ### CDI Certificates This profile requires the generation of a CDI certificate as part of the DICE flow. The subject key pair is derived from the Attestation CDI value for the target code. The authority key pair which signs the certificate is derived from the UDS or, after the initial hardware to software transition, from the Attestation CDI value for the current code (see [Layering Details](#layering-details)). The DICE flow outputs the CDI values and the generated certificate; the private key associated with the certificate may be optionally passed along with the CDI values to avoid the need for re-derivation by the target code. The UDS-derived public key is certified by an external authority during manufacturing to complete the certificate chain. See [Certificate Details](#certificate-details). As an example, if the CDI private key were used to sign a leaf certificate for an attestation key, the certificate chain may look like this:  ## High-level DICE Flow The [TCG DICE specification](#background) outlines a four stage flow: measure, compute CDI, lock UDS, and transfer control. This profile expands on this to include operations for CDI certification. The expanded flow has the following steps: 1. Measure CDI input values and compute CDI values 2. Derive an asymmetric key pair from the UDS 3. Lock UDS 4. Derive an asymmetric key pair from the Attestation CDI 5. Generate a CDI certificate 6. Destroy the UDS-derived private key from step (2) 7. Transfer control to the target code, passing on the certificate and all CDI values ## Cryptography This profile requires three cryptographic primitives: a hash function, a key derivation function, and an asymmetric digital signature. The recommended defaults are [SHA-512](https://en.wikipedia.org/wiki/SHA-2), [HKDF](https://en.wikipedia.org/wiki/HKDF) (using SHA-512) and [Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519). Since Ed25519 uses SHA-512 under the hood, using this combination means implementing only one hash function. See below for the full list of [acceptable algorithms](#acceptable-cryptographic-algorithms). The following pseudocode operations are used throughout this document: ```py # A hash function. The input can be any length. hash = H(input) # Random salt values used as the 'salt' KDF argument (hex encoded). ASYM_SALT = 63B6A04D2C077FC10F639F21DA793844356CC2B0B441B3A77124035C03F8E1BE 6035D31F282821A7450A02222AB1B3CFF1679B05AB1CA5D1AFFB789CCD2B0B3B ID_SALT = DBDBAEBC8020DA9FF0DD5A24C83AA5A54286DFC263031E329B4DA148430659FE 62CDB5B7E1E00FC680306711EB444AF77209359496FCFF1DB9520BA51C7B29EA # A KDF operation with the given desired output length, input key material, # salt, and info. output = KDF(length, ikm, salt, info) # An asymmetric key pair derivation, either Ed25519 or ECDSA. # * The private key is derived using KDF(32, input, ASYM_SALT, "Key Pair"). # * The public key is derived from the private key (per the chosen algorithm). private_key, public_key = ASYM_KDF(input) ``` ### Computing CDI Values Each CDI value is 32 bytes in length and is computed using a KDF operation with the UDS or previous CDI value as the input key material argument and the relevant input measurement as the salt argument. The KDF info argument differs for each type of CDI. #### Attestation CDI The Attestation CDI input measurement is derived from the combination of all input values. The [input values](#input-values) are hashed in this order: code, config, authority, mode, hidden. ```py CDI_Attest = KDF(32, UDS, H(code + config + authority + mode + hidden), "CDI_Attest") ``` #### Sealing CDI The Sealing CDI input measurement is similar but is derived from only the stable inputs. The [input values](#input-values) are hashed in this order: authority, mode, hidden. ```py CDI_Seal = KDF(32, UDS, H(authority + mode + hidden), "CDI_Seal") ``` ### Deriving Asymmetric Key Pairs There are two key pair derivations; one to derive from the UDS, and the other to derive from the Attestation CDI. When deriving from the UDS, the KDF input is simply the UDS. ```py UDS_Private, UDS_Public = ASYM_KDF(UDS) ``` When deriving from Attestation CDI, the KDF input is simply the [CDI\_Attest](#attestation-cdi) value. ```py CDI_Private, CDI_Public = ASYM_KDF(CDI_Attest) ``` Note: It is important that these two derivations remain consistent except for the input key material; this is what makes [layering](#layering-details) possible. ### Deriving Identifiers There are a few cases where the DICE needs to generate an identifier for use in certificates. To ensure these identifiers are deterministic and require no additional DICE inputs, the identifiers are derived from the associated public key. The identifiers are 20 octets so they fit in the RFC 5280 serialNumber field constraints and the X520SerialNumber type when hex encoded. The big-endian high-order bit is cleared so the ASN.1 integer representation is always positive without padding. ```py UDS_ID = KDF(20, UDS_Public, ID_SALT, "ID") CDI_ID = KDF(20, CDI_Public, ID_SALT, "ID") ``` Note: Like the public key derivations, it is important that the ID derivations remain consistent except for the input key material. This is because these are used in certificate issuer and subject fields and need to match when [layering](#layering-details). ### Acceptable Cryptographic Algorithms #### Hash Algorithms Acceptable hash algorithms are: * SHA-256, SHA-384, SHA-512 * SHA3-256, SHA3-384, SHA3-512 #### Key Derivation Functions ##### HKDF [HKDF](https://en.wikipedia.org/wiki/HKDF) can be used with any acceptable hash algorithm. The KDF inputs map exactly to HKDF parameters, by design. This is the recommended default. ##### DRBG A [DRBG](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf) can be used to implement the KDF operation. Depending on the DRBG implementation this may require UDS and CDI values larger than 256 bits to provide both _nonce_ and _entropy_ inputs when instantiating the DRBG. The DRBG should be instantiated with a security strength of 256 bits. The sequence of DRBG functions {instantiate, generate, uninstantiate}, are used as a KDF operation. The mapping of inputs is as shown in the following table. HKDF Input | Corresponding DRBG Input ---------- | ------------------------------------ ikm | Instantiate: Entropy Input and Nonce salt | Generate: Additional Input info | Instantiate: Personalization String ##### OpenTitan Key Manager The [OpenTitan Key Manager](https://docs.opentitan.org/hw/ip/keymgr/doc/index.html) can be used as a KDF. See the OpenTitan documentation for details. #### Digital Signatures ##### Ed25519 [Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) is the recommended default. ##### ECDSA [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) can be used instead of Ed25519. When signing the CDI certificate, the random _k_ required by ECDSA may be generated deterministically per [RFC6979](https://tools.ietf.org/html/rfc6979). One weakness of Ed25519 is that implementations may be susceptible to error injection ([example](https://www.romailler.ch/ddl/10.1109_FDTC.2017.12_eddsa.pdf)). Another disadvantage of Ed25519 is that it is not [currently] FIPS 140-2 certifiable. In any case, either algorithm is acceptable for this profile. The following [NIST](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf) curves are acceptable for use with ECDSA: * P-256 * P-384 ## Layering Details This DICE profile is designed to be layered. That is, software that receives CDI values can in turn execute a DICE flow using those CDI values in place of the UDS value. The certificate generated by the next DICE layer can chain to the certificate generated by the previous DICE layer because the asymmetric key derivation is consistent across layers for authority and subject keys. ### Computing Layered CDI Values When computing CDI values, the previous Attestation CDI or Sealing CDI is used as the input key material instead of the hardware UDS: ```py CDI_Attest[n+1] = KDF(32, CDI_Attest[n], H(code + config + authority + mode + hidden), "CDI_Attest") CDI_Seal[n+1] = KDF(32, CDI_Seal[n], H(authority + mode + hidden), "CDI_Seal") ``` ### Protecting Layered CDI Values Just like the UDS is locked in the DICE [flow](#high-level-dice-flow), previous layer CDIs must be destroyed, locked, or otherwise protected before control is passed to the next layer. Layer[n+1] must never obtain access to CDI[n] values and must not be able to use CDI[n] in any computation. For example, a layer[n] program cannot offer a service that uses CDI[n] to layer[n+1] programs. In some cases a layer[n] program will stay active and spawn multiple programs (for example, a kernel, TEE, or hypervisor). In these cases the CDI[n] values must be protected from all layer[n+1] programs for the duration they are in operation, and must be destroyed when no longer needed. ### Generating Layered Certificates When generating certificates, the authority is the previous CDI key pair and the certificates chain together. So the certificate chain may look like this:  ## UDS Details ### Requirements In addition to the requirements described in the [TCG DICE specification](#background), this profile requires the following: * The UDS is at least 256 bits in size and is full-entropy. This means the UDS value has been conditioned from at least 512 bits of entropy. * If a UDS has not been provisioned, a value of all zero bytes is used. This convention enables provisioning testability since running a DICE on an unprovisioned UDS will yield predictable outputs. * UDS values and certificates must use one of the provisioning schemes described in this section. The provisioning process is expected to occur very seldom, likely once per device during manufacture. Hardware may or may not support re-provisioning of the UDS. ### Provisioning Scheme 1: Pre-generation In this scheme, the UDS and an associated certificate are pre-generated and injected during a manufacturing process in a controlled environment appropriate for the implementation or product. The pre-generation infrastructure does not retain UDS values after provisioning. This approach is designed to balance the risks and costs associated with provisioning between security and scale. Rationale is not described here in detail, but the primary benefits are: * No in-factory CAs (which make revocation as difficult as pre-generation) * On-device certificates (which enable offline use cases) Note: If the UDS is integrated with an SoC at the time of SoC manufacture, the issuer may be the SoC vendor. If the UDS is integrated at the time of device manufacture, the issuer may be the OEM. #### Provisioning Flow 1. [Pre-generation] Generate a random UDS 2. [Pre-generation] Derive UDS\_Public and generate an associated certificate which has a subject matching the expected issuer field generated for CDI certificates (see [X.509 UDS Certificates](#x_509-uds-certificates)). 3. [Manufacturing] Program the UDS to the hardware (and destroy the source copy) 4. [Manufacturing] Test the DICE to ensure: 1. The UDS certificate correctly chains to the CDI certificate 2. The CDI values cannot be reproduced using a zero UDS 5. [Manufacturing] Write the certificate to device storage ### Provisioning Scheme 2: Factory CA In some cases, it may be feasible and preferable to install a CA for UDS provisioning during an SoC or device manufacturing stage. In this scheme, the UDS is derived on-chip from internal and external entropy, at least 256 bits each. Internal entropy may be generated using a [PUF](https://en.wikipedia.org/wiki/Physical_unclonable_function), or generated once using an internal hardware RNG and stored, for example, in OTP memory. External entropy is injected once during manufacturing and stored, for example, in OTP memory. The UDS is derived at runtime on every boot from the combined entropy. The UDS derivation (i.e. conditioning) from internal and external entropy uses a KDF: ```py UDS = KDF(32, internal_entropy, external_entropy, "UDS") ``` With this provisioning scheme, the device must output UDS\_Public so provisioning software can read the public key and issue a certificate. #### Provisioning Flow All steps occur during manufacturing. 1. Generate and inject external entropy; do not retain or inject to multiple devices 2. Run the DICE flow and read the UDS\_Public key 3. Issue a certificate for UDS\_Public 4. Test the DICE to ensure: 1. The UDS certificate correctly chains to the CDI certificate 2. The CDI values cannot be reproduced using a zero UDS 5. Write the certificate to device storage ### Provisioning Scheme 3: On-Demand Certification In some cases, the certificate may not need to be stored on the device or the device may not be capable of storing a certificate. In this scheme the UDS is derived in the same way as [Provisioning Scheme 2](#provisioning-scheme-2-factory-ca), and the UDS\_Public key must similarly be output by the device. A SHA-512 hash of the UDS\_Public key is retained in a secure database by the manufacturer. The manufacturer then operates or coordinates with an online CA to provide on-demand certification of UDS public keys. Acceptable approaches include but are not limited to: * Manufacturer provides the list of UDS public key hashes to the CA. This has the downside of revealing the total number of devices. * Manufacturer operates a simple web service on a dedicated domain over HTTPS which takes as input the hash of a UDS public key and provides as output a boolean indicating whether or not the hash is valid and should be certified. The CA issues certificates for any valid UDS public key without requiring proof-of-possession from the caller, only requiring a signal of approval from the manufacturer. This allows a certificate chain to be requested by a CDI certificate verifier that received an incomplete chain from a device. The UDS certificate may be cached indefinitely by the device or by a verifier. #### Provisioning Flow 1. [Manufacturing] Generate and inject external entropy; do not retain or inject to multiple devices 2. [Manufacturing] Run the DICE flow and read the UDS\_Public key 3. [Manufacturing] Retain H(UDS\_Public) in a secure database 4. [On-Demand] Send UDS\_Public to the CA (no proof-of-possession necessary) 5. [CA] Check that H(UDS\_Public) is approved by the manufacturer 6. [CA] Issue a certificate for UDS\_Public ## Mode Value Details The following table describes the semantics of each mode. Mode | Value | Description -------------- | ----- | ----------- Not Configured | 0 | This mode indicates that at least one security mechanism has not been configured. This mode also acts as a catch-all for configurations which do not fit the other modes. Invalid mode values -- values not defined here -- should be treated like this mode. Normal | 1 | This mode indicates the device is operating normally under secure configuration. This may mean, for example: Verified boot is enabled, verified boot authorities used for development or debug have been disabled, debug ports or other debug facilities have been disabled, and the device booted software from the normal primary source, for example, eMMC, not USB, network, or removable storage. Debug | 2 | This mode indicates at least one criteria for Normal mode is not met and the device is not in a secure state. Recovery | 3 | This mode indicates a recovery or maintenance mode of some kind. This may mean software is being loaded from an alternate source, or the device is configured to trigger recovery logic instead of a normal boot flow. ## Configuration Input Value Details (Optional) The format and meaning of the 64-byte configuration input value is implementation dependent and may be a hash of more configuration data. Implementers may choose to use the following convention for the configuration input which covers a set of common security-relevant configuration. Field | Byte/Bits (MSB=0) | Description ------------------------------- | ----------------- | ----------- Verified Boot Enabled | 0/0 | This bit indicates whether a verified boot feature is enabled. The bit is set if enabled, clear if disabled or not supported. Verified Boot Authority Enabled | 0/1-7 | These bits indicate which of the verified boot authorities available are enabled. The bit is set if the authority is enabled, clear if disabled. If a verified boot system is disabled or not supported, all bits are clear. The mapping of these bits to particular authorities is implementation dependent. Debug Ports Enabled | 1 | The bits of this byte each indicate that a debug port or feature is enabled. A bit is set if the port or feature is enabled, clear if disabled. The mapping of these bits to particular ports or features is implementation dependent. Boot Source | 2 | This value indicates the boot source; that is, where the target software was loaded from. The mapping of this value to particular boot sources is implementation dependent but by convention 0 is used for the default boot source. Version | 3-4 | This value encodes target software version information. The format and interpretation of this value is implementation dependent. Reserved | 5-31 | These are reserved for future versions of this profile. Implementation Specific | 32-63 | An implementation can use these bytes to represent any other security-relevant configuration. ## Certificate Details This profile allows for two certificate options: standard X.509, or CBOR. The certificate type does not need to be consistent for all certificates in a certificate chain. Any certificate in the chain may be any type. Attestation infrastructure may place additional constraints on certificate type, but this profile does not. Regardless of type, UDS and CDI certificates are always semantically _CA certificates_ to enable use cases for certifying subsequent DICE [layers](#layering-details) or certifying attestation keys of some kind; the UDS\_Private and CDI\_Private keys are not intended to be used for any purpose other than signing certificates. In particular, this means CDI\_Private should not participate directly in attestation protocols, but should rather certify an attestation key. If a target software component does not launch additional software, the _pathLenConstraint_ field can be set to zero so certification of a subsequent CDI\_Public is not possible. When UDS and CDI certificates are standard X.509 certificates, they follow the profile specified in [RFC 5280](https://tools.ietf.org/html/rfc5280). When they are CBOR, they follow the IETF [CBOR Web Token](https://tools.ietf.org/html/rfc8392) (CWT) specification, and the [CBOR Object Signing and Encryption](https://tools.ietf.org/html/rfc8152) (COSE) specification. ### X.509 UDS Certificates The following table describes all standard fields of a UDS certificate's tbsCertificate field that this profile requires. Fields omitted are implementation dependent, but must not break the ability to chain to a CDI Certificate. Field | Description -------------------- | ----------- version | v3 subject | "SERIALNUMBER=\" where UDS\_ID is hex encoded lower case subjectPublicKeyInfo | When using Ed25519, the info per [RFC 8410](https://tools.ietf.org/html/rfc8410) and [RFC 8032](https://tools.ietf.org/html/rfc8032) extensions | The standard extensions described below are included. ##### UDS Standard Extensions Extension | Critical | Description -------------------- | ------------ | ----------- subjectKeyIdentifier | non-critical | Set to UDS\_ID keyUsage | critical | Contains only keyCertSign basicConstraints | critical | The cA field is set to TRUE. The pathLenConstraint field is normally not included, but may be included and set to zero if it is known that no additional DICE [layers](#layering-details) exist. ### X.509 CDI Certificates All standard fields of a CDI certificate and the tbsCertificate field are described in the following table. Notably, this certificate can be generated deterministically given a CDI\_Public key and the DICE input value details. Field | Description -------------------- | ----------- signatureAlgorithm | id-Ed25519 per [RFC 8410](https://tools.ietf.org/html/rfc8410) signatureValue | 64 byte Ed25519 signature per [RFC 8032](https://tools.ietf.org/html/rfc8032), using UDS\_Private or a previous CDI\_Private as the signing key version | v3 serialNumber | CDI\_ID in ASN.1 INTEGER form signature | id-Ed25519 per [RFC 8410](https://tools.ietf.org/html/rfc8410) issuer | "SERIALNUMBER=\" where UDS\_ID is hex encoded lower case validity | The DICE is not expected to have a reliable source of time when generating a certificate. The validity values are populated as follows: _notBefore_ can be any time known to be in the past; in the absence of a better value, "180322235959Z" can be used which is the date of publication of the [TCG DICE specification](#background), and _notAfter_ is set to the standard value used to indicate no well-known expiry date, "99991231235959Z". subject | "SERIALNUMBER=\" where CDI\_ID is hex encoded lower case subjectPublicKeyInfo | When using Ed25519, the info per [RFC 8410](https://tools.ietf.org/html/rfc8410) and [RFC 8032](https://tools.ietf.org/html/rfc8032) issuerUniqueID | Omitted subjectUniqueID | Omitted extensions | Standard extensions are included as well as a custom extension which holds information about the measurements used to derive CDI values. Both are described below. ##### CDI Standard Extensions Extension | Critical | Description ---------------------- | ------------ | ----------- authorityKeyIdentifier | non-critical | Contains only keyIdentifier set to UDS\_ID subjectKeyIdentifier | non-critical | Set to CDI\_ID keyUsage | critical | Contains only keyCertSign basicConstraints | critical | The cA field is set to TRUE. The pathLenConstraint field is normally not included, but may be included and set to zero if it is known that no additional DICE [layers](#layering-details) exist. ##### CDI Custom Extension Fields Field | Value --------- | ----- extnID | 1.3.6.1.4.1.11129.2.1.24 (The 1.3.6.1.4.1 is the [enterprise number](https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers), the 11129.2.1 is google.googleSecurity.certificateExtensions, and 24 is diceAttestationData assigned for this profile). critical | FALSE extnValue | A [OpenDiceInput](#custom-extension-format) sequence #### Custom Extension Format The custom extension follows this ASN.1 format: ``` Mode ::= INTEGER (0..3) OpenDiceInput ::= SEQUENCE { codeHash [0] EXPLICIT OCTET STRING OPTIONAL, codeDescriptor [1] EXPLICIT OCTET STRING OPTIONAL, configurationHash [2] EXPLICIT OCTET STRING OPTIONAL, configurationDescriptor [3] EXPLICIT OCTET STRING OPTIONAL, authorityHash [4] EXPLICIT OCTET STRING OPTIONAL, authorityDescriptor [5] EXPLICIT OCTET STRING OPTIONAL, mode [6] EXPLICIT Mode OPTIONAL, } ``` All fields are explicitly tagged and optional to allow for flexibility and extensibility in the format itself. The actual semantics are as follows: * **codeHash** - Required. This is the exact 64-byte code input value used to compute CDI values. * **codeDescriptor** - Optional. This field contains additional information about the code input value. The format of this field is implementation-specific. If this field is included then all the information here must have been used to compute codeHash; i.e. a change in this value implies a change in codeHash. * **configurationHash** - Optional. If the configuration input is a hash, this field contains that hash. If the configuration is not a hash, this field is omitted. If present, this value is the exact configuration input used to compute CDI values, and also matches H(configurationDescriptor). * **configurationDescriptor** - Required. If the configuration input is a hash this field contains the original configuration data that was hashed. If it is not a hash, this field contains the exact 64-byte configuration input value used to compute CDI values. * **authorityHash** - Required. This is the exact 64-byte authority input value used to compute CDI values. * **authorityDescriptor** - Optional. This field contains additional information about the authority input value. The format of this field is implementation-specific. If this field is included then all the information here must have been used to compute authorityHash; i.e. a change in this value implies a change in authorityHash. * **mode** - Required. This is the mode input value. ### CBOR UDS Certificates A CBOR UDS certificate is a standard signed CWT. The following table lists all field constraints required by this profile in addition to the standard. The certificate is _untagged_, and it must be a _COSE\_Sign1_ message. Field | Description ----- | ----------- iss | Required: The value is implementation dependent. sub | Required: The value must be "\" where UDS\_ID is hex encoded lower case. aud | Omitted #### Additional Fields The following table lists additional entries in the CWT. Note these have the same labels and semantics as the corresponding fields in [CBOR CDI certificates](#cbor-cdi-certificates). Field | CBOR Label ---------------- | ---------- subjectPublicKey | -4670552 keyUsage | -4670553 The _subjectPublicKey_ field contains the public key associated with the subject in the form of a COSE\_Key structure encoded to a CBOR byte string. The _keyUsage_ field contains a CBOR byte string the bits of which correspond to the [X.509 KeyUsage bits](https://tools.ietf.org/html/rfc5280#section-4.2.1.3) in little-endian byte order (i.e. bit 0 is the low-order bit of the first byte). For UDS certificates this should have only the keyCertSign bit set. ### CBOR CDI Certificates A CBOR CDI certificate is a standard signed CWT with additional fields. The certificate is _untagged_, and it must be a _COSE\_Sign1_ message. The following table lists all constraints on standard fields required by this profile. Field | Description ----- | ----------- iss | Required: The value must be "\" where UDS\_ID is hex encoded lower case. sub | Required: The value must be "\" where CDI\_ID is hex encoded lower case. aud | Omitted exp | Omitted nbf | Omitted when a reliable time source is not available iat | Omitted when a reliable time source is not available cti | Omitted #### Additional Fields The following table lists additional entries in the CWT. By convention, the private fields in the map are labeled using negative integers starting at -4670545. Field | CBOR Label ----------------------- | ---------- codeHash | -4670545 codeDescriptor | -4670546 configurationHash | -4670547 configurationDescriptor | -4670548 authorityHash | -4670549 authorityDescriptor | -4670550 mode | -4670551 subjectPublicKey | -4670552 keyUsage | -4670553 The _subjectPublicKey_ field contains the public key associated with the subject in the form of a COSE\_Key structure encoded to a CBOR byte string. The _keyUsage_ field contains a CBOR byte string the bits of which correspond to the [X.509 KeyUsage bits](https://tools.ietf.org/html/rfc5280#section-4.2.1.3) in little-endian byte order (i.e. bit 0 is the low-order bit of the first byte). For CDI certificates this should have only the keyCertSign bit set. All other fields have identical semantics to their counterparts in the [X.509 custom extension](#custom-extension-format). The encoding for each is a CBOR byte string including _mode_ which is a CBOR byte string holding a single byte (the advantage to using a byte string here is a consistent encoding size regardless of the value of mode). # Appendix A: Implementing on Existing Hardware This profile requires hardware changes to implement fully. However, there is still value in implementing it in software on top of existing hardware. Depending on the existing hardware capabilities, the security of the DICE root may be equivalent to a full hardware implementation. ## Implementing with Standard DICE Support If hardware supports a standard DICE mechanism but does not support this profile directly, this profile can be implemented in firmware and can use the firmware CDI from the standard DICE as a UDS. The provisioned certificate would then cover both the hardware and the firmware implementing this profile. However, this only works if the firmware that implements this profile is unmodified during normal operation. It becomes a _ROM extension_ in the sense that if it is modified, the firmware CDI changes, and the certificate chain provisioned for the device is no longer valid. In an ARM Trusted Firmware architecture, it would likely be BL2 firmware that implements this profile. If the firmware implementing this profile is the first firmware to run on the system, this approach has equivalent security to a full hardware implementation. ## Implementing with Lockable Persistent Storage If hardware supports a lockable persistent storage mechanism early in boot, this profile can be implemented in firmware and can use a secret stored using this mechanism as a UDS. This firmware should run as early in boot as possible. The storage could be lockable OTP memory, lockable NVRAM, a one-time derivation, or similar. Security chips like a TPM or SE often have an appropriate capability. However, this only works along with a robust verified boot system to verify the firmware that implements this profile and any other firmware that runs before it. It also has the downside that changes to the firmware, or any other firmware that runs before it, are not reflected in the CDIs. The security of this approach is not equivalent to a full hardware implementation, but may still be acceptable for many applications. If the firmware implementing this profile is the first firmware to run on the system, this approach has equivalent security to a full hardware implementation which employs a hardware modification mechanism like an FPGA or microcode. This approach can also be used later in boot, for example in a TEE. However, the more code that runs without being covered by a DICE flow, the lower the security of the implementation. ## Other Hardware Implementations With a robust verified boot system, there are many other possible implementations as long as (1) A UDS can be made available by some means early in boot, and (2) that UDS can be made subsequently unavailable until the next boot. These implementations meet the requirements of the TCG DICE specification as an _updatable DICE_ per section 6.2. # Appendix B: Hardware Implementation Checklist The following is a list of capabilities that a full hardware implementation must have. This is intended for the convenience of hardware designers, and is not intended to add any additional requirements or constraints. 1. Provide a UDS capability as required by this profile and the TCG DICE specification. Usually this _cannot_ be implemented in mask ROM but requires additional hardware capabilities. See [UDS Details](#uds-details). 1. Reserve on the order of 8KB of mask ROM for DICE, not including crypto primitives. The rest of this list can usually be implemented entirely in ROM. 1. Choose crypto primitives and provide implementations, ideally with hardware acceleration. See [Cryptography](#cryptography). 1. Provide a code input. At this level a simple code hash is recommended, without an additional descriptor. Often the verified boot system already has a code hash it verifies, and using the same hash as input to DICE is recommended. See [Input Values](#input-values). 1. Provide a configuration input. At this level, using the 64-bit value described in this profile is recommended. See [Input Values](#input-values) and [Configuration Input Value Details](#configuration-input-value-details-optional). 1. Provide a verified boot authority input. This should be very simple and stable, often copied directly out of OTP memory. At this level a simple hash is recommended, without an additional descriptor. See [Input Values](#input-values). 1. Provide a mode input. Determining the mode is a runtime decision so a bit of logic will have to be coded. The 64-bit configuration value should have all the information necessary to make this decision. See [Input Values](#input-values) and [Mode Value Details](#mode-value-details). 1. Provide a hidden input value if necessary. At this level it is not recommended. 1. Implement the [DICE flow](#high-level-dice-flow) and certificate generation; reference code is available. If recommendations in this list are followed for simple inputs, the certificate will be a constant size and layout and a template can be used (avoiding the need for X.509 or CBOR code). See [Certificate Details](#certificate-details). 1. Make DICE outputs available to firmware (CDIs and certificate). 1. Depending on which provisioning model is used, make the UDS-derived public key available. # Appendix C: Versioned Sealing Keys A versioned sealing key is a key that is derived from a secret seed and one or more software versions. The versions cannot be higher than the current software version. In other words, a versioned sealing key can be derived for the current software version and each previous version, but not for future versions. These keys can be used to seal data in a rollback-protected way, that is, in a way that current and future software can unseal but older software cannot. Each time software is upgraded, the data can be re-sealed to be bound to the latest version. The Sealing CDIs derived by using DICE in layers as described in this profile are not versioned; rather they are stable across versions. To achieve versioned sealing keys, an additional hardware mechanism is required: a versioned KDF (V-KDF). There are many possible implementations but in general it must be possible to seed the V-KDF with one or more secrets that it will not expose, and one or more maximum versions that it will not allow to be subsequently modified. After seeding, the V-KDF accepts version info as input (likely along with other inputs), and the output is a key that may be used as a versioned sealing key. Given such a V-KDF, versioned keys can be derived from a Sealing CDI by adding a few steps to precede the [DICE flow](#high-level-dice-flow): * Derive a V-KDF seed from the current sealing CDI (or UDS if this is the initial DICE instance) and the same inputs used for deriving the next layer sealing CDI. The derivation differs from the sealing CDI derivation only by the info string: ```py VKDF_SEED = KDF(32, CDI_Seal_or_UDS, H(authority + mode + hidden), "VKDF_SEED") ``` * Seed the V-KDF with the output of (1) and the version of the target code (the code to which control will be transferred at the end of the DICE flow) * Destroy any copy of the V-KDF seed, so it's only available to the V-KDF * Run the DICE flow as usual Note that the V-KDF seed is derived from the _current_ sealing CDI; this value is _not_ passed to target code but is locked / destroyed as part of the DICE flow. As a result the target code can only generate versioned keys as seeded by the previous layer. When multiple layers are involved, the V-KDF should use the seed inputs cumulatively: * The seed value should be mixed into the current state, it should not reset the state. * The max version value should be retained in addition to the existing max version values. The version info supplied as KDF input must then contain one version for each maximum version configured. The number of layers supported may be limited by the V-KDF hardware; support for at least 8 maximum versions is recommended.