docs/android.md - open-dice - Git at Google


            
            # Android Profile for DICE


            [TOC]


            ## Background


            The Android Profile for DICE is a specialization of the [Open Profile for

            
            DICE](specification.md) that provides additional detail around algorithms,

            
            certificates, and configuration descriptor. The choices are made to meet the

            
            needs of the Android ecosystem.


            This profile is not always a strict refinement of the Open Profile for DICE as

            
            it also forced to address practical concerns such as workarounds for errata in

            
            ROMs that require a relaxation of the base specification. However, the objective

            
            is to avoid these where practical.


            ## Cryptographic Algorithms


            The choice of algorithm must remain consistent with any given certificate e.g.

            
            if SHA-256 is the hash algorithm used for the code hash then the authority hash,

            
            config hash, etc. must also use SHA-256.


            See the Open Profile for DICE's [acceptable cryptographic

            
            algorithms](specification.md#acceptable-cryptographic-algorithms) for more

            
            detail on specific algorithms.


            ### Hash Algorithms


            Acceptable hash algorithms are:


            *   SHA-256, SHA-384, SHA-512


            Unlike the Open Profile for DICE, digests can be used as DICE inputs at their

            
            output size without needing to be resized to 64 bytes. The value that is used as

            
            the DICE input must be listed in the certificate. E.g. SHA-256 digests can be

            
            used as 32-byte DICE inputs with the same 32 bytes encoded as a byte string in

            
            the certificate.


            ### Key Derivation Functions


            HKDF with a [supported hash algorithm](#hash-algorithms), or

            
            [CKDF](https://datatracker.ietf.org/doc/html/draft-agl-ckdf-00) for all key

            
            derivation.


            ### Digital Signatures


            Ed25519 is recommended for performance and memory usage reasons. ECDSA with

            
            curves P-256 or P-384 are acceptable.


            ML-DSA-65 or ML-DSA-87 are acceptable for PQC support. However, keep in mind

            
            that CNSA 2.0 accepts only ML-DSA-87.


            ## Certificate Details


            Only CBOR certificates are allowed by this profile. Other certificate types,

            
            such as X.509, must not be used.


            ### Mode


            A certificate must only set the mode to `normal` when all of the following

            
            conditions are met when loading and verifying the software component that is

            
            being described by the certificate:


            *   secure/verified boot with anti-rollback protection is enabled

            
            *   only the secure/verified boot authorities for production images are enabled

            
            *   debug ports, fuses, or other debug facilities are disabled

            
            *   device booted software from the normal primary source e.g. internal flash


            The mode should never be `not configured`.


            ### Configuration descriptor


            The configuration descriptor is a CBOR map. Only key values less than -65536

            
            are used as this is conventionally reserved for private use in IANA

            
            assignments. The key value range \[-70000, -70999\] is reserved for use by this

            
            profile. Implementation-specific fields may be added using key values outside

            
            of the reserved range.


            Unless explicitly stated as required in the [versions](#versions) section, each

            
            field is optional. If no fields are relevant, an empty map should be encoded.


            The `configurationHash` field is permitted to be missing in all versions of the

            
            Android Profile for DICE.


            Name                   | Key    | Value&nbsp;type      | Meaning

            
            ---                    | ---    | ---                  | ---

            
            Component&nbsp;name    | -70002 | tstr                 | Name of the component

            
            Component&nbsp;version | -70003 | int&nbsp;/&nbsp;tstr | Version of the component

            
            Resettable             | -70004 | null                 | If present, key changes on factory reset

            
            Security&nbsp;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.

            
            [RKP&nbsp;VM][rkp-vm]&nbsp;marker | -70006 | null      | See the [Android HAL documentation][rkp-hal-readme] for precise semantics, as they vary by Android version.

            
            Component&nbsp;instance&nbsp;name | -70007 | tstr      | When component is meant as a type, class or category, one can further specify the particular instance of that component.


            [rkp-vm]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/docs/service_vm.md#rkp-vm-remote-key-provisioning-virtual-machine

            
            [rkp-hal-readme]: https://android.googlesource.com/platform/hardware/interfaces/+/main/security/rkp/README.md


            ### Versions


            Android is an evolving ecosystem with compatibility requirements that enable

            
            devices to continue being updated. Explicit versioning of certificates in the

            
            DICE chain allows continued compatibility between higher-level software that

            
            updates and lower-level software (such as ROM) that might not update.


            Versions of this profile are identified by their profile name which is composed

            
            of the prefix `"android."` followed by the Android version number it aligns

            
            with. Certificates declare which profile they are following in the `profileName`

            
            field defined by the [Open Profile for DICE](specification.md). If no profile

            
            name is included in the certificate, `"android.14"` is assumed.


            Within a DICE chain, the version of the profile used in each certificate must

            
            be the same or greater than the version used in the previous certificate. This

            
            ensures the all certificates are aware of, and can maintain, any chain

            
            invariants that can be added in any version of the profile.


            Android provides the [`hwtrust`][hwtrust-tool] tool which can validate that

            
            certificate chains conform to this profile and can assist in diagnosing

            
            problems.


            [hwtrust-tool]: https://cs.android.com/android/platform/superproject/main/+/main:tools/security/remote_provisioning/hwtrust/README.md


            The version-specific details listed below are non-cumulative so only apply to

            
            the version they are listed under.


            #### `"android.14"`


            The profile named `"android.14"` was introduced with Android 14.


            *   Based on the [Open Profile for DICE v2.4][open-dice-v2.4].

            
            *   The `mode` field is permitted to be encoded as an integer rather than the

            
                byte string that is specified by the Open Profile for DICE.

            
            *   The `keyUsage` field is permitted to be encoded in big-endian byte order as

            
                well as the little-endian byte order that is specified by the Open Profile

            
                for DICE. As a result of this erratum workaround, the value is ambiguous and

            
                verifiers might not be able to rely on this value.


            #### `"android.15"`


            The profile named `"android.15"` was introduced with Android 15. It is backwards

            
            compatible with the previous versions of the Android Profile for DICE.


            *   Based on the [Open Profile for DICE v2.5][open-dice-v2.5].


            #### `"android.16"`


            The profile named `"android.16"` was introduced with Android 16. It is backwards

            
            compatible with the previous versions of the Android Profile for DICE.


            *   Based on the [Open Profile for DICE v2.5][open-dice-v2.5].

            
            *   The security version field of the [configuration

            
                descriptor](#configuration-descriptor) is required.


            #### `"android.17"`


            Please note there is no `"android.17"` profile as there were no changes to

            
            Android DICE support between Android versions 16 and 17. Google recommends

            
            that chipset vendors implement the `"android.16"` profile, as it is the most

            
            up-to-date.


            #### `"android.18"`


            The profile named `"android.18"` aligns with Android 18 and is still subject to

            
            change. It is backwards compatible with the previous versions of the Android

            
            Profile for DICE.


            *   Based on the [Open Profile for DICE v2.6][open-dice-v2.6].

            
            *   Added support for ML-DSA-65 and ML-DSA-87 to the profile.


            [open-dice-v2.4]: https://pigweed.googlesource.com/open-dice/+/f9f454ae493bfe76ec2af8011eb7543c20c5ffc2/docs/specification.md

            
            [open-dice-v2.5]: https://pigweed.googlesource.com/open-dice/+/0b5044098bf9b40128927d675dea4ec1fb75c510/docs/specification.md

            
            [open-dice-v2.6]: https://pigweed.googlesource.com/open-dice/+/03e19ce5d8557d10f06cb1319bc6043685dfd22c/docs/specification.md
	# Android Profile for DICE

	[TOC]

	## Background

	The Android Profile for DICE is a specialization of the [Open Profile for
	DICE](specification.md) that provides additional detail around algorithms,
	certificates, and configuration descriptor. The choices are made to meet the
	needs of the Android ecosystem.

	This profile is not always a strict refinement of the Open Profile for DICE as
	it also forced to address practical concerns such as workarounds for errata in
	ROMs that require a relaxation of the base specification. However, the objective
	is to avoid these where practical.

	## Cryptographic Algorithms

	The choice of algorithm must remain consistent with any given certificate e.g.
	if SHA-256 is the hash algorithm used for the code hash then the authority hash,
	config hash, etc. must also use SHA-256.

	See the Open Profile for DICE's [acceptable cryptographic
	algorithms](specification.md#acceptable-cryptographic-algorithms) for more
	detail on specific algorithms.

	### Hash Algorithms

	Acceptable hash algorithms are:

	* SHA-256, SHA-384, SHA-512

	Unlike the Open Profile for DICE, digests can be used as DICE inputs at their
	output size without needing to be resized to 64 bytes. The value that is used as
	the DICE input must be listed in the certificate. E.g. SHA-256 digests can be
	used as 32-byte DICE inputs with the same 32 bytes encoded as a byte string in
	the certificate.

	### Key Derivation Functions

	HKDF with a [supported hash algorithm](#hash-algorithms), or
	[CKDF](https://datatracker.ietf.org/doc/html/draft-agl-ckdf-00) for all key
	derivation.

	### Digital Signatures

	Ed25519 is recommended for performance and memory usage reasons. ECDSA with
	curves P-256 or P-384 are acceptable.

	ML-DSA-65 or ML-DSA-87 are acceptable for PQC support. However, keep in mind
	that CNSA 2.0 accepts only ML-DSA-87.

	## Certificate Details

	Only CBOR certificates are allowed by this profile. Other certificate types,
	such as X.509, must not be used.

	### Mode

	A certificate must only set the mode to `normal` when all of the following
	conditions are met when loading and verifying the software component that is
	being described by the certificate:

	* secure/verified boot with anti-rollback protection is enabled
	* only the secure/verified boot authorities for production images are enabled
	* debug ports, fuses, or other debug facilities are disabled
	* device booted software from the normal primary source e.g. internal flash

	The mode should never be `not configured`.

	### Configuration descriptor

	The configuration descriptor is a CBOR map. Only key values less than -65536
	are used as this is conventionally reserved for private use in IANA
	assignments. The key value range \[-70000, -70999\] is reserved for use by this
	profile. Implementation-specific fields may be added using key values outside
	of the reserved range.

	Unless explicitly stated as required in the [versions](#versions) section, each
	field is optional. If no fields are relevant, an empty map should be encoded.

	The `configurationHash` field is permitted to be missing in all versions of the
	Android Profile for DICE.

	Name \| Key \| Value type \| Meaning
	--- \| --- \| --- \| ---
	Component name \| -70002 \| tstr \| Name of the component
	Component version \| -70003 \| int / tstr \| Version of the component
	Resettable \| -70004 \| null \| If present, key changes on factory reset
	Security 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.
	[RKP VM][rkp-vm] marker \| -70006 \| null \| See the [Android HAL documentation][rkp-hal-readme] for precise semantics, as they vary by Android version.
	Component instance name \| -70007 \| tstr \| When component is meant as a type, class or category, one can further specify the particular instance of that component.

	[rkp-vm]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/docs/service_vm.md#rkp-vm-remote-key-provisioning-virtual-machine
	[rkp-hal-readme]: https://android.googlesource.com/platform/hardware/interfaces/+/main/security/rkp/README.md

	### Versions

	Android is an evolving ecosystem with compatibility requirements that enable
	devices to continue being updated. Explicit versioning of certificates in the
	DICE chain allows continued compatibility between higher-level software that
	updates and lower-level software (such as ROM) that might not update.

	Versions of this profile are identified by their profile name which is composed
	of the prefix `"android."` followed by the Android version number it aligns
	with. Certificates declare which profile they are following in the `profileName`
	field defined by the [Open Profile for DICE](specification.md). If no profile
	name is included in the certificate, `"android.14"` is assumed.

	Within a DICE chain, the version of the profile used in each certificate must
	be the same or greater than the version used in the previous certificate. This
	ensures the all certificates are aware of, and can maintain, any chain
	invariants that can be added in any version of the profile.

	Android provides the [`hwtrust`][hwtrust-tool] tool which can validate that
	certificate chains conform to this profile and can assist in diagnosing
	problems.

	[hwtrust-tool]: https://cs.android.com/android/platform/superproject/main/+/main:tools/security/remote_provisioning/hwtrust/README.md

	The version-specific details listed below are non-cumulative so only apply to
	the version they are listed under.

	#### `"android.14"`

	The profile named `"android.14"` was introduced with Android 14.

	* Based on the [Open Profile for DICE v2.4][open-dice-v2.4].
	* The `mode` field is permitted to be encoded as an integer rather than the
	byte string that is specified by the Open Profile for DICE.
	* The `keyUsage` field is permitted to be encoded in big-endian byte order as
	well as the little-endian byte order that is specified by the Open Profile
	for DICE. As a result of this erratum workaround, the value is ambiguous and
	verifiers might not be able to rely on this value.

	#### `"android.15"`

	The profile named `"android.15"` was introduced with Android 15. It is backwards
	compatible with the previous versions of the Android Profile for DICE.

	* Based on the [Open Profile for DICE v2.5][open-dice-v2.5].

	#### `"android.16"`

	The profile named `"android.16"` was introduced with Android 16. It is backwards
	compatible with the previous versions of the Android Profile for DICE.

	* Based on the [Open Profile for DICE v2.5][open-dice-v2.5].
	* The security version field of the [configuration
	descriptor](#configuration-descriptor) is required.

	#### `"android.17"`

	Please note there is no `"android.17"` profile as there were no changes to
	Android DICE support between Android versions 16 and 17. Google recommends
	that chipset vendors implement the `"android.16"` profile, as it is the most
	up-to-date.

	#### `"android.18"`

	The profile named `"android.18"` aligns with Android 18 and is still subject to
	change. It is backwards compatible with the previous versions of the Android
	Profile for DICE.

	* Based on the [Open Profile for DICE v2.6][open-dice-v2.6].
	* Added support for ML-DSA-65 and ML-DSA-87 to the profile.

	[open-dice-v2.4]: https://pigweed.googlesource.com/open-dice/+/f9f454ae493bfe76ec2af8011eb7543c20c5ffc2/docs/specification.md
	[open-dice-v2.5]: https://pigweed.googlesource.com/open-dice/+/0b5044098bf9b40128927d675dea4ec1fb75c510/docs/specification.md
	[open-dice-v2.6]: https://pigweed.googlesource.com/open-dice/+/03e19ce5d8557d10f06cb1319bc6043685dfd22c/docs/specification.md