[doc] Update DICE handover spec in pvmfw accroding to VSR-15
Bug: 354182571
Test: N/A. Only text change
Change-Id: I75a6a31aff981e3731be1d1f9d60c1b961255ae1
diff --git a/docs/img/pvm-dice.png b/docs/img/pvm-dice.png
new file mode 100644
index 0000000..5b26038
--- /dev/null
+++ b/docs/img/pvm-dice.png
Binary files differ
diff --git a/docs/pvm_dice_chain.md b/docs/pvm_dice_chain.md
new file mode 100644
index 0000000..11cdb6f
--- /dev/null
+++ b/docs/pvm_dice_chain.md
@@ -0,0 +1,52 @@
+# pVM DICE Chain
+
+Unlike KeyMint, which only needs a vendor DICE chain, the pVM DICE
+chain combines the vendor's DICE chain with additional pVM DICE nodes
+describing the protected VM's environment.
+
+![][pvm-dice-chain-img]
+
+The full RKP VM DICE chain, starting from `UDS_Pub` rooted in ROM, is
+sent to the RKP server during [pVM remote attestation][vm-attestation].
+
+[vm-attestation]: vm_remote_attestation.md
+[pvm-dice-chain-img]: img/pvm-dice.png
+
+## Key derivation
+
+Key derivation is a critical step in the DICE handover process within
+[pvmfw][pvmfw]. Vendors need to ensure that both pvmfw and their final DICE
+node use the same method to derive a key pair from `CDI_Attest` in order to
+maintain a valid certificate chain. Pvmfw use [open-dice][open-dice] with the
+following formula:
+
+```
+CDI_Attest_pub, CDI_Attest_priv = KDF_ASYM(KDF(CDI_Attest))
+```
+
+Where KDF = HKDF-SHA-512 (RFC 5869).
+
+Currently, KDF_ASYM = Ed25519, but EC p-384 and p-256 (RFC 6979) support is
+coming soon.
+
+Vendors must use a supported algorithm for the last DICE node to ensure
+compatibility and chain integrity.
+
+[pvmfw]: ../guest/pvmfw
+[open-dice]: https://cs.android.com/android/platform/superproject/main/+/main:external/open-dice/
+
+## Testing
+
+To verify that the DICE handover is successful in pvmfw and eventually the pVM
+has a valid DICE chain, you can run the VSR test
+`MicrodroidTests#protectedVmHasValidDiceChain`. The test retrieves the DICE
+chain from within a Microdroid VM in protected mode and checks the following
+properties using the [hwtrust][hwtrust] library:
+
+1. All the fields in the DICE chain conform to
+ [Android Profile for DICE][android-open-dice].
+2. The DICE chain is a valid certificate chain, where the subject public key in
+ each certificate can be used to verify the signature of the next certificate.
+
+[hwtrust]: https://cs.android.com/android/platform/superproject/main/+/main:tools/security/remote_provisioning/hwtrust/
+[android-open-dice]: https://android.googlesource.com/platform/external/open-dice/+/refs/heads/main/docs/android.md
diff --git a/guest/pvmfw/README.md b/guest/pvmfw/README.md
index 4712d77..58ba10c 100644
--- a/guest/pvmfw/README.md
+++ b/guest/pvmfw/README.md
@@ -251,10 +251,13 @@
}
```
-and contains the _Compound Device Identifiers_ ("CDIs"), used to derive the
-next-stage secret, and a certificate chain, intended for pVM attestation. Note
-that it differs from the `AndroidDiceHandover` defined by the specification in
-that its `DiceCertChain` field is mandatory (while optional in the original).
+It contains the _Compound Device Identifiers_ (CDIs), used for deriving the
+next-stage secret, and a certificate chain, necessary for building the full
+[pVM DICE chain][pvm-dice-chain] required by features like
+[pVM remote attestation][vm-attestation].
+
+Note that it differs from the `AndroidDiceHandover` defined by the specification
+in that its `DiceCertChain` field is mandatory (while optional in the original).
Devices that fully implement DICE should provide a certificate rooted at the
Unique Device Secret (UDS) in a boot stage preceding the pvmfw loader (typically
@@ -262,16 +265,6 @@
can be passed to [`DiceAndroidHandoverMainFlow`][DiceAndroidHandoverMainFlow] along with
the inputs described below.
-Otherwise, as an intermediate step towards supporting DICE throughout the
-software stack of the device, incomplete implementations may root the DICE chain
-at the pvmfw loader, using an arbitrary constant as initial CDI. The pvmfw
-loader can easily do so by:
-
-1. Building an "empty" `AndroidDiceHandover` using CBOR operations only
- containing constant CDIs ([example][Trusty-BCC])
-1. Passing the resulting `AndroidDiceHandover` to `DiceAndroidHandoverMainFlow`
- as described above
-
The recommended DICE inputs at this stage are:
- **Code**: hash of the pvmfw image, hypervisor (`boot.img`), and other target
@@ -291,19 +284,6 @@
`/reserved-memory` device tree node marked as
[`compatible=”google,open-dice”`][dice-dt].
-#### Testing
-
-To verify that the DICE handover is successful in pvmfw and eventually the pVM
-has a valid DICE chain, you can run the VSR test
-`MicrodroidTests#protectedVmHasValidDiceChain`. The test retrieves the DICE
-chain from within a Microdroid VM in protected mode and checks the following
-properties using the [hwtrust][hwtrust] library:
-
-1. All the fields in the DICE chain conform to
- [Android Profile for DICE][android-open-dice].
-2. The DICE chain is a valid certificate chain, where the subject public key in
- each certificate can be used to verify the signature of the next certificate.
-
[AVB]: https://source.android.com/docs/security/features/verifiedboot/boot-flow
[AndroidDiceHandover]: https://pigweed.googlesource.com/open-dice/+/42ae7760023/src/android.c#212
[DiceAndroidHandoverMainFlow]: https://pigweed.googlesource.com/open-dice/+/42ae7760023/src/android.c#221
@@ -311,9 +291,8 @@
[dice-mode]: https://pigweed.googlesource.com/open-dice/+/refs/heads/main/docs/specification.md#Mode-Value-Details
[dice-dt]: https://www.kernel.org/doc/Documentation/devicetree/bindings/reserved-memory/google%2Copen-dice.yaml
[Layering]: https://pigweed.googlesource.com/open-dice/+/refs/heads/main/docs/specification.md#layering-details
-[Trusty-BCC]: https://android.googlesource.com/trusty/lib/+/1696be0a8f3a7103/lib/hwbcc/common/swbcc.c#554
-[hwtrust]: https://cs.android.com/android/platform/superproject/main/+/main:tools/security/remote_provisioning/hwtrust/
-[android-open-dice]: https://android.googlesource.com/platform/external/open-dice/+/refs/heads/main/docs/android.md
+[pvm-dice-chain]: ../../docs/pvm_dice_chain.md
+[vm-attestation]: ../../docs/vm_remote_attestation.md
### Platform Requirements
