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. 86Component instance name | -70007 | tstr | When component is meant as a type, class or category, one can further specify the particular instance of that component. 87 88[rkp-vm]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/docs/service_vm.md#rkp-vm-remote-key-provisioning-virtual-machine 89[rkp-hal-readme]: https://android.googlesource.com/platform/hardware/interfaces/+/main/security/rkp/README.md 90 91### Versions 92 93Android is an evolving ecosystem with compatibility requirements that enable 94devices to continue being updated. Explicit versioning of certificates in the 95DICE chain allows continued compatibility between higher-level software that 96updates and lower-level software (such as ROM) that might not update. 97 98Versions of this profile are identified by their profile name which is composed 99of the prefix `"android."` followed by the Android version number it aligns 100with. Certificates declare which profile they are following in the `profileName` 101field defined by the [Open Profile for DICE](specification.md). If no profile 102name is included in the certificate, `"android.14"` is assumed. 103 104Within a DICE chain, the version of the profile used in each certificate must 105be the same or greater than the version used in the previous certificate. This 106ensures the all certificates are aware of, and can maintain, any chain 107invariants that can be added in any version of the profile. 108 109Android provides the [`hwtrust`][hwtrust-tool] tool which can validate that 110certificate chains conform to this profile and can assist in diagnosing 111problems. 112 113[hwtrust-tool]: https://cs.android.com/android/platform/superproject/main/+/main:tools/security/remote_provisioning/hwtrust/README.md 114 115The version-specific details listed below are non-cumulative so only apply to 116the version they are listed under. 117 118#### `"android.14"` 119 120The profile named `"android.14"` aligns with Android 14. 121 122* Based on the [Open Profile for DICE v2.4][open-dice-v2.4]. 123* The `configurationHash` field is permitted to be missing rather than being 124 required, as specified by the Open Profile for DICE. 125* The `mode` field is permitted to be encoded as an integer rather than the 126 byte string that is specified by the Open Profile for DICE. 127* The `keyUsage` field is permitted to be encoded in big-endian byte order as 128 well as the little-endian byte order that is specified by the Open Profile 129 for DICE. As a result of this erratum workaround, the value is ambiguous and 130 verifiers might not be able to rely on this value. 131 132#### `"android.15"` 133 134The profile named `"android.15"` aligns with Android 15. It is backwards 135compatible with the previous versions of the Andorid Profile for DICE. 136 137* Based on the [Open Profile for DICE v2.5][open-dice-v2.5]. 138* The `configurationHash` field is permitted to be missing rather than being 139 required, as specified by the Open Profile for DICE. 140 141#### `"android.16"` 142 143The profile named `"android.16"` aligns with Android 16 and is still subject to 144change. It is backwards compatible with the previous versions of the Android 145Profile for DICE. 146 147* Based on the [Open Profile for DICE v2.5][open-dice-v2.5]. 148* The security version field of the [configuration 149 descriptor](#configuration-descriptor) is required. 150 151[open-dice-v2.4]: https://pigweed.googlesource.com/open-dice/+/f9f454ae493bfe76ec2af8011eb7543c20c5ffc2/docs/specification.md 152[open-dice-v2.5]: https://pigweed.googlesource.com/open-dice/+/0b5044098bf9b40128927d675dea4ec1fb75c510/docs/specification.md 153