1# Android Profile for DICE 2 3[TOC] 4 5## Background 6 7The Android Profile for DICE is a specialization of the [Open Profile for 8DICE](specification.md) that provides additional detail around algorithms, 9certificates, and configuration descriptor. The choices are made to meet the 10needs of the Android ecosystem. 11 12This profile is not always a strict refinement of the Open Profile for DICE as 13it also forced to address practical concerns such as workarounds for errata in 14ROMs that require a relaxation of the base specification. However, the objective 15is to avoid these where practical. 16 17## Cryptographic Algorithms 18 19The choice of algorithm must remain consistent with any given certificate e.g. 20if SHA-256 is the hash algorithm used for the code hash then the authority hash, 21config hash, etc. must also use SHA-256. 22 23See the Open Profile for DICE's [acceptable cryptographic 24algorithms](specification.md#acceptable-cryptographic-algorithms) for more 25detail on specific algorithms. 26 27### Hash Algorithms 28 29Acceptable hash algorithms are: 30 31* SHA-256, SHA-384, SHA-512 32 33Unlike the Open Profile for DICE, digests can be used as DICE inputs at their 34output size without needing to be resized to 64 bytes. The value that is used as 35the DICE input must be listed in the certificate. E.g. SHA-256 digests can be 36used as 32-byte DICE inputs with the same 32 bytes encoded as a byte string in 37the certificate. 38 39### Key Derivation Functions 40 41HKDF with a [supported hash algorithm](#hash-algorithms), or 42[CKDF](https://datatracker.ietf.org/doc/html/draft-agl-ckdf-00) for all key 43derivation. 44 45### Digital Signatures 46 47Ed25519 is recommended for performance and memory usage reasons. ECDSA with 48curves P-256 or P-384 are acceptable. 49 50## Certificate Details 51 52Only CBOR certificates are allowed by this profile. Other certificate types, 53such as X.509, must not be used. 54 55### Mode 56 57A certificate must only set the mode to `normal` when all of the following 58conditions are met when loading and verifying the software component that is 59being described by the certificate: 60 61* secure/verified boot with anti-rollback protection is enabled 62* only the secure/verified boot authorities for production images are enabled 63* debug ports, fuses, or other debug facilities are disabled 64* device booted software from the normal primary source e.g. internal flash 65 66The mode should never be `not configured`. 67 68### Configuration descriptor 69 70The configuration descriptor is a CBOR map. Only key values less than -65536 71are used as this is conventionally reserved for private use in IANA 72assignments. The key value range \[-70000, -70999\] is reserved for use by this 73profile. Implementation-specific fields may be added using key values outside 74of the reserved range. 75 76Unless explicitly stated as required in the [versions](#versions) section, each 77field is optional. If no fields are relevant, an empty map should be encoded. 78 79Name | Key | Value type | Meaning 80--- | --- | --- | --- 81Component name | -70002 | tstr | Name of the component 82Component version | -70003 | int / tstr | Version of the component 83Resettable | -70004 | null | If present, key changes on factory reset 84Security version | -70005 | uint | Machine-comparable, monotonically increasing version of the component where a greater value indicates a newer version. This value must increment for every update that changes the code hash, for example by using the timestamp of the version's release. 85[RKP VM][rkp-vm] marker | -70006 | null | See the [Android HAL documentation][rkp-hal-readme] for precise semantics, as they vary by Android version. 86 87[rkp-vm]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/service_vm/README.md#rkp-vm-remote-key-provisioning-virtual-machine 88[rkp-hal-readme]: https://android.googlesource.com/platform/hardware/interfaces/+/main/security/rkp/README.md 89 90### Versions 91 92Android is an evolving ecosystem with compatibility requirements that enable 93devices to continue being updated. Explicit versioning of certificates in the 94DICE chain allows continued compatibility between higher-level software that 95updates and lower-level software (such as ROM) that might not update. 96 97Versions of this profile are identified by their profile name which is composed 98of the prefix `"android."` followed by the Android version number it aligns 99with. Certificates declare which profile they are following in the `profileName` 100field defined by the [Open Profile for DICE](specification.md). If no profile 101name is included in the certificate, `"android.14"` is assumed. 102 103Within a DICE chain, the version of the profile used in each certificate must 104be the same or greater than the version used in the previous certificate. This 105ensures the all certificates are aware of, and can maintain, any chain 106invariants that can be added in any version of the profile. 107 108Android provides the [`hwtrust`][hwtrust-tool] tool which can validate that 109certificate chains conform to this profile and can assist in diagnosing 110problems. 111 112[hwtrust-tool]: https://cs.android.com/android/platform/superproject/main/+/main:tools/security/remote_provisioning/hwtrust/README.md 113 114The version-specific details listed below are non-cumulative so only apply to 115the version they are listed under. 116 117#### `"android.14"` 118 119The profile named `"android.14"` aligns with Android 14. 120 121* Based on the [Open Profile for DICE v2.4][open-dice-v2.4]. 122* The `configurationHash` field is permitted to be missing rather than being 123 required, as specified by the Open Profile for DICE. 124* The `mode` field is permitted to be encoded as an integer rather than the 125 byte string that is specified by the Open Profile for DICE. 126* The `keyUsage` field is permitted to be encoded in big-endian byte order as 127 well as the little-endian byte order that is specified by the Open Profile 128 for DICE. As a result of this erratum workaround, the value is ambiguous and 129 verifiers might not be able to rely on this value. 130 131#### `"android.15"` 132 133The profile named `"android.15"` aligns with Android 15. It is backwards 134compatible with the previous versions of the Andorid Profile for DICE. 135 136* Based on the [Open Profile for DICE v2.5][open-dice-v2.5]. 137* The `configurationHash` field is permitted to be missing rather than being 138 required, as specified by the Open Profile for DICE. 139 140#### `"android.16"` 141 142The profile named `"android.16"` aligns with Android 16 and is still subject to 143change. It is backwards compatible with the previous versions of the Android 144Profile for DICE. 145 146* Based on the [Open Profile for DICE v2.5][open-dice-v2.5]. 147* The security version field of the [configuration 148 descriptor](#configuration-descriptor) is required. 149 150[open-dice-v2.4]: https://pigweed.googlesource.com/open-dice/+/f9f454ae493bfe76ec2af8011eb7543c20c5ffc2/docs/specification.md 151[open-dice-v2.5]: https://pigweed.googlesource.com/open-dice/+/0b5044098bf9b40128927d675dea4ec1fb75c510/docs/specification.md 152