Document the Android Profile for DICE
Move the specification of the Android Profile for DICE into this repo
where it can be referenced from AOSP. Moving the documentation here
shows the alignment between the projects. Although the profile is
primarily designed for Android features, there has been interest from
others to follow the same specification.
Change-Id: Ifc3aa210e84fe71452bf16a3d96cc50ba47ad26b
Reviewed-on: https://pigweed-review.googlesource.com/c/open-dice/+/165234
Reviewed-by: Darren Krahn <dkrahn@google.com>
Commit-Queue: Andrew Scull <ascull@google.com>
Reviewed-by: Max Bires <jbires@google.com>
diff --git a/docs/android.md b/docs/android.md
new file mode 100644
index 0000000..f41e6b1
--- /dev/null
+++ b/docs/android.md
@@ -0,0 +1,151 @@
+# 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.
+
+## 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.
+
+```
+| 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, for example, the :
+: : : : anti-rollback counter :
+```
+
+### 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. 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"` aligns with Android 14.
+
+* Based on the [Open Profile for DICE v2.4][open-dice-v2.4].
+* The `configurationHash` field is permitted to be missing rather than being
+ required, as specified by the Open Profile for DICE.
+* 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"` aligns with Android 15.
+
+* Based on the [Open Profile for DICE v2.5][open-dice-v2.5].
+* The `configurationHash` field is permitted to be missing rather than being
+ required, as specified by the Open Profile for DICE.
+
+#### `"android.16"`
+
+The profile named `"android.16"` aligns with Android 16 and is still subject to
+change.
+
+* 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.
+
+[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
diff --git a/docs/specification.md b/docs/specification.md
index e10e739..3348c62 100644
--- a/docs/specification.md
+++ b/docs/specification.md
@@ -62,6 +62,10 @@
* Additional requirements, including asymmetric key derivation and
certification
+Known specializations of this profile include:
+
+* [Android Profile for DICE](android.md)
+
#### Goals
The main goals of this document are:
diff --git a/src/android.c b/src/android.c
index 5fd4a5c..39ee7d0 100644
--- a/src/android.c
+++ b/src/android.c
@@ -12,11 +12,7 @@
// License for the specific language governing permissions and limitations under
// the License.
-// The Android Profile for DICE is a specialization of the Open Profile for DICE
-// that is used by Android. More details can be found in the remote key
-// provisioning (RKP) documentation linked below.
-//
-// https://cs.android.com/android/platform/superproject/+/main:hardware/interfaces/security/rkp/README.md
+// For more information on the Android Profile for DICE, see docs/android.md.
#include "dice/android.h"
