# VM Remote Attestation

## 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/docs/service_vm.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.

During the validation process, the RKP server compares the root public key of the
DICE chain with the ones registered in the RKP database. Additionally, the server
examines the presence of the [RKP VM marker][rkpvm-marker] within the DICE
certificates to determine the origin of the chain, confirming that it indeed
originates from the RKP VM. For more detailed information about the RKP VM
DICE chain validation, please refer to the [Remote Provisioning HAL][rkp-hal]
spec.

[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 DICE chain][pvm-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.

[pvm-dice-chain]: ./pvm_dice_chain.md

## 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/libs/libvm_payload/README.md
[demo]: https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/android/VmAttestationDemoApp

## 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. These components are extracted from the config descriptor of the
    last DiceChainEntry of the pVM DICE chain. Refer to
    [dice_for_avf_guest.cddl][dice_for_avf_guest_cddl] for more information.

[dice_for_avf_guest_cddl]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/dice_for_avf_guest.cddl

## To Support It

VM remote attestation is a strongly recommended feature from Android V. To
support it, you only need to provide a valid VM DICE chain satisfying the
following requirements:

- The DICE chain must have a UDS-rooted public key registered at the RKP
  factory.
- The DICE chain must use [RKP VM markers][rkpvm-marker] to help identify the
  RKP VM as required by the [remote provisioning HAL][rkp-hal].

### RKP VM marker

To support VM remote attestation, vendors must include an RKP VM marker in their
DICE certificates. This marker should be present from the early boot stage
within the TEE and continue through to the leaf DICE certificate before
[pvmfw][pvmfw] takes over.

![RKP VM DICE chain][rkpvm-dice-chain]

Pvmfw will add an RKP VM marker when it's launching an RKP VM. The __continuous
presence__ of this marker throughout the chain allows the RKP server to clearly
identify legitimate RKP VM DICE chains.

This mechanism also serves as a security measure. If an attacker tries to launch
a malicious guest OS or payload, their DICE chain will be rejected by the RKP
server because it will lack the RKP VM marker that pvmfw would have added in a
genuine RKP VM boot process.

### Testing

To ensure the correct implementation and usage of RKP VM markers, we've
incorporated comprehensive checks into various xTS tests (e.g.,
`VtsHalRemotelyProvisionedComponentTargetTest`).

These tests validate the following conditions:

- The RKP VM DICE chain must have a continuous presence of at least two RKP VM
  markers, extending to the leaf DICE certificate.
- Non-RKP VM DICE chains must not have a continuous presence of two or more RKP
  VM markers, preventing non-RKP VM chains from being incorrectly identified as
  RKP VM chains.

[pvmfw]: ../guest/pvmfw/README.md
[rkpvm-dice-chain]: img/rkpvm-dice-chain.png

## To Disable It

The feature is enabled by default. To disable it, you have two options:

1. Set `PRODUCT_AVF_REMOTE_ATTESTATION_DISABLED` to `true` in your Makefile to
   disable the feature at build time.

2. Set the system property `avf.remote_attestation.enabled` to `0` to disable
   the feature at boot time by including the following line in vendor init:
   `setprop avf.remote_attestation.enabled 0`.

If you don't set any of these variables, VM remote attestation will be enabled
by default.

[rkpvm-marker]: https://pigweed.googlesource.com/open-dice/+/HEAD/docs/android.md#configuration-descriptor
[rkp-hal]: https://android.googlesource.com/platform/hardware/interfaces/+/main/security/rkp/README.md#hal