1; DICE Specification for guest VM
2
3; See the Open DICE specification
4; https://pigweed.googlesource.com/open-dice/+/HEAD/docs/specification.md,
5; and the Android Profile for DICE
6; https://pigweed.googlesource.com/open-dice/+/HEAD/docs/android.md.
7
8; This CDDL describes the Configuration Descriptor used for components running in AVF Guest environment
9; (VM core components and payload). It extends the `ConfigurationDescriptor` specified at
10; https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
11
12; Additionally, we reserve range -71000...-71999 for AVF system specific usage. These are or can be
13; used by frameworks & parsers of DICE chains such as local and remote attestation frameworks.
14; Vendor must not use these key/values for other purposes, that may compromise the integrity of the system.
15; Note that each of the key-value pairs may not be useful for all the boot components and therefore
16; are optional. For e.g., SubcomponentDescriptor is only used in Microdroid payload, it may
17; not have immediate use for pVM firmware.
18
19; Each components of VM must specify the value corresponding to `Component name`(-70002).
20; For provided reference implementations:
21;
22; 1. "vm_entry" - Guest 'OS'. This is the payload booted by pVM firmware. For e.g, Microdroid, Rialto.
23; 2. "Microdroid vendor" - The vendor image, specific to Microdroid.
24; 3. "Microdroid Payload" - Payload run by Microdroid Manager.
25
26
27ConfigDescriptor = {
28    -70002 : tstr,                        ; Component name
29    (? -71000: tstr //                    ; Path to the payload config file
30    ? -71001: PayloadConfig),
31    ? -71002: [+ SubcomponentDescriptor], ; The order of these should be kept constant on each boot
32                                          ; of the VM instance
33    ? -71003: bstr .size 64               ; Instance hash: Unique identifier of the VM instance
34}
35
36PayloadConfig = {
37    1: tstr                             ; Path to the binary file where payload execution starts
38}
39
40; Describes a unit of code (e.g. an APK or an APEX) present inside the VM.
41;
42; For an APK, the fields are as follows:
43; - Component name: The string "apk:" followed by the package name.
44; - Security version: The long version code from the APK manifest
45;   (https://developer.android.com/reference/android/content/pm/PackageInfo#getLongVersionCode()).
46; - Code hash: This is the root hash of a Merkle tree computed over all bytes of the APK, as used
47;   in the APK Signature Scheme v4 (https://source.android.com/docs/security/features/apksigning/v4)
48;   with empty salt and using SHA-256 as the hash algorithm.
49; - Authority hash: The SHA-512 hash of the DER representation of the X.509 certificate for the
50;   public key used to sign the APK.
51;
52; For an APEX, they are as follows:
53; - Component name: The string "apex:" followed by the APEX name as specified in the APEX Manifest
54;   (see https://source.android.com/docs/core/ota/apex).
55; - Security version: The version number from the APEX Manifest.
56; - Code hash: The root hash of the apex_payload.img file within the APEX, taken from the first
57;   hashtree descriptor in the VBMeta image
58;   (see https://android.googlesource.com/platform/external/avb/+/master/README.md).
59; - Authority hash: The SHA-512 hash of the public key used to sign the file system image in the
60;   APEX (as stored in the apex_pubkey file). The format is as described for AvbRSAPublicKeyHeader
61;   in https://cs.android.com/android/platform/superproject/main/+/main:external/avb/libavb/avb_crypto.h.
62SubcomponentDescriptor = {
63  1: tstr,                              ; Component name
64  2: uint,                              ; Security version
65  3: bstr,                              ; Code hash
66  4: bstr,                              ; Authority hash
67}
68
69TODO: Describe how these descriptors are used by AVF components in Android W.