1# pVM DICE Chain
2
3A VM [DICE][open-dice] chain is a cryptographically linked
4[certificates chain][cert-chain] that captures measurements of the VM's
5entire execution environment.
6
7This chain should be rooted in the device's ROM and encompass all components
8involved in the VM's loading and boot process. To achieve this, we typically
9extract measurements of all the components after verified boot at each stage
10of the boot process. These measurements are then used to derive a new DICE
11certificate describing the next boot stage.
12
13![][pvm-dice-chain-built-img]
14
15[pvm-dice-chain-built-img]: img/pvm-dice-built-during-boot.png
16[cert-chain]: https://en.wikipedia.org/wiki/Chain_of_trust
17
18## Vendor responsibility
19
20Vendors are responsible for constructing the first portion of the DICE chain,
21from ROM to the pvmfw loader (e.g., ABL). This portion describes the VM's
22loading environment. The final certificate in the vendor's chain must include
23measurements of pvmfw, the hypervisor, and any other code relevant to pvmfw's
24secure execution.
25
26## pVM DICE handover
27
28Vendors then pass this DICE chain, along with its corresponding
29[CDI values][dice-cdi], in a handover to pvmfw. The pVM takes over this
30handover and extends it with additional nodes describing its own execution
31environment.
32
33[dice-cdi]: https://android.googlesource.com/platform/external/open-dice/+/main/docs/specification.md#cdi-values
34![][pvm-dice-handover-img]
35
36### Key derivation
37
38Key derivation is a critical step in the DICE handover process within
39[pvmfw][pvmfw]. Vendors need to ensure that both pvmfw and their final DICE
40node use the same method to derive a key pair from `CDI_Attest` in order to
41maintain a valid certificate chain. Pvmfw uses [open-dice][open-dice] with the
42following formula:
43
44```
45CDI_Attest_pub, CDI_Attest_priv = KDF_ASYM(KDF(CDI_Attest))
46```
47
48Where KDF = HKDF-SHA-512 (RFC 5869).
49
50Currently, KDF_ASYM = Ed25519, but EC p-384 and p-256 (RFC 6979) support is
51coming soon.
52
53Vendors must use a supported algorithm for the last DICE node to ensure
54compatibility and chain integrity.
55
56[pvmfw]: ../guest/pvmfw
57[pvm-dice-handover-img]: img/pvm-dice-handover.png
58[open-dice]: https://android.googlesource.com/platform/external/open-dice/+/main/docs/specification.md
59
60## Validation
61
62While pvmfw and the Microdroid OS extend the VM DICE chain, they don't
63perform comprehensive validation of the chain's structure or its ROM-rooted
64origin. The [VM Remote Attestation][vm-attestation] feature is specifically
65designed to ensure the validity and ROM-rooted nature of a VM DICE chain.
66
67[vm-attestation]: vm_remote_attestation.md
68
69## Testing
70
71To verify that the DICE handover is successful in pvmfw and eventually the pVM
72has a valid DICE chain, you can run the VSR test
73`MicrodroidTests#protectedVmHasValidDiceChain`. The test retrieves the DICE
74chain from within a Microdroid VM in protected mode and checks the following
75properties using the [hwtrust][hwtrust] library:
76
771. All the fields in the DICE chain conform to
78   [Android Profile for DICE][android-open-dice].
792. The DICE chain is a valid certificate chain, where the subject public key in
80   each certificate can be used to verify the signature of the next certificate.
81
82[hwtrust]: https://cs.android.com/android/platform/superproject/main/+/main:tools/security/remote_provisioning/hwtrust/
83[android-open-dice]: https://android.googlesource.com/platform/external/open-dice/+/refs/heads/main/docs/android.md
84