1# Updatable VM
2
3From Android V+, AVF (with Microdroid) supports Updatable VMs. This allows the VM instances to
4remain stable even when the VM core components and payload are upgraded. This includes (but is not
5limited to) update of payload apk and Microdroid OS.
6
7## Background
8
9The following constructs have been used (and are critical) to support Updatable VM:
10
111. [Secretkeeper][sk_project] is the critical piece of solution. It provides secure storage for VM's
12   secrets. It is specified as [a HAL][secretkeeperhal] and needs to be implemented in an
13   environment with privilege higher than protected VM.
141. [DICE Policies][dice_policy]: DICE policy is the mechanism for setting constraints on a DICE
15   chain(i.e., identities of a VM). VM seals its secrets using DICE policies, and Secretkeeper
16   serves as a policy verifier.
171. [AuthGraph key exchange][authgraphke]: The requests/responses between pVM and Secretkeeper are
18   ferried via Android (which is untrusted). A cryptographically secure channel is setup using
19   AuthGraph key exchange.
20
21## VmSecrets::V2
22
23Updatable VMs are achieved by changing Microdroid's secret management. It now supports
24`VmSecrets::V2` which is derived from 2 independently secured secrets:
25
261. Secretkeeper protected secret: This is random 64 bytes generated by VM on first boot & stored in
27   Secretkeeper.
281. DICE Sealing CDIs (similar to legacy secrets V1): These are defined by
29   [Open Profile for DICE][open_dice_spec_cdi] and must remain the same across software updates.
30
31Secretkeeper protected secret is protected against rollback of boot images i.e. VM instance rebooted
32with downgraded images will not have access to these secrets. This is done using
33[Policy Gated Storage feature](policy_gated_storage) of Secretkeeper. On the first boot of the VM
34instance, Microdroid Manager (on behalf of the VM payload) generates a secret, stores it in
35Secretkeeper and on further reboots, this is retrieved from it. Along with this secret, a
36[sealing policy](#sealing-policy) is also stored (in Secretkeeper) that ensures that secrets are not
37released to the VM instance booted with downgraded images.
38
39Each Secretkeeper client needs a 64 bytes' Id to store an entry in Secretkeeper. For Microdroid,
40this is Instance Id. It is allocated by host (when the VM instance is created) and relayed to VM via a property (`instance-id`)
41in device tree node (`/avf/untrusted`)
42
43## Sealing Policy
44
45Sealing Policy is a DICE policy on the DICE chain of the payload running in Microdroid. This is
46constructed by Microdroid Manager on behalf of the payload and is stored along with the secret.
47
48A highly simplified view - Sealing policy built by Microdroid has the following constraints:
49
50- ExactMatch on DiceCertChainInitialPayload (root public key)
51- ExactMatch of Instance salt, this is present in DiceChainEntry corresponding to OS (and is derived
52  deterministically from Instance Id). This is needed to prevent the secrets of one instance from
53  being accessible to another instance running with the same VM images.
54- For each DiceChainEntry:
55  1. ExactMatch on AUTHORITY_HASH.
56  1. ExactMatch on MODE - Secret should be inaccessible if any of the runtime
57     configuration changes. For example, the secrets stored with a boot stage being in Normal mode
58     should be inaccessible when the same stage is booted in Debug mode.
59  1. GreaterOrEqual on SECURITY_VERSION: The secrets will be accessible if version of any
60     image is greater or equal to the set version.
61- For each Subcomponent on the last DiceChainEntry (which corresponds to VM payload, See
62  [vm_config.cddl][vm_config_cddl]): - GreaterOrEqual on SECURITY_VERSION - ExactMatch on
63  AUTHORITY_HASH.
64
65The sealing policy is updated each time the secret is retrieved. This ensures the secrets are only
66released if the security version of the images are non-decreasing.
67
68## Deferring rollback protection
69
70Traditionally in Android, each boot stage is responsible for rollback protection of the next boot
71image. ABL has access to tamper evident storage to ensure that. VM (Android U and lower) use
72instance.img where the boot stages (pvmfw/Microdroid) would store information about packages they
73boot (exact code_hash) and on subsequent boot of the instance ensure that the same images are
74allowed to run. This prevented running of older images, but also prevented running newer images and
75hence VMs were not updatable.
76
77Secretkeeper HAL then introduced the capability of storing secrets in a TA such that the owner of
78the secret ( for ex. VM) while storing it, includes a corresponding sealing policy such that only
79entities with DICE chain that adheres to those policies can access the secrets.
80
81This allows the bootloaders to defer rollback protection to the payload. Host relays this intention
82to pVM (both pVM firmware and OS) using the property (`defer-rollback-protection`) in device tree
83node (`/avf/untrusted`). If this is set and the guest OS is capable of `SecretkeeperProtection` then
84VMs use Secretkeeper based rollback protection.
85
86### Note on legacy support
87
88If the device does not support Secretkeeper, Microdroid will fallback to legacy secrets
89(`VmSecrets::V1`). These are not protected against the rollback of boot images and hence pVM
90firmware cannot defer rollback protection. Instance image is used to record information about the
91images on the first boot of the instance, and any further boot prevents any different image from
92running i.e, Updatable VMs are not supported.
93
94[authgraphke]: https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/security/authgraph/aidl/android/hardware/security/authgraph/IAuthGraphKeyExchange.aidl
95[dice_policy]: https://android.googlesource.com/platform/system/secretkeeper/+/refs/heads/main/dice_policy/
96[open_dice_spec_cdi]: https://pigweed.googlesource.com/open-dice/+/HEAD/docs/specification.md#cdi-values
97[secretkeeperhal]: https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/security/secretkeeper/aidl/android/hardware/security/secretkeeper/ISecretkeeper.aidl
98[sk_project]: https://android.googlesource.com/platform/system/secretkeeper/
99[vm_config_cddl]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/microdroid_manager/src/vm_config.cddl
100