Merge "DICE specification for AVF guest" into main
diff --git a/dice_for_avf_guest.cddl b/dice_for_avf_guest.cddl
new file mode 100644
index 0000000..372ee15
--- /dev/null
+++ b/dice_for_avf_guest.cddl
@@ -0,0 +1,69 @@
+; DICE Specification for guest VM
+
+; See the Open DICE specification
+; https://pigweed.googlesource.com/open-dice/+/HEAD/docs/specification.md,
+; and the Android Profile for DICE
+; https://pigweed.googlesource.com/open-dice/+/HEAD/docs/android.md.
+
+; This CDDL describes the Configuration Descriptor used for components running in AVF Guest environment
+; (VM core components and payload). It extends the `ConfigurationDescriptor` specified at
+; https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
+
+; Additionally, we reserve range -71000...-71999 for AVF system specific usage. These are or can be
+; used by frameworks & parsers of DICE chains such as local and remote attestation frameworks.
+; Vendor must not use these key/values for other purposes, that may compromise the integrity of the system.
+; Note that each of the key-value pairs may not be useful for all the boot components and therefore
+; are optional. For e.g., SubcomponentDescriptor is only used in Microdroid payload, it may
+; not have immediate use for pVM firmware.
+
+; Each components of VM must specify the value corresponding to `Component name`(-70002).
+; For provided reference implementations:
+;
+; 1. "vm_entry" - Guest 'OS'. This is the payload booted by pVM firmware. For e.g, Microdroid, Rialto.
+; 2. "Microdroid vendor" - The vendor image, specific to Microdroid.
+; 3. "Microdroid Payload" - Payload run by Microdroid Manager.
+
+
+ConfigDescriptor = {
+ -70002 : tstr, ; Component name
+ (? -71000: tstr // ; Path to the payload config file
+ ? -71001: PayloadConfig),
+ ? -71002: [+ SubcomponentDescriptor], ; The order of these should be kept constant on each boot
+ ; of the VM instance
+ ? -71003: bstr .size 64 ; Instance hash: Unique identifier of the VM instance
+}
+
+PayloadConfig = {
+ 1: tstr ; Path to the binary file where payload execution starts
+}
+
+; Describes a unit of code (e.g. an APK or an APEX) present inside the VM.
+;
+; For an APK, the fields are as follows:
+; - Component name: The string "apk:" followed by the package name.
+; - Security version: The long version code from the APK manifest
+; (https://developer.android.com/reference/android/content/pm/PackageInfo#getLongVersionCode()).
+; - Code hash: This is the root hash of a Merkle tree computed over all bytes of the APK, as used
+; in the APK Signature Scheme v4 (https://source.android.com/docs/security/features/apksigning/v4)
+; with empty salt and using SHA-256 as the hash algorithm.
+; - Authority hash: The SHA-512 hash of the DER representation of the X.509 certificate for the
+; public key used to sign the APK.
+;
+; For an APEX, they are as follows:
+; - Component name: The string "apex:" followed by the APEX name as specified in the APEX Manifest
+; (see https://source.android.com/docs/core/ota/apex).
+; - Security version: The version number from the APEX Manifest.
+; - Code hash: The root hash of the apex_payload.img file within the APEX, taken from the first
+; hashtree descriptor in the VBMeta image
+; (see https://android.googlesource.com/platform/external/avb/+/master/README.md).
+; - Authority hash: The SHA-512 hash of the public key used to sign the file system image in the
+; APEX (as stored in the apex_pubkey file). The format is as described for AvbRSAPublicKeyHeader
+; in https://cs.android.com/android/platform/superproject/main/+/main:external/avb/libavb/avb_crypto.h.
+SubcomponentDescriptor = {
+ 1: tstr, ; Component name
+ 2: uint, ; Security version
+ 3: bstr, ; Code hash
+ 4: bstr, ; Authority hash
+}
+
+TODO: Describe how these descriptors are used by AVF components in Android W.
\ No newline at end of file
diff --git a/docs/updatable_vm.md b/docs/updatable_vm.md
index ff1a0d6..24c1b4b 100644
--- a/docs/updatable_vm.md
+++ b/docs/updatable_vm.md
@@ -59,8 +59,9 @@
1. GreaterOrEqual on SECURITY_VERSION: The secrets will be accessible if version of any
image is greater or equal to the set version.
- For each Subcomponent on the last DiceChainEntry (which corresponds to VM payload, See
- [vm_config.cddl][vm_config_cddl]): - GreaterOrEqual on SECURITY_VERSION - ExactMatch on
- AUTHORITY_HASH.
+ [dice_for_avf_guest.cddl][dice_for_avf_guest_cddl]):
+ - GreaterOrEqual on SECURITY_VERSION
+ - ExactMatch on AUTHORITY_HASH.
The sealing policy is updated each time the secret is retrieved. This ensures the secrets are only
released if the security version of the images are non-decreasing.
@@ -96,4 +97,4 @@
[open_dice_spec_cdi]: https://pigweed.googlesource.com/open-dice/+/HEAD/docs/specification.md#cdi-values
[secretkeeperhal]: https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/security/secretkeeper/aidl/android/hardware/security/secretkeeper/ISecretkeeper.aidl
[sk_project]: https://android.googlesource.com/platform/system/secretkeeper/
-[vm_config_cddl]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/microdroid_manager/src/vm_config.cddl
+[dice_for_avf_guest_cddl]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/dice_for_avf_guest.cddl
diff --git a/microdroid/derive_microdroid_vendor_dice_node/src/main.rs b/microdroid/derive_microdroid_vendor_dice_node/src/main.rs
index c7bc3f5..0f0631e 100644
--- a/microdroid/derive_microdroid_vendor_dice_node/src/main.rs
+++ b/microdroid/derive_microdroid_vendor_dice_node/src/main.rs
@@ -47,6 +47,7 @@
Path::new(AVF_STRICT_BOOT).exists()
}
+// See dice_for_avf_guest.cddl for CDDL of Configuration Descriptor of VM components.
fn build_descriptor(vbmeta: &VbMetaImage) -> Result<Vec<u8>> {
let values = DiceConfigValues {
component_name: Some(cstr!("Microdroid vendor")),
diff --git a/microdroid_manager/src/dice.rs b/microdroid_manager/src/dice.rs
index cecf413..7cfeb21 100644
--- a/microdroid_manager/src/dice.rs
+++ b/microdroid_manager/src/dice.rs
@@ -134,8 +134,8 @@
apks.chain(apexes).collect()
}
-// Returns a configuration descriptor of the given payload. See vm_config.cddl for the definition
-// of the format.
+// Returns a configuration descriptor of the given payload. See dice_for_avf_guest.cddl for the
+// definition of the format.
fn format_payload_config_descriptor(
payload: &PayloadMetadata,
subcomponents: Vec<Subcomponent>,
diff --git a/microdroid_manager/src/vm_config.cddl b/microdroid_manager/src/vm_config.cddl
deleted file mode 100644
index 8508e8f..0000000
--- a/microdroid_manager/src/vm_config.cddl
+++ /dev/null
@@ -1,56 +0,0 @@
-; Configuration Descriptor used in the DICE node that describes the payload of a Microdroid virtual
-; machine.
-;
-; See the Open DICE specification
-; https://pigweed.googlesource.com/open-dice/+/HEAD/docs/specification.md,
-; and the Android Profile for DICE
-; https://pigweed.googlesource.com/open-dice/+/HEAD/docs/android.md.
-;
-; CDDL for the normal Configuration Descriptor can be found at
-; https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
-
-; The configuration descriptor node for a Microdroid VM, with extensions to describe the contents
-; of the VM payload.
-; The subcomponents describe the APKs and then the APEXes that are part of the VM. The main APK
-; is first, followed by any extra APKs in the order they are specified in the VM config.
-; The APEXes are listed in the order specified when the VM is created, which is normally alphabetic
-; order by name.
-VmConfigDescriptor = {
- -70002 : "Microdroid payload", ; Component name
- (? -71000: tstr // ; Path to the payload config file
- ? -71001: PayloadConfig),
- ? -71002: [+ SubcomponentDescriptor],
-}
-
-PayloadConfig = {
- 1: tstr ; Path to the binary file where payload execution starts
-}
-
-; Describes a unit of code (e.g. an APK or an APEX) present inside the VM.
-;
-; For an APK, the fields are as follows:
-; - Component name: The string "apk:" followed by the package name.
-; - Security version: The long version code from the APK manifest
-; (https://developer.android.com/reference/android/content/pm/PackageInfo#getLongVersionCode()).
-; - Code hash: This is the root hash of a Merkle tree computed over all bytes of the APK, as used
-; in the APK Signature Scheme v4 (https://source.android.com/docs/security/features/apksigning/v4)
-; with empty salt and using SHA-256 as the hash algorithm.
-; - Authority hash: The SHA-512 hash of the DER representation of the X.509 certificate for the
-; public key used to sign the APK.
-;
-; For an APEX, they are as follows:
-; - Component name: The string "apex:" followed by the APEX name as specified in the APEX Manifest
-; (see https://source.android.com/docs/core/ota/apex).
-; - Security version: The version number from the APEX Manifest.
-; - Code hash: The root hash of the apex_payload.img file within the APEX, taken from the first
-; hashtree descriptor in the VBMeta image
-; (see https://android.googlesource.com/platform/external/avb/+/master/README.md).
-; - Authority hash: The SHA-512 hash of the public key used to sign the file system image in the
-; APEX (as stored in the apex_pubkey file). The format is as described for AvbRSAPublicKeyHeader
-; in https://cs.android.com/android/platform/superproject/main/+/main:external/avb/libavb/avb_crypto.h.
-SubcomponentDescriptor = {
- 1: tstr, ; Component name
- 2: uint, ; Security version
- 3: bstr, ; Code hash
- 4: bstr, ; Authority hash
-}
diff --git a/microdroid_manager/src/vm_secret.rs b/microdroid_manager/src/vm_secret.rs
index c16a45e..1ad2d88 100644
--- a/microdroid_manager/src/vm_secret.rs
+++ b/microdroid_manager/src/vm_secret.rs
@@ -171,7 +171,7 @@
// rollback protection of pvmfw. Such components may chose to not put SECURITY_VERSION in the
// corresponding DiceChainEntry.
// 4. For each Subcomponent on the last DiceChainEntry (which corresponds to VM payload, See
-// microdroid_manager/src/vm_config.cddl):
+// dice_for_avf_guest.cddl):
// - GreaterOrEqual on SECURITY_VERSION (Required)
// - ExactMatch on AUTHORITY_HASH (Required).
// 5. ExactMatch on Instance Hash (Required) - This uniquely identifies one VM instance from
diff --git a/pvmfw/src/dice.rs b/pvmfw/src/dice.rs
index da19931..8be73a4 100644
--- a/pvmfw/src/dice.rs
+++ b/pvmfw/src/dice.rs
@@ -26,10 +26,11 @@
use pvmfw_avb::{Capability, DebugLevel, Digest, VerifiedBootData};
use zerocopy::AsBytes;
+// pVM firmware (like other VM components) is expected to populate some fields in DICE
+// Configuration Descriptor. See dice_for_avf_guest.cddl
const COMPONENT_NAME_KEY: i64 = -70002;
const SECURITY_VERSION_KEY: i64 = -70005;
const RKP_VM_MARKER_KEY: i64 = -70006;
-// TODO(b/291245237): Document this key along with others used in ConfigDescriptor in AVF based VM.
const INSTANCE_HASH_KEY: i64 = -71003;
#[derive(Debug)]