1# VM Remote Attestation
2
3## Introduction
4
5In today's digital landscape, where security threats are ever-evolving, ensuring
6the authenticity and integrity of VMs is paramount. This is particularly crucial
7for sensitive applications, such as those running machine learning models, where
8guaranteeing a trusted and secure execution environment is essential.
9
10VM remote attestation provides a powerful mechanism for *protected VMs* (pVMs)
11to prove their trustworthiness to a third party. This process allows a pVM to
12demonstrate that:
13
14-   All its components, including firmware, operating system, and software, are
15    valid and have not been tampered with.
16-   It is running on a valid device trusted by the
17    [Remote Key Provisioning][rkp] (RKP) backend, such as Google.
18
19[rkp]: https://source.android.com/docs/core/ota/modular-system/remote-key-provisioning
20
21## Design
22
23The process of pVM remote attestation involves the use of a lightweight
24intermediate VM known as the [RKP VM][rkpvm]. It allows us to divide the
25attestation process into two parts:
26
271.  Attesting the RKP VM against the RKP server.
282.  Attesting the pVM against the RKP VM.
29
30[rkpvm]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/docs/service_vm.md
31
32### RKP VM attestation
33
34The RKP VM is recognized and attested by the RKP server, which acts as a trusted
35entity responsible for verifying the [DICE chain][open-dice] of the RKP VM. This
36verification ensures that the RKP VM is operating on a genuine device.
37Additionally, the RKP VM is validated by the pVM Firmware, as part of the
38verified boot process.
39
40During the validation process, the RKP server compares the root public key of the
41DICE chain with the ones registered in the RKP database. Additionally, the server
42examines the presence of the [RKP VM marker][rkpvm-marker] within the DICE
43certificates to determine the origin of the chain, confirming that it indeed
44originates from the RKP VM. For more detailed information about the RKP VM
45DICE chain validation, please refer to the [Remote Provisioning HAL][rkp-hal]
46spec.
47
48[open-dice]: https://android.googlesource.com/platform/external/open-dice/+/main/docs/android.md
49
50### pVM attestation
51
52Once the RKP VM is successfully attested, it acts as a trusted platform to
53attest pVMs. Leveraging its trusted status, the RKP VM validates the integrity
54of each [pVM DICE chain][pvm-dice-chain] by comparing it against its own DICE
55chain. This validation process ensures that the pVMs are running in the expected
56VM environment and certifies the payload executed within each pVM. Currently,
57only Microdroid VMs are supported.
58
59[pvm-dice-chain]: ./pvm_dice_chain.md
60
61## API
62
63To request remote attestation of a pVM, the [VM Payload API][api]
64`AVmPayload_requestAttestation(challenge)` can be invoked within the pVM
65payload.
66
67For detailed information and usage examples, please refer to the
68[demo app][demo].
69
70[api]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/libs/libvm_payload/README.md
71[demo]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/android/VmAttestationDemoApp
72
73## Output
74
75Upon successful completion of the attestation process, a pVM receives an
76RKP-backed certificate chain and an attested private key that is exclusively
77known to the pVM. This certificate chain includes a leaf certificate covering
78the attested public key. Notably, the leaf certificate features a new extension
79with the OID `1.3.6.1.4.1.11129.2.1.29.1`, specifically designed to describe the
80pVM payload for third-party verification.
81
82The extension format is as follows:
83
84```
85AttestationExtension ::= SEQUENCE {
86    attestationChallenge       OCTET_STRING,
87    isVmSecure                 BOOLEAN,
88    vmComponents               SEQUENCE OF VmComponent,
89}
90
91VmComponent ::= SEQUENCE {
92    name               UTF8String,
93    securityVersion    INTEGER,
94    codeHash           OCTET STRING,
95    authorityHash      OCTET STRING,
96}
97```
98
99In `AttestationExtension`:
100
101-   The `attestationChallenge` field represents a challenge provided by the
102    third party. It is passed to `AVmPayload_requestAttestation()` to ensure
103    the freshness of the certificate.
104-   The `isVmSecure` field indicates whether the attested pVM is secure. It is
105    set to true only when all the DICE certificates in the pVM DICE chain are in
106    normal mode.
107-   The `vmComponents` field contains a list of all the APKs and apexes loaded
108    by the pVM. These components are extracted from the config descriptor of the
109    last DiceChainEntry of the pVM DICE chain. Refer to
110    [dice_for_avf_guest.cddl][dice_for_avf_guest_cddl] for more information.
111
112[dice_for_avf_guest_cddl]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/dice_for_avf_guest.cddl
113
114## To Support It
115
116VM remote attestation is a strongly recommended feature from Android V. To
117support it, you only need to provide a valid VM DICE chain satisfying the
118following requirements:
119
120- The DICE chain must have a UDS-rooted public key registered at the RKP
121  factory.
122- The DICE chain must use [RKP VM markers][rkpvm-marker] to help identify the
123  RKP VM as required by the [remote provisioning HAL][rkp-hal].
124
125### RKP VM marker
126
127To support VM remote attestation, vendors must include an RKP VM marker in their
128DICE certificates. This marker should be present from the early boot stage
129within the TEE and continue through to the leaf DICE certificate before
130[pvmfw][pvmfw] takes over.
131
132![RKP VM DICE chain][rkpvm-dice-chain]
133
134Pvmfw will add an RKP VM marker when it's launching an RKP VM. The __continuous
135presence__ of this marker throughout the chain allows the RKP server to clearly
136identify legitimate RKP VM DICE chains.
137
138This mechanism also serves as a security measure. If an attacker tries to launch
139a malicious guest OS or payload, their DICE chain will be rejected by the RKP
140server because it will lack the RKP VM marker that pvmfw would have added in a
141genuine RKP VM boot process.
142
143### Testing
144
145To ensure the correct implementation and usage of RKP VM markers, we've
146incorporated comprehensive checks into various xTS tests (e.g.,
147`VtsHalRemotelyProvisionedComponentTargetTest`).
148
149These tests validate the following conditions:
150
151- The RKP VM DICE chain must have a continuous presence of at least two RKP VM
152  markers, extending to the leaf DICE certificate.
153- Non-RKP VM DICE chains must not have a continuous presence of two or more RKP
154  VM markers, preventing non-RKP VM chains from being incorrectly identified as
155  RKP VM chains.
156
157[pvmfw]: ../guest/pvmfw/README.md
158[rkpvm-dice-chain]: img/rkpvm-dice-chain.png
159
160## To Disable It
161
162The feature is enabled by default. To disable it, you have two options:
163
1641. Set `PRODUCT_AVF_REMOTE_ATTESTATION_DISABLED` to `true` in your Makefile to
165   disable the feature at build time.
166
1672. Set the system property `avf.remote_attestation.enabled` to `0` to disable
168   the feature at boot time by including the following line in vendor init:
169   `setprop avf.remote_attestation.enabled 0`.
170
171If you don't set any of these variables, VM remote attestation will be enabled
172by default.
173
174[rkpvm-marker]: https://pigweed.googlesource.com/open-dice/+/HEAD/docs/android.md#configuration-descriptor
175[rkp-hal]: https://android.googlesource.com/platform/hardware/interfaces/+/main/security/rkp/README.md#hal
176