[attestation] Document pVM remote attestation
Bug: 330868880
Test: N/A pure document update
Change-Id: Ib4514f1d76e8df192528e7a2741a4a1c88b0709f
diff --git a/docs/vm_remote_attestation.md b/docs/vm_remote_attestation.md
index 093418b..ddb7adf 100644
--- a/docs/vm_remote_attestation.md
+++ b/docs/vm_remote_attestation.md
@@ -1,3 +1,98 @@
# VM Remote Attestation
-(To be filled)
+## Introduction
+
+In today's digital landscape, where security threats are ever-evolving, ensuring
+the authenticity and integrity of VMs is paramount. This is particularly crucial
+for sensitive applications, such as those running machine learning models, where
+guaranteeing a trusted and secure execution environment is essential.
+
+VM remote attestation provides a powerful mechanism for *protected VMs* (pVMs)
+to prove their trustworthiness to a third party. This process allows a pVM to
+demonstrate that:
+
+- All its components, including firmware, operating system, and software, are
+ valid and have not been tampered with.
+- It is running on a valid device trusted by the
+ [Remote Key Provisioning][rkp] (RKP) backend, such as Google.
+
+[rkp]: https://source.android.com/docs/core/ota/modular-system/remote-key-provisioning
+
+## Design
+
+The process of pVM remote attestation involves the use of a lightweight
+intermediate VM known as the [RKP VM][rkpvm]. It allows us to divide the
+attestation process into two parts:
+
+1. Attesting the RKP VM against the RKP server.
+2. Attesting the pVM against the RKP VM.
+
+[rkpvm]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/service_vm/README.md
+
+### RKP VM attestation
+
+The RKP VM is recognized and attested by the RKP server, which acts as a trusted
+entity responsible for verifying the [DICE chain][open-dice] of the RKP VM. This
+verification ensures that the RKP VM is operating on a genuine device.
+Additionally, the RKP VM is validated by the pVM Firmware, as part of the
+verified boot process.
+
+[open-dice]: https://android.googlesource.com/platform/external/open-dice/+/main/docs/android.md
+
+### pVM attestation
+
+Once the RKP VM is successfully attested, it acts as a trusted platform to
+attest pVMs. Leveraging its trusted status, the RKP VM validates the integrity
+of each pVM's DICE chain by comparing it against its own DICE chain. This
+validation process ensures that the pVMs are running in the expected VM
+environment and certifies the payload executed within each pVM. Currently, only
+Microdroid VMs are supported.
+
+## API
+
+To request remote attestation of a pVM, the [VM Payload API][api]
+`AVmPayload_requestAttestation(challenge)` can be invoked within the pVM
+payload.
+
+For detailed information and usage examples, please refer to the
+[demo app][demo].
+
+[api]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/vm_payload/README.md
+[demo]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/service_vm/demo_apk
+
+## Output
+
+Upon successful completion of the attestation process, a pVM receives an
+RKP-backed certificate chain and an attested private key that is exclusively
+known to the pVM. This certificate chain includes a leaf certificate covering
+the attested public key. Notably, the leaf certificate features a new extension
+with the OID `1.3.6.1.4.1.11129.2.1.29.1`, specifically designed to describe the
+pVM payload for third-party verification.
+
+The extension format is as follows:
+
+```
+AttestationExtension ::= SEQUENCE {
+ attestationChallenge OCTET_STRING,
+ isVmSecure BOOLEAN,
+ vmComponents SEQUENCE OF VmComponent,
+}
+
+VmComponent ::= SEQUENCE {
+ name UTF8String,
+ securityVersion INTEGER,
+ codeHash OCTET STRING,
+ authorityHash OCTET STRING,
+}
+```
+
+In `AttestationExtension`:
+
+- The `attestationChallenge` field represents a challenge provided by the
+ third party. It is passed to `AVmPayload_requestAttestation()` to ensure
+ the freshness of the certificate.
+- The `isVmSecure` field indicates whether the attested pVM is secure. It is
+ set to true only when all the DICE certificates in the pVM DICE chain are in
+ normal mode.
+- The `vmComponents` field contains a list of all the APKs and apexes loaded
+ by the pVM.
diff --git a/service_vm/README.md b/service_vm/README.md
index 3d94f78..ca03c1d 100644
--- a/service_vm/README.md
+++ b/service_vm/README.md
@@ -18,28 +18,12 @@
## RKP VM (Remote Key Provisioning Virtual Machine)
-The RKP VM is a key dependency of the Service VM. It is a virtual machine that
-undergoes validation by the [RKP][rkp] Server and acts as a remotely provisioned
-component for verifying the integrity of other virtual machines.
+Currently, the Service VM only supports VM remote attestation, and in that
+context we refer to it as the RKP VM. The RKP VM undergoes validation by the
+[RKP][rkp] Server and functions as a remotely provisioned component responsible
+for verifying the integrity of other virtual machines. See
+[VM remote attestation][vm-attestation] for more details about the role of RKP
+VM in remote attestation.
[rkp]: https://source.android.com/docs/core/ota/modular-system/remote-key-provisioning
-
-### RKP VM attestation
-
-The RKP VM is recognized and attested by the RKP server, which acts as a trusted
-entity responsible for verifying the DICE chain of the RKP VM. This verification
-ensures that the RKP VM is operating on a genuine device.
-Additionally, the RKP VM is validated by the pVM Firmware, as part of the
-verified boot process.
-
-### Client VM attestation
-
-Once the RKP VM is successfully attested, it assumes the role of a trusted
-platform to attest client VMs. It leverages its trusted status to validate the
-integrity of the [DICE chain][open-dice] associated with each client VM. This
-validation process verifies that the client VMs are running in the expected
-[Microdroid][microdroid] VM environment, and certifies the payload executed
-within the VM. Currently, only Microdroid VMs are supported.
-
-[open-dice]: https://android.googlesource.com/platform/external/open-dice/+/main/docs/android.md
-[microdroid]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/microdroid/README.md
+[vm-attestation]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/docs/vm_remote_attestation.md
diff --git a/service_vm/requests/src/cert.rs b/service_vm/requests/src/cert.rs
index 91281e7..e31d870 100644
--- a/service_vm/requests/src/cert.rs
+++ b/service_vm/requests/src/cert.rs
@@ -43,7 +43,7 @@
/// Attestation extension contents
///
/// ```asn1
-/// AttestationDescription ::= SEQUENCE {
+/// AttestationExtension ::= SEQUENCE {
/// attestationChallenge OCTET_STRING,
/// isVmSecure BOOLEAN,
/// vmComponents SEQUENCE OF VmComponent,