Move vm_payload to libs/libvm_payload
Bug: 352458998
Test: pass TH
Change-Id: Ibb1364410c12e3b4daaa9f81d4ec830ccdbf475f
diff --git a/libs/libvm_payload/Android.bp b/libs/libvm_payload/Android.bp
new file mode 100644
index 0000000..cf2a002
--- /dev/null
+++ b/libs/libvm_payload/Android.bp
@@ -0,0 +1,120 @@
+package {
+ default_applicable_licenses: ["Android-Apache-2.0"],
+}
+
+// The Rust implementation of the C API.
+rust_ffi_static {
+ name: "libvm_payload_impl",
+ crate_name: "vm_payload",
+ defaults: ["avf_build_flags_rust"],
+ visibility: ["//visibility:private"],
+ srcs: ["src/lib.rs"],
+ include_dirs: ["include"],
+ prefer_rlib: true,
+ rustlibs: [
+ "android.system.virtualization.payload-rust",
+ "libandroid_logger",
+ "libanyhow",
+ "libbinder_rs",
+ "liblazy_static",
+ "liblibc",
+ "liblog_rust",
+ "libopenssl",
+ "librpcbinder_rs",
+ "libvm_payload_status_bindgen",
+ "libvsock",
+ ],
+}
+
+rust_bindgen {
+ name: "libvm_payload_status_bindgen",
+ wrapper_src: "include/vm_payload.h",
+ crate_name: "vm_payload_status_bindgen",
+ defaults: ["avf_build_flags_rust"],
+ source_stem: "bindings",
+ bindgen_flags: [
+ "--default-enum-style rust",
+ "--allowlist-type=AVmAttestationStatus",
+ ],
+ visibility: [":__subpackages__"],
+}
+
+// Access to the C API for Rust code.
+// This shouldn't be used directly - prefer libvm_payload_rs (below)
+rust_bindgen {
+ name: "libvm_payload_bindgen",
+ wrapper_src: "include-restricted/vm_payload_restricted.h",
+ crate_name: "vm_payload_bindgen",
+ defaults: ["avf_build_flags_rust"],
+ source_stem: "bindings",
+ apex_available: ["com.android.compos"],
+ bindgen_flags: [
+ "--default-enum-style rust",
+ ],
+ shared_libs: [
+ "libvm_payload#current",
+ ],
+}
+
+// Wrapper library for the raw C API for use by Rust clients.
+// (Yes, this involves going Rust -> C -> Rust.)
+// This is not a stable API - we may change it in subsequent versions.
+// But it is made available as an rlib so it is linked into any
+// code using it, leaving only dependencies on stable APIs.
+// So code built with it should run unchanged on future versions.
+rust_library_rlib {
+ name: "libvm_payload_rs",
+ crate_name: "vm_payload",
+ defaults: ["avf_build_flags_rust"],
+ srcs: ["wrapper/lib.rs"],
+ rustlibs: [
+ "libbinder_rs",
+ "libstatic_assertions",
+ "libvm_payload_bindgen",
+ ],
+ apex_available: ["com.android.compos"],
+ visibility: ["//visibility:public"],
+}
+
+// Shared library for clients to link against.
+cc_library_shared {
+ name: "libvm_payload",
+ defaults: ["avf_build_flags_cc"],
+ shared_libs: [
+ "libbinder_ndk",
+ "libbinder_rpc_unstable",
+ "liblog",
+ "libcrypto",
+ ],
+ whole_static_libs: ["libvm_payload_impl"],
+ export_static_lib_headers: ["libvm_payload_impl"],
+ no_full_install: true,
+ version_script: "libvm_payload.map.txt",
+ stubs: {
+ symbol_file: "libvm_payload.map.txt",
+ // Implementation is available inside a Microdroid VM.
+ implementation_installable: false,
+ },
+ visibility: ["//visibility:public"],
+}
+
+// Just the headers. Mostly useful for clients that only want the
+// declaration of AVmPayload_main().
+cc_library_headers {
+ name: "vm_payload_headers",
+ defaults: ["avf_build_flags_cc"],
+ apex_available: ["com.android.compos"],
+ export_include_dirs: ["include"],
+ visibility: ["//visibility:public"],
+}
+
+// Restricted headers for use by internal clients & associated tests.
+cc_library_headers {
+ name: "vm_payload_restricted_headers",
+ defaults: ["avf_build_flags_cc"],
+ header_libs: ["vm_payload_headers"],
+ export_header_lib_headers: ["vm_payload_headers"],
+ export_include_dirs: ["include-restricted"],
+ apex_available: ["com.android.compos"],
+ visibility: ["//packages/modules/Virtualization:__subpackages__"],
+}
diff --git a/libs/libvm_payload/README.md b/libs/libvm_payload/README.md
new file mode 100644
index 0000000..eb2ccf0
--- /dev/null
+++ b/libs/libvm_payload/README.md
@@ -0,0 +1,85 @@
+# VM Payload API
+
+This directory contains the definition of the VM Payload API. This is a native
+API, exposed as a set of C functions, available to payload code running inside a
+[Microdroid](https://android.googlesource.com/platform/packages/modules/Virtualization/+/refs/heads/main/build/microdroid/README.md)
+VM.
+
+Note that only native code is supported in Microdroid, so no Java APIs are
+available in the VM, and only 64 bit code is supported.
+
+To create a VM and run the payload from Android see the [AVF Java
+APIs](../java/framework/README.md).
+
+## Entry point
+
+The payload should be packaged as one (or more) .so files inside the app's APK -
+under the `lib/<ABI>` directory, like other JNI code.
+
+The primary .so, which is specified as part of the VM configuration via
+[VirtualMachineConfig.Builder#setPayloadBinaryPath](https://android.googlesource.com/platform/packages/modules/Virtualization/+/refs/heads/main/java/framework/src/android/system/virtualmachine/VirtualMachineConfig.java),
+must define the entry point for the payload.
+
+This entry point is a C function called `AVmPayload_main()`, as declared in
+[vm_main.h](include/vm_main.h). (In C++ this must be defined as `extern "C"`.)
+
+## API header
+
+The functions available to the payload once it starts are declared in
+[vm_payload.h](include/vm_payload.h).
+
+### Linking
+
+In the Android build system, the payload binary should be built with
+`libvm_payload#current` specified as one of the `shared_libs`; this links
+against a stub `libvm_payload.so`, where the dependencies will be satisfied at
+runtime from the real `libvm_payload.so` hosted within the Microdroid VM.
+
+See `MicrodroidTestNativeLib` in the [test
+APK](https://android.googlesource.com/platform/packages/modules/Virtualization/+/refs/heads/main/tests/testapk/Android.bp)
+for an example.
+
+In other build systems a similar stub `libvm_payload.so` can be built using
+[stub.c](stub/stub.c) and the [linker script](libvm_payload.map.txt).
+
+## Available NDK APIs
+
+In addition to the VM Payload APIs, a small subset of the [Android
+NDK](https://developer.android.com/ndk) can be used by the payload.
+
+This subset consists of:
+- The [standard C library](https://developer.android.com/ndk/guides/stable_apis#c_library).
+- The [Logging APIs](https://developer.android.com/ndk/guides/stable_apis#logging).
+- The [NdkBinder
+ API](https://developer.android.com/ndk/reference/group/ndk-binder). However
+ note that the payload can only host a binder server via
+ `AVmPayload_runVsockRpcServer`, defined in
+ [vm_payload.h](include/vm_payload.h), rather than
+ `AServiceManager_addService`, and cannot connect to any binder server. Passing
+ file descriptors to and from the VM is not supported.
+
+## C++
+
+C++ can be used, but you will need to include the C++ runtime in your APK along
+with your payload, either statically linked (if
+[appropriate](https://developer.android.com/ndk/guides/cpp-support#sr)) or as a
+separate .so.
+
+The same is true for other languages such as Rust.
+
+See [AIDL
+backends](https://source.android.com/docs/core/architecture/aidl/aidl-backends)
+for information on using AIDL with the NDK Binder from C++.
+
+## Rust
+
+A Rust wrapper library for the VM Payload API is available (as an rlib) for VM
+payloads written in Rust.
+
+This wrapper is not guaranteed to be stable; we may change it in future
+versions. But payload code built using it will depend only on the C VM Payload
+API and the NDK APIs that are available to the payload, so should run unchanged
+on future versions.
+
+See [wrapper/lib.rs](wrapper/lib.rs) and `libvm_payload_rs` in
+[Android.bp](Android.bp).
diff --git a/libs/libvm_payload/include-restricted/vm_payload_restricted.h b/libs/libvm_payload/include-restricted/vm_payload_restricted.h
new file mode 100644
index 0000000..5dd12ad
--- /dev/null
+++ b/libs/libvm_payload/include-restricted/vm_payload_restricted.h
@@ -0,0 +1,79 @@
+/*
+ * Copyright (C) 2022 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <sys/cdefs.h>
+
+#include "vm_payload.h"
+
+#if !defined(__INTRODUCED_IN)
+#define __INTRODUCED_IN(__api_level) /* nothing */
+#endif
+
+// The functions declared here are restricted to VMs created with a config file;
+// they will fail if called in other VMs. The ability to create such VMs
+// requires the android.permission.USE_CUSTOM_VIRTUAL_MACHINE permission, and is
+// therefore not available to privileged or third party apps.
+
+// These functions can be used by tests, if the permission is granted via shell.
+
+__BEGIN_DECLS
+
+/**
+ * Get the VM's DICE attestation chain.
+ *
+ * \param data pointer to size bytes where the chain is written (may be null if size is 0).
+ * \param size number of bytes that can be written to data.
+ *
+ * \return the total size of the chain
+ */
+size_t AVmPayload_getDiceAttestationChain(void* _Nullable data, size_t size);
+
+/**
+ * Get the VM's DICE attestation CDI.
+ *
+ * \param data pointer to size bytes where the CDI is written (may be null if size is 0).
+ * \param size number of bytes that can be written to data.
+ *
+ * \return the total size of the CDI
+ */
+size_t AVmPayload_getDiceAttestationCdi(void* _Nullable data, size_t size);
+
+/**
+ * Requests attestation for the VM for testing only.
+ *
+ * This function is only for testing and will not return a real RKP server backed
+ * certificate chain.
+ *
+ * Prior to calling this function, the caller must provision a key pair to be used in
+ * this function with `VirtualMachineManager#enableTestAttestation`.
+ *
+ * \param challenge A pointer to the challenge buffer.
+ * \param challenge_size size of the challenge. The maximum supported challenge size is
+ * 64 bytes. The status ATTESTATION_ERROR_INVALID_CHALLENGE will be returned if
+ * an invalid challenge is passed.
+ * \param result The remote attestation result will be filled here if the attestation
+ * succeeds. The result remains valid until it is freed with
+ * `AVmPayload_freeAttestationResult`.
+ */
+AVmAttestationStatus AVmPayload_requestAttestationForTesting(
+ const void* _Nonnull challenge, size_t challenge_size,
+ struct AVmAttestationResult* _Nullable* _Nonnull result) __INTRODUCED_IN(__ANDROID_API_V__);
+
+__END_DECLS
diff --git a/libs/libvm_payload/include/vm_main.h b/libs/libvm_payload/include/vm_main.h
new file mode 100644
index 0000000..5158b43
--- /dev/null
+++ b/libs/libvm_payload/include/vm_main.h
@@ -0,0 +1,39 @@
+/*
+ * Copyright 2022 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+typedef int AVmPayload_main_t();
+AVmPayload_main_t AVmPayload_main;
+}
+#else
+typedef int AVmPayload_main_t(void);
+
+/**
+ * Entry point for the VM payload. This function must be implemented by the
+ * payload binary, and is called by Microdroid to start the payload inside the
+ * VM.
+ *
+ * When the function returns the VM will be shut down. If the host app has set
+ * a `VirtualMachineCallback` for the VM, its `onPayloadFinished` method will be
+ * called with the VM's exit code.
+ *
+ * \return the exit code of the VM.
+ */
+extern int AVmPayload_main(void);
+#endif
diff --git a/libs/libvm_payload/include/vm_payload.h b/libs/libvm_payload/include/vm_payload.h
new file mode 100644
index 0000000..5e15607
--- /dev/null
+++ b/libs/libvm_payload/include/vm_payload.h
@@ -0,0 +1,263 @@
+/*
+ * Copyright (C) 2022 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <sys/cdefs.h>
+
+#include "vm_main.h"
+
+__BEGIN_DECLS
+
+typedef struct AIBinder AIBinder;
+
+/**
+ * Introduced in API 35.
+ * Remote attestation result if the attestation succeeds.
+ */
+typedef struct AVmAttestationResult AVmAttestationResult;
+
+/**
+ * Introduced in API 35.
+ * Remote attestation status types returned from remote attestation functions.
+ */
+typedef enum AVmAttestationStatus : int32_t {
+ /** The remote attestation completes successfully. */
+ ATTESTATION_OK = 0,
+
+ /** The challenge size is not between 0 and 64. */
+ ATTESTATION_ERROR_INVALID_CHALLENGE = -10001,
+
+ /** Failed to attest the VM. Please retry at a later time. */
+ ATTESTATION_ERROR_ATTESTATION_FAILED = -10002,
+
+ /** Remote attestation is not supported in the current environment. */
+ ATTESTATION_ERROR_UNSUPPORTED = -10003,
+} AVmAttestationStatus;
+
+/**
+ * Notifies the host that the payload is ready.
+ *
+ * If the host app has set a `VirtualMachineCallback` for the VM, its
+ * `onPayloadReady` method will be called.
+ *
+ * Note that subsequent calls to this function after the first have no effect;
+ * `onPayloadReady` is never called more than once.
+ */
+void AVmPayload_notifyPayloadReady(void);
+
+/**
+ * Runs a binder RPC server, serving the supplied binder service implementation on the given vsock
+ * port.
+ *
+ * If and when the server is ready for connections (it is listening on the port), `on_ready` is
+ * called to allow appropriate action to be taken - e.g. to notify clients that they may now
+ * attempt to connect with `AVmPayload_notifyPayloadReady`.
+ *
+ * Note that this function does not return. The calling thread joins the binder
+ * thread pool to handle incoming messages.
+ *
+ * \param service the service to bind to the given port.
+ * \param port vsock port.
+ * \param on_ready the callback to execute once the server is ready for connections. If not null the
+ * callback will be called at most once.
+ * \param param parameter to be passed to the `on_ready` callback.
+ */
+__attribute__((noreturn)) void AVmPayload_runVsockRpcServer(
+ AIBinder* _Nonnull service, uint32_t port,
+ void (*_Nullable on_ready)(void* _Nullable param), void* _Nullable param);
+
+/**
+ * Returns all or part of a 32-byte secret that is bound to this unique VM
+ * instance and the supplied identifier. The secret can be used e.g. as an
+ * encryption key.
+ *
+ * Every VM has a secret that is derived from a device-specific value known to
+ * the hypervisor, the code that runs in the VM and its non-modifiable
+ * configuration; it is not made available to the host OS.
+ *
+ * This function performs a further derivation from the VM secret and the
+ * supplied identifier. As long as the VM identity doesn't change the same value
+ * will be returned for the same identifier, even if the VM is stopped &
+ * restarted or the device rebooted.
+ *
+ * If multiple secrets are required for different purposes, a different
+ * identifier should be used for each. The identifiers otherwise are arbitrary
+ * byte sequences and do not need to be kept secret; typically they are
+ * hardcoded in the calling code.
+ *
+ * \param identifier identifier of the secret to return.
+ * \param identifier_size size of the secret identifier.
+ * \param secret pointer to size bytes where the secret is written.
+ * \param size number of bytes of the secret to get, <= 32.
+ */
+void AVmPayload_getVmInstanceSecret(const void* _Nonnull identifier, size_t identifier_size,
+ void* _Nonnull secret, size_t size);
+
+/**
+ * Gets the path to the APK contents. It is a directory, under which are
+ * the unzipped contents of the APK containing the payload, all read-only
+ * but accessible to the payload.
+ *
+ * \return the path to the APK contents. The returned string should not be
+ * deleted or freed by the application. The string remains valid for the
+ * lifetime of the VM.
+ */
+const char* _Nonnull AVmPayload_getApkContentsPath(void);
+
+/**
+ * Gets the path to the encrypted persistent storage for the VM, if any. This is
+ * a directory under which any files or directories created will be stored on
+ * behalf of the VM by the host app. All data is encrypted using a key known
+ * only to the VM, so the host cannot decrypt it, but may delete it.
+ *
+ * \return the path to the encrypted storage directory, or NULL if no encrypted
+ * storage was requested in the VM configuration. If non-null the returned
+ * string should not be deleted or freed by the application and remains valid
+ * for the lifetime of the VM.
+ */
+const char* _Nullable AVmPayload_getEncryptedStoragePath(void);
+
+/**
+ * Requests the remote attestation of the client VM.
+ *
+ * The challenge will be included in the certificate chain in the attestation result,
+ * serving as proof of the freshness of the result.
+ *
+ * \param challenge A pointer to the challenge buffer.
+ * \param challenge_size size of the challenge. The maximum supported challenge size is
+ * 64 bytes. The status ATTESTATION_ERROR_INVALID_CHALLENGE will be returned if
+ * an invalid challenge is passed.
+ * \param result The remote attestation result will be filled here if the attestation
+ * succeeds. The result remains valid until it is freed with
+ * `AVmPayload_freeAttestationResult`.
+ *
+ * \return ATTESTATION_OK upon successful attestation.
+ */
+AVmAttestationStatus AVmPayload_requestAttestation(const void* _Nonnull challenge,
+ size_t challenge_size,
+ AVmAttestationResult* _Nullable* _Nonnull result)
+ __INTRODUCED_IN(__ANDROID_API_V__);
+
+/**
+ * Converts the return value from `AVmPayload_requestAttestation` to a text string
+ * representing the status code.
+ *
+ * \return a constant string value representing the status code. The string should not
+ * be deleted or freed by the application and remains valid for the lifetime of the VM.
+ */
+const char* _Nonnull AVmAttestationStatus_toString(AVmAttestationStatus status)
+ __INTRODUCED_IN(__ANDROID_API_V__);
+
+/**
+ * Frees all the data owned by the provided attestation result, including the result itself.
+ *
+ * Callers should ensure to invoke this API only once on a valid attestation result
+ * returned by `AVmPayload_requestAttestation` to avoid undefined behavior.
+ *
+ * \param result A pointer to the attestation result.
+ */
+void AVmAttestationResult_free(AVmAttestationResult* _Nullable result)
+ __INTRODUCED_IN(__ANDROID_API_V__);
+
+/**
+ * Reads the DER-encoded ECPrivateKey structure specified in [RFC 5915 s3] for the
+ * EC P-256 private key from the provided attestation result.
+ *
+ * \param result A pointer to the attestation result filled in
+ * `AVmPayload_requestAttestation` when the attestation succeeds.
+ * \param data A pointer to the memory where the private key will be written
+ * (can be null if size is 0).
+ * \param size The maximum number of bytes that can be written to the data buffer.
+ * If `size` is smaller than the total size of the private key, the key data will be
+ * truncated to this `size`.
+ *
+ * \return The total size of the private key.
+ *
+ * [RFC 5915 s3]: https://datatracker.ietf.org/doc/html/rfc5915#section-3
+ */
+size_t AVmAttestationResult_getPrivateKey(const AVmAttestationResult* _Nonnull result,
+ void* _Nullable data, size_t size)
+ __INTRODUCED_IN(__ANDROID_API_V__);
+
+/**
+ * Signs the given message using ECDSA P-256, the message is first hashed with SHA-256 and
+ * then it is signed with the attested EC P-256 private key in the attestation result.
+ *
+ * \param result A pointer to the attestation result filled in
+ * `AVmPayload_requestAttestation` when the attestation succeeds.
+ * \param message A pointer to the message buffer.
+ * \param message_size size of the message.
+ * \param data A pointer to the memory where the signature will be written
+ * (can be null if size is 0). The signature is a DER-encoded ECDSASignature structure
+ * detailed in the [RFC 6979].
+ * \param size The maximum number of bytes that can be written to the data buffer.
+ * If `size` is smaller than the total size of the signature, the signature will be
+ * truncated to this `size`.
+ *
+ * \return The size of the signature, or the size needed if the supplied buffer is too small.
+ *
+ * [RFC 6979]: https://datatracker.ietf.org/doc/html/rfc6979
+ */
+size_t AVmAttestationResult_sign(const AVmAttestationResult* _Nonnull result,
+ const void* _Nonnull message, size_t message_size,
+ void* _Nullable data, size_t size)
+ __INTRODUCED_IN(__ANDROID_API_V__);
+
+/**
+ * Gets the number of certificates in the certificate chain.
+ *
+ * The certificate chain consists of a sequence of DER-encoded X.509 certificates that form
+ * the attestation key's certificate chain. It starts with a leaf certificate covering the attested
+ * public key and ends with a root certificate.
+ *
+ * \param result A pointer to the attestation result obtained from `AVmPayload_requestAttestation`
+ * when the attestation succeeds.
+ *
+ * \return The number of certificates in the certificate chain.
+ */
+size_t AVmAttestationResult_getCertificateCount(const AVmAttestationResult* _Nonnull result)
+ __INTRODUCED_IN(__ANDROID_API_V__);
+
+/**
+ * Retrieves the certificate at the given `index` from the certificate chain in the provided
+ * attestation result.
+ *
+ * The certificate chain consists of a sequence of DER-encoded X.509 certificates that form
+ * the attestation key's certificate chain. It starts with a leaf certificate covering the attested
+ * public key and ends with a root certificate.
+ *
+ * \param result A pointer to the attestation result obtained from `AVmPayload_requestAttestation`
+ * when the attestation succeeds.
+ * \param index Index of the certificate to retrieve. The `index` must be within the range of
+ * [0, number of certificates). The number of certificates can be obtained with
+ * `AVmAttestationResult_getCertificateCount`.
+ * \param data A pointer to the memory where the certificate will be written
+ * (can be null if size is 0).
+ * \param size The maximum number of bytes that can be written to the data buffer. If `size`
+ * is smaller than the total size of the certificate, the certificate will be
+ * truncated to this `size`.
+ *
+ * \return The total size of the certificate at the given `index`.
+ */
+size_t AVmAttestationResult_getCertificateAt(const AVmAttestationResult* _Nonnull result,
+ size_t index, void* _Nullable data, size_t size)
+ __INTRODUCED_IN(__ANDROID_API_V__);
+
+__END_DECLS
diff --git a/libs/libvm_payload/libvm_payload.map.txt b/libs/libvm_payload/libvm_payload.map.txt
new file mode 100644
index 0000000..3daad00
--- /dev/null
+++ b/libs/libvm_payload/libvm_payload.map.txt
@@ -0,0 +1,20 @@
+LIBVM_PAYLOAD {
+ global:
+ AVmPayload_notifyPayloadReady; # systemapi introduced=UpsideDownCake
+ AVmPayload_runVsockRpcServer; # systemapi introduced=UpsideDownCake
+ AVmPayload_getVmInstanceSecret; # systemapi introduced=UpsideDownCake
+ AVmPayload_getDiceAttestationChain; # systemapi introduced=UpsideDownCake
+ AVmPayload_getDiceAttestationCdi; # systemapi introduced=UpsideDownCake
+ AVmPayload_getApkContentsPath; # systemapi introduced=UpsideDownCake
+ AVmPayload_getEncryptedStoragePath; # systemapi introduced=UpsideDownCake
+ AVmPayload_requestAttestation; # systemapi introduced=VanillaIceCream
+ AVmPayload_requestAttestationForTesting; # systemapi introduced=VanillaIceCream
+ AVmAttestationResult_getPrivateKey; # systemapi introduced=VanillaIceCream
+ AVmAttestationResult_sign; # systemapi introduced=VanillaIceCream
+ AVmAttestationResult_free; # systemapi introduced=VanillaIceCream
+ AVmAttestationStatus_toString; # systemapi introduced=VanillaIceCream
+ AVmAttestationResult_getCertificateCount; # systemapi introduced=VanillaIceCream
+ AVmAttestationResult_getCertificateAt; # systemapi introduced=VanillaIceCream
+ local:
+ *;
+};
diff --git a/libs/libvm_payload/src/lib.rs b/libs/libvm_payload/src/lib.rs
new file mode 100644
index 0000000..5cc4431
--- /dev/null
+++ b/libs/libvm_payload/src/lib.rs
@@ -0,0 +1,570 @@
+// Copyright 2022, The Android Open Source Project
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! This module handles the interaction with virtual machine payload service.
+
+use android_system_virtualization_payload::aidl::android::system::virtualization::payload:: IVmPayloadService::{
+ IVmPayloadService, ENCRYPTEDSTORE_MOUNTPOINT, VM_APK_CONTENTS_PATH,
+ VM_PAYLOAD_SERVICE_SOCKET_NAME, AttestationResult::AttestationResult,
+};
+use anyhow::{bail, ensure, Context, Result};
+use binder::{
+ unstable_api::{new_spibinder, AIBinder},
+ Strong, ExceptionCode,
+};
+use lazy_static::lazy_static;
+use log::{error, info, LevelFilter};
+use rpcbinder::{RpcServer, RpcSession};
+use openssl::{ec::EcKey, sha::sha256, ecdsa::EcdsaSig};
+use std::convert::Infallible;
+use std::ffi::{CString, CStr};
+use std::fmt::Debug;
+use std::os::raw::{c_char, c_void};
+use std::path::Path;
+use std::ptr::{self, NonNull};
+use std::sync::{
+ atomic::{AtomicBool, Ordering},
+ Mutex,
+};
+use vm_payload_status_bindgen::AVmAttestationStatus;
+
+/// Maximum size of an ECDSA signature for EC P-256 key is 72 bytes.
+const MAX_ECDSA_P256_SIGNATURE_SIZE: usize = 72;
+
+lazy_static! {
+ static ref VM_APK_CONTENTS_PATH_C: CString =
+ CString::new(VM_APK_CONTENTS_PATH).expect("CString::new failed");
+ static ref PAYLOAD_CONNECTION: Mutex<Option<Strong<dyn IVmPayloadService>>> = Mutex::default();
+ static ref VM_ENCRYPTED_STORAGE_PATH_C: CString =
+ CString::new(ENCRYPTEDSTORE_MOUNTPOINT).expect("CString::new failed");
+}
+
+static ALREADY_NOTIFIED: AtomicBool = AtomicBool::new(false);
+
+/// Return a connection to the payload service in Microdroid Manager. Uses the existing connection
+/// if there is one, otherwise attempts to create a new one.
+fn get_vm_payload_service() -> Result<Strong<dyn IVmPayloadService>> {
+ let mut connection = PAYLOAD_CONNECTION.lock().unwrap();
+ if let Some(strong) = &*connection {
+ Ok(strong.clone())
+ } else {
+ let new_connection: Strong<dyn IVmPayloadService> = RpcSession::new()
+ .setup_unix_domain_client(VM_PAYLOAD_SERVICE_SOCKET_NAME)
+ .context(format!("Failed to connect to service: {}", VM_PAYLOAD_SERVICE_SOCKET_NAME))?;
+ *connection = Some(new_connection.clone());
+ Ok(new_connection)
+ }
+}
+
+/// Make sure our logging goes to logcat. It is harmless to call this more than once.
+fn initialize_logging() {
+ android_logger::init_once(
+ android_logger::Config::default().with_tag("vm_payload").with_max_level(LevelFilter::Info),
+ );
+}
+
+/// In many cases clients can't do anything useful if API calls fail, and the failure
+/// generally indicates that the VM is exiting or otherwise doomed. So rather than
+/// returning a non-actionable error indication we just log the problem and abort
+/// the process.
+fn unwrap_or_abort<T, E: Debug>(result: Result<T, E>) -> T {
+ result.unwrap_or_else(|e| {
+ let msg = format!("{:?}", e);
+ error!("{msg}");
+ panic!("{msg}")
+ })
+}
+
+/// Notifies the host that the payload is ready.
+/// Panics on failure.
+#[no_mangle]
+pub extern "C" fn AVmPayload_notifyPayloadReady() {
+ initialize_logging();
+
+ if !ALREADY_NOTIFIED.swap(true, Ordering::Relaxed) {
+ unwrap_or_abort(try_notify_payload_ready());
+
+ info!("Notified host payload ready successfully");
+ }
+}
+
+/// Notifies the host that the payload is ready.
+/// Returns a `Result` containing error information if failed.
+fn try_notify_payload_ready() -> Result<()> {
+ get_vm_payload_service()?.notifyPayloadReady().context("Cannot notify payload ready")
+}
+
+/// Runs a binder RPC server, serving the supplied binder service implementation on the given vsock
+/// port.
+///
+/// If and when the server is ready for connections (it is listening on the port), `on_ready` is
+/// called to allow appropriate action to be taken - e.g. to notify clients that they may now
+/// attempt to connect.
+///
+/// The current thread joins the binder thread pool to handle incoming messages.
+/// This function never returns.
+///
+/// Panics on error (including unexpected server exit).
+///
+/// # Safety
+///
+/// If present, the `on_ready` callback must be a valid function pointer, which will be called at
+/// most once, while this function is executing, with the `param` parameter.
+#[no_mangle]
+pub unsafe extern "C" fn AVmPayload_runVsockRpcServer(
+ service: *mut AIBinder,
+ port: u32,
+ on_ready: Option<unsafe extern "C" fn(param: *mut c_void)>,
+ param: *mut c_void,
+) -> Infallible {
+ initialize_logging();
+
+ // SAFETY: try_run_vsock_server has the same requirements as this function
+ unwrap_or_abort(unsafe { try_run_vsock_server(service, port, on_ready, param) })
+}
+
+/// # Safety: Same as `AVmPayload_runVsockRpcServer`.
+unsafe fn try_run_vsock_server(
+ service: *mut AIBinder,
+ port: u32,
+ on_ready: Option<unsafe extern "C" fn(param: *mut c_void)>,
+ param: *mut c_void,
+) -> Result<Infallible> {
+ // SAFETY: AIBinder returned has correct reference count, and the ownership can
+ // safely be taken by new_spibinder.
+ let service = unsafe { new_spibinder(service) };
+ if let Some(service) = service {
+ match RpcServer::new_vsock(service, libc::VMADDR_CID_HOST, port) {
+ Ok(server) => {
+ if let Some(on_ready) = on_ready {
+ // SAFETY: We're calling the callback with the parameter specified within the
+ // allowed lifetime.
+ unsafe { on_ready(param) };
+ }
+ server.join();
+ bail!("RpcServer unexpectedly terminated");
+ }
+ Err(err) => {
+ bail!("Failed to start RpcServer: {:?}", err);
+ }
+ }
+ } else {
+ bail!("Failed to convert the given service from AIBinder to SpIBinder.");
+ }
+}
+
+/// Get a secret that is uniquely bound to this VM instance.
+/// Panics on failure.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `identifier` must be [valid] for reads of `identifier_size` bytes.
+/// * `secret` must be [valid] for writes of `size` bytes.
+///
+/// [valid]: ptr#safety
+#[no_mangle]
+pub unsafe extern "C" fn AVmPayload_getVmInstanceSecret(
+ identifier: *const u8,
+ identifier_size: usize,
+ secret: *mut u8,
+ size: usize,
+) {
+ initialize_logging();
+
+ // SAFETY: See the requirements on `identifier` above.
+ let identifier = unsafe { std::slice::from_raw_parts(identifier, identifier_size) };
+ let vm_secret = unwrap_or_abort(try_get_vm_instance_secret(identifier, size));
+
+ // SAFETY: See the requirements on `secret` above; `vm_secret` is known to have length `size`,
+ // and cannot overlap `secret` because we just allocated it.
+ unsafe {
+ ptr::copy_nonoverlapping(vm_secret.as_ptr(), secret, size);
+ }
+}
+
+fn try_get_vm_instance_secret(identifier: &[u8], size: usize) -> Result<Vec<u8>> {
+ let vm_secret = get_vm_payload_service()?
+ .getVmInstanceSecret(identifier, i32::try_from(size)?)
+ .context("Cannot get VM instance secret")?;
+ ensure!(
+ vm_secret.len() == size,
+ "Returned secret has {} bytes, expected {}",
+ vm_secret.len(),
+ size
+ );
+ Ok(vm_secret)
+}
+
+/// Get the VM's attestation chain.
+/// Panics on failure.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `data` must be [valid] for writes of `size` bytes, if size > 0.
+///
+/// [valid]: ptr#safety
+#[no_mangle]
+pub unsafe extern "C" fn AVmPayload_getDiceAttestationChain(data: *mut u8, size: usize) -> usize {
+ initialize_logging();
+
+ let chain = unwrap_or_abort(try_get_dice_attestation_chain());
+ if size != 0 {
+ // SAFETY: See the requirements on `data` above. The number of bytes copied doesn't exceed
+ // the length of either buffer, and `chain` cannot overlap `data` because we just allocated
+ // it. We allow data to be null, which is never valid, but only if size == 0 which is
+ // checked above.
+ unsafe { ptr::copy_nonoverlapping(chain.as_ptr(), data, std::cmp::min(chain.len(), size)) };
+ }
+ chain.len()
+}
+
+fn try_get_dice_attestation_chain() -> Result<Vec<u8>> {
+ get_vm_payload_service()?.getDiceAttestationChain().context("Cannot get attestation chain")
+}
+
+/// Get the VM's attestation CDI.
+/// Panics on failure.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `data` must be [valid] for writes of `size` bytes, if size > 0.
+///
+/// [valid]: ptr#safety
+#[no_mangle]
+pub unsafe extern "C" fn AVmPayload_getDiceAttestationCdi(data: *mut u8, size: usize) -> usize {
+ initialize_logging();
+
+ let cdi = unwrap_or_abort(try_get_dice_attestation_cdi());
+ if size != 0 {
+ // SAFETY: See the requirements on `data` above. The number of bytes copied doesn't exceed
+ // the length of either buffer, and `cdi` cannot overlap `data` because we just allocated
+ // it. We allow data to be null, which is never valid, but only if size == 0 which is
+ // checked above.
+ unsafe { ptr::copy_nonoverlapping(cdi.as_ptr(), data, std::cmp::min(cdi.len(), size)) };
+ }
+ cdi.len()
+}
+
+fn try_get_dice_attestation_cdi() -> Result<Vec<u8>> {
+ get_vm_payload_service()?.getDiceAttestationCdi().context("Cannot get attestation CDI")
+}
+
+/// Requests the remote attestation of the client VM.
+///
+/// The challenge will be included in the certificate chain in the attestation result,
+/// serving as proof of the freshness of the result.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `challenge` must be [valid] for reads of `challenge_size` bytes.
+///
+/// [valid]: ptr#safety
+#[no_mangle]
+pub unsafe extern "C" fn AVmPayload_requestAttestation(
+ challenge: *const u8,
+ challenge_size: usize,
+ res: &mut *mut AttestationResult,
+) -> AVmAttestationStatus {
+ // SAFETY: The caller guarantees that `challenge` is valid for reads and `res` is valid
+ // for writes.
+ unsafe {
+ request_attestation(
+ challenge,
+ challenge_size,
+ false, // test_mode
+ res,
+ )
+ }
+}
+
+/// Requests the remote attestation of the client VM for testing.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `challenge` must be [valid] for reads of `challenge_size` bytes.
+///
+/// [valid]: ptr#safety
+#[no_mangle]
+pub unsafe extern "C" fn AVmPayload_requestAttestationForTesting(
+ challenge: *const u8,
+ challenge_size: usize,
+ res: &mut *mut AttestationResult,
+) -> AVmAttestationStatus {
+ // SAFETY: The caller guarantees that `challenge` is valid for reads and `res` is valid
+ // for writes.
+ unsafe {
+ request_attestation(
+ challenge,
+ challenge_size,
+ true, // test_mode
+ res,
+ )
+ }
+}
+
+/// Requests the remote attestation of the client VM.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `challenge` must be [valid] for reads of `challenge_size` bytes.
+///
+/// [valid]: ptr#safety
+unsafe fn request_attestation(
+ challenge: *const u8,
+ challenge_size: usize,
+ test_mode: bool,
+ res: &mut *mut AttestationResult,
+) -> AVmAttestationStatus {
+ initialize_logging();
+ const MAX_CHALLENGE_SIZE: usize = 64;
+ if challenge_size > MAX_CHALLENGE_SIZE {
+ return AVmAttestationStatus::ATTESTATION_ERROR_INVALID_CHALLENGE;
+ }
+ let challenge = if challenge_size == 0 {
+ &[]
+ } else {
+ // SAFETY: The caller guarantees that `challenge` is valid for reads of
+ // `challenge_size` bytes and `challenge_size` is not zero.
+ unsafe { std::slice::from_raw_parts(challenge, challenge_size) }
+ };
+ let service = unwrap_or_abort(get_vm_payload_service());
+ match service.requestAttestation(challenge, test_mode) {
+ Ok(attestation_res) => {
+ *res = Box::into_raw(Box::new(attestation_res));
+ AVmAttestationStatus::ATTESTATION_OK
+ }
+ Err(e) => {
+ error!("Remote attestation failed: {e:?}");
+ binder_status_to_attestation_status(e)
+ }
+ }
+}
+
+fn binder_status_to_attestation_status(status: binder::Status) -> AVmAttestationStatus {
+ match status.exception_code() {
+ ExceptionCode::UNSUPPORTED_OPERATION => AVmAttestationStatus::ATTESTATION_ERROR_UNSUPPORTED,
+ _ => AVmAttestationStatus::ATTESTATION_ERROR_ATTESTATION_FAILED,
+ }
+}
+
+/// Converts the return value from `AVmPayload_requestAttestation` to a text string
+/// representing the error code.
+#[no_mangle]
+pub extern "C" fn AVmAttestationStatus_toString(status: AVmAttestationStatus) -> *const c_char {
+ let message = match status {
+ AVmAttestationStatus::ATTESTATION_OK => {
+ CStr::from_bytes_with_nul(b"The remote attestation completes successfully.\0").unwrap()
+ }
+ AVmAttestationStatus::ATTESTATION_ERROR_INVALID_CHALLENGE => {
+ CStr::from_bytes_with_nul(b"The challenge size is not between 0 and 64.\0").unwrap()
+ }
+ AVmAttestationStatus::ATTESTATION_ERROR_ATTESTATION_FAILED => {
+ CStr::from_bytes_with_nul(b"Failed to attest the VM. Please retry at a later time.\0")
+ .unwrap()
+ }
+ AVmAttestationStatus::ATTESTATION_ERROR_UNSUPPORTED => CStr::from_bytes_with_nul(
+ b"Remote attestation is not supported in the current environment.\0",
+ )
+ .unwrap(),
+ };
+ message.as_ptr()
+}
+
+/// Reads the DER-encoded ECPrivateKey structure specified in [RFC 5915 s3] for the
+/// EC P-256 private key from the provided attestation result.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `data` must be [valid] for writes of `size` bytes, if size > 0.
+/// * The region of memory beginning at `data` with `size` bytes must not overlap with the
+/// region of memory `res` points to.
+///
+/// [valid]: ptr#safety
+/// [RFC 5915 s3]: https://datatracker.ietf.org/doc/html/rfc5915#section-3
+#[no_mangle]
+pub unsafe extern "C" fn AVmAttestationResult_getPrivateKey(
+ res: &AttestationResult,
+ data: *mut u8,
+ size: usize,
+) -> usize {
+ let private_key = &res.privateKey;
+ if size != 0 {
+ let data = NonNull::new(data).expect("data must not be null when size > 0");
+ // SAFETY: See the requirements on `data` above. The number of bytes copied doesn't exceed
+ // the length of either buffer, and the caller ensures that `private_key` cannot overlap
+ // `data`. We allow data to be null, which is never valid, but only if size == 0
+ // which is checked above.
+ unsafe {
+ ptr::copy_nonoverlapping(
+ private_key.as_ptr(),
+ data.as_ptr(),
+ std::cmp::min(private_key.len(), size),
+ )
+ };
+ }
+ private_key.len()
+}
+
+/// Signs the given message using ECDSA P-256, the message is first hashed with SHA-256 and
+/// then it is signed with the attested EC P-256 private key in the attestation result.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `message` must be [valid] for reads of `message_size` bytes.
+/// * `data` must be [valid] for writes of `size` bytes, if size > 0.
+/// * The region of memory beginning at `data` with `size` bytes must not overlap with the
+/// region of memory `res` or `message` point to.
+///
+///
+/// [valid]: ptr#safety
+#[no_mangle]
+pub unsafe extern "C" fn AVmAttestationResult_sign(
+ res: &AttestationResult,
+ message: *const u8,
+ message_size: usize,
+ data: *mut u8,
+ size: usize,
+) -> usize {
+ // A DER-encoded ECDSA signature can have varying sizes even with the same EC Key and message,
+ // due to the encoding of the random values r and s that are part of the signature.
+ if size == 0 {
+ return MAX_ECDSA_P256_SIGNATURE_SIZE;
+ }
+ if message_size == 0 {
+ panic!("Message to be signed must not be empty.")
+ }
+ // SAFETY: See the requirements on `message` above.
+ let message = unsafe { std::slice::from_raw_parts(message, message_size) };
+ let signature = unwrap_or_abort(try_ecdsa_sign(message, &res.privateKey));
+ let data = NonNull::new(data).expect("data must not be null when size > 0");
+ // SAFETY: See the requirements on `data` above. The number of bytes copied doesn't exceed
+ // the length of either buffer, and the caller ensures that `signature` cannot overlap
+ // `data`. We allow data to be null, which is never valid, but only if size == 0
+ // which is checked above.
+ unsafe {
+ ptr::copy_nonoverlapping(
+ signature.as_ptr(),
+ data.as_ptr(),
+ usize::min(signature.len(), size),
+ )
+ };
+ if size < signature.len() {
+ // If the buffer is too small, return the maximum size of the signature to allow the caller
+ // to allocate a buffer large enough to call this function again.
+ MAX_ECDSA_P256_SIGNATURE_SIZE
+ } else {
+ signature.len()
+ }
+}
+
+fn try_ecdsa_sign(message: &[u8], der_encoded_ec_private_key: &[u8]) -> Result<Vec<u8>> {
+ let private_key = EcKey::private_key_from_der(der_encoded_ec_private_key)?;
+ let digest = sha256(message);
+ let sig = EcdsaSig::sign(&digest, &private_key)?;
+ Ok(sig.to_der()?)
+}
+
+/// Gets the number of certificates in the certificate chain.
+#[no_mangle]
+pub extern "C" fn AVmAttestationResult_getCertificateCount(res: &AttestationResult) -> usize {
+ res.certificateChain.len()
+}
+
+/// Retrieves the certificate at the given `index` from the certificate chain in the provided
+/// attestation result.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `data` must be [valid] for writes of `size` bytes, if size > 0.
+/// * `index` must be within the range of [0, number of certificates). The number of certificates
+/// can be obtained with `AVmAttestationResult_getCertificateCount`.
+/// * The region of memory beginning at `data` with `size` bytes must not overlap with the
+/// region of memory `res` points to.
+///
+/// [valid]: ptr#safety
+#[no_mangle]
+pub unsafe extern "C" fn AVmAttestationResult_getCertificateAt(
+ res: &AttestationResult,
+ index: usize,
+ data: *mut u8,
+ size: usize,
+) -> usize {
+ let certificate =
+ &res.certificateChain.get(index).expect("The index is out of bounds.").encodedCertificate;
+ if size != 0 {
+ let data = NonNull::new(data).expect("data must not be null when size > 0");
+ // SAFETY: See the requirements on `data` above. The number of bytes copied doesn't exceed
+ // the length of either buffer, and the caller ensures that `certificate` cannot overlap
+ // `data`. We allow data to be null, which is never valid, but only if size == 0
+ // which is checked above.
+ unsafe {
+ ptr::copy_nonoverlapping(
+ certificate.as_ptr(),
+ data.as_ptr(),
+ std::cmp::min(certificate.len(), size),
+ )
+ };
+ }
+ certificate.len()
+}
+
+/// Frees all the data owned by given attestation result and result itself.
+///
+/// # Safety
+///
+/// Behavior is undefined if any of the following conditions are violated:
+///
+/// * `res` must point to a valid `AttestationResult` and has not been freed before.
+#[no_mangle]
+pub unsafe extern "C" fn AVmAttestationResult_free(res: *mut AttestationResult) {
+ if !res.is_null() {
+ // SAFETY: The result is only freed once is ensured by the caller.
+ let res = unsafe { Box::from_raw(res) };
+ drop(res)
+ }
+}
+
+/// Gets the path to the APK contents.
+#[no_mangle]
+pub extern "C" fn AVmPayload_getApkContentsPath() -> *const c_char {
+ VM_APK_CONTENTS_PATH_C.as_ptr()
+}
+
+/// Gets the path to the VM's encrypted storage.
+#[no_mangle]
+pub extern "C" fn AVmPayload_getEncryptedStoragePath() -> *const c_char {
+ if Path::new(ENCRYPTEDSTORE_MOUNTPOINT).exists() {
+ VM_ENCRYPTED_STORAGE_PATH_C.as_ptr()
+ } else {
+ ptr::null()
+ }
+}
diff --git a/libs/libvm_payload/stub/readme.txt b/libs/libvm_payload/stub/readme.txt
new file mode 100644
index 0000000..15b8743
--- /dev/null
+++ b/libs/libvm_payload/stub/readme.txt
@@ -0,0 +1,17 @@
+The stub.c file here is a checked-in version of a generated code file.
+
+It is not needed when building a payload client in the Android build
+system. The build system will automatically generated it (from
+libvm_payload.map.txt) and then compile it to form the stub version of
+libvm_payload.so. Clients link against the stub, but at runtime they
+will use the real libvm_payload.so provided by Microdroid.
+
+This file is here to support non-Android build systems, to allow a
+suitable stub libvm_payload.so to be built.
+
+To update this file, something like the following should work:
+
+lunch aosp_arm64-eng
+m MicrodroidTestNativeLib
+
+The generated stub file can then be found at out/soong/.intermediates/packages/modules/Virtualization/libs/libvm_payload/libvm_payload/android_arm64_armv8-a_shared_current/gen/stub.c
diff --git a/libs/libvm_payload/stub/stub.c b/libs/libvm_payload/stub/stub.c
new file mode 100644
index 0000000..ad7f8b0
--- /dev/null
+++ b/libs/libvm_payload/stub/stub.c
@@ -0,0 +1,15 @@
+void AVmPayload_notifyPayloadReady() {}
+void AVmPayload_runVsockRpcServer() {}
+void AVmPayload_getVmInstanceSecret() {}
+void AVmPayload_getDiceAttestationChain() {}
+void AVmPayload_getDiceAttestationCdi() {}
+void AVmPayload_getApkContentsPath() {}
+void AVmPayload_getEncryptedStoragePath() {}
+void AVmPayload_requestAttestation() {}
+void AVmPayload_requestAttestationForTesting() {}
+void AVmAttestationResult_getPrivateKey() {}
+void AVmAttestationResult_sign() {}
+void AVmAttestationResult_free() {}
+void AVmAttestationStatus_toString() {}
+void AVmAttestationResult_getCertificateCount() {}
+void AVmAttestationResult_getCertificateAt() {}
diff --git a/libs/libvm_payload/wrapper/attestation.rs b/libs/libvm_payload/wrapper/attestation.rs
new file mode 100644
index 0000000..e0055d5
--- /dev/null
+++ b/libs/libvm_payload/wrapper/attestation.rs
@@ -0,0 +1,288 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+use std::error::Error;
+use std::ffi::{c_void, CStr};
+use std::fmt::{self, Display};
+use std::iter::FusedIterator;
+use std::ptr::{self, NonNull};
+
+use vm_payload_bindgen::{
+ AVmAttestationResult, AVmAttestationResult_free, AVmAttestationResult_getCertificateAt,
+ AVmAttestationResult_getCertificateCount, AVmAttestationResult_getPrivateKey,
+ AVmAttestationResult_sign, AVmAttestationStatus, AVmAttestationStatus_toString,
+ AVmPayload_requestAttestation, AVmPayload_requestAttestationForTesting,
+};
+
+/// Holds the result of a successful Virtual Machine attestation request.
+/// See [`request_attestation`].
+#[derive(Debug)]
+pub struct AttestationResult {
+ result: NonNull<AVmAttestationResult>,
+}
+
+/// Error type that can be returned from an unsuccessful Virtual Machine attestation request.
+/// See [`request_attestation`].
+#[derive(Copy, Clone, Debug, Hash, PartialEq, Eq)]
+pub enum AttestationError {
+ /// The challenge size was not between 0 and 64 bytes (inclusive).
+ InvalidChallenge,
+ /// The attempt to attest the VM failed. A subsequent request may succeed.
+ AttestationFailed,
+ /// VM attestation is not supported in the current environment.
+ AttestationUnsupported,
+}
+
+impl Error for AttestationError {}
+
+impl Display for AttestationError {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
+ let status = match self {
+ Self::InvalidChallenge => AVmAttestationStatus::ATTESTATION_ERROR_INVALID_CHALLENGE,
+ Self::AttestationFailed => AVmAttestationStatus::ATTESTATION_ERROR_ATTESTATION_FAILED,
+ Self::AttestationUnsupported => AVmAttestationStatus::ATTESTATION_ERROR_UNSUPPORTED,
+ };
+ // SAFETY: AVmAttestationStatus_toString always returns a non-null pointer to a
+ // nul-terminated C string with static lifetime (which is valid UTF-8).
+ let c_str = unsafe { CStr::from_ptr(AVmAttestationStatus_toString(status)) };
+ let str = c_str.to_str().expect("Invalid UTF-8 for AVmAttestationStatus");
+ f.write_str(str)
+ }
+}
+
+impl Drop for AttestationResult {
+ fn drop(&mut self) {
+ let ptr = self.result.as_ptr();
+
+ // SAFETY: The `result` field is private, and only populated with a successful call to
+ // `AVmPayload_requestAttestation`, and not freed elsewhere.
+ unsafe { AVmAttestationResult_free(ptr) };
+ }
+}
+
+// SAFETY: The API functions that accept the `AVmAttestationResult` pointer are all safe to call
+// from any thread, including `AVmAttestationResult_free` which is called only on drop.
+unsafe impl Send for AttestationResult {}
+
+// SAFETY: There is no interior mutation here; any future functions that might mutate the data would
+// require a non-const pointer and hence need `&mut self` here. The only existing such function is
+// `AVmAttestationResult_free` where we take a mutable reference guaranteeing no other references
+// exist. The raw API functions are safe to call from any thread.
+unsafe impl Sync for AttestationResult {}
+
+/// Requests the remote attestation of this VM.
+///
+/// On success the supplied [`challenge`] will be included in the certificate chain accessible from
+/// the [`AttestationResult`]; this can be used as proof of the freshness of the attestation.
+///
+/// The challenge should be no more than 64 bytes long or the request will fail.
+pub fn request_attestation(challenge: &[u8]) -> Result<AttestationResult, AttestationError> {
+ let mut result: *mut AVmAttestationResult = ptr::null_mut();
+ // SAFETY: We only read the challenge within its bounds and the function does not retain any
+ // reference to it.
+ let status = unsafe {
+ AVmPayload_requestAttestation(
+ challenge.as_ptr() as *const c_void,
+ challenge.len(),
+ &mut result,
+ )
+ };
+ AttestationResult::new(status, result)
+}
+
+/// A variant of [`request_attestation`] used for testing purposes. This should not be used by
+/// normal VMs, and is not available to app owned VMs.
+pub fn request_attestation_for_testing(
+ challenge: &[u8],
+) -> Result<AttestationResult, AttestationError> {
+ let mut result: *mut AVmAttestationResult = ptr::null_mut();
+ // SAFETY: We only read the challenge within its bounds and the function does not retain any
+ // reference to it.
+ let status = unsafe {
+ AVmPayload_requestAttestationForTesting(
+ challenge.as_ptr() as *const c_void,
+ challenge.len(),
+ &mut result,
+ )
+ };
+ AttestationResult::new(status, result)
+}
+
+impl AttestationResult {
+ fn new(
+ status: AVmAttestationStatus,
+ result: *mut AVmAttestationResult,
+ ) -> Result<AttestationResult, AttestationError> {
+ match status {
+ AVmAttestationStatus::ATTESTATION_ERROR_INVALID_CHALLENGE => {
+ Err(AttestationError::InvalidChallenge)
+ }
+ AVmAttestationStatus::ATTESTATION_ERROR_ATTESTATION_FAILED => {
+ Err(AttestationError::AttestationFailed)
+ }
+ AVmAttestationStatus::ATTESTATION_ERROR_UNSUPPORTED => {
+ Err(AttestationError::AttestationUnsupported)
+ }
+ AVmAttestationStatus::ATTESTATION_OK => {
+ let result = NonNull::new(result)
+ .expect("Attestation succeeded but the attestation result is null");
+ Ok(AttestationResult { result })
+ }
+ }
+ }
+
+ fn as_const_ptr(&self) -> *const AVmAttestationResult {
+ self.result.as_ptr().cast_const()
+ }
+
+ /// Returns the attested private key. This is the ECDSA P-256 private key corresponding to the
+ /// public key described by the leaf certificate in the attested
+ /// [certificate chain](AttestationResult::certificate_chain). It is a DER-encoded
+ /// `ECPrivateKey` structure as specified in
+ /// [RFC 5915 s3](https://datatracker.ietf.org/doc/html/rfc5915#section-3).
+ ///
+ /// Note: The [`sign_message`](AttestationResult::sign_message) method allows signing with the
+ /// key without retrieving it.
+ pub fn private_key(&self) -> Vec<u8> {
+ let ptr = self.as_const_ptr();
+
+ let size =
+ // SAFETY: We own the `AVmAttestationResult` pointer, so it is valid. The function
+ // writes no data since we pass a zero size, and null is explicitly allowed for the
+ // destination in that case.
+ unsafe { AVmAttestationResult_getPrivateKey(ptr, ptr::null_mut(), 0) };
+
+ let mut private_key = vec![0u8; size];
+ // SAFETY: We own the `AVmAttestationResult` pointer, so it is valid. The function only
+ // writes within the bounds of `private_key`, which we just allocated so cannot be aliased.
+ let size = unsafe {
+ AVmAttestationResult_getPrivateKey(
+ ptr,
+ private_key.as_mut_ptr() as *mut c_void,
+ private_key.len(),
+ )
+ };
+ assert_eq!(size, private_key.len());
+ private_key
+ }
+
+ /// Signs the given message using the attested private key. The signature uses ECDSA P-256; the
+ /// message is first hashed with SHA-256 and then it is signed with the attested EC P-256
+ /// [private key](AttestationResult::private_key).
+ ///
+ /// The signature is a DER-encoded `ECDSASignature`` structure as described in
+ /// [RFC 6979](https://datatracker.ietf.org/doc/html/rfc6979).
+ pub fn sign_message(&self, message: &[u8]) -> Vec<u8> {
+ let ptr = self.as_const_ptr();
+
+ // SAFETY: We own the `AVmAttestationResult` pointer, so it is valid. The function
+ // writes no data since we pass a zero size, and null is explicitly allowed for the
+ // destination in that case.
+ let size = unsafe {
+ AVmAttestationResult_sign(
+ ptr,
+ message.as_ptr() as *const c_void,
+ message.len(),
+ ptr::null_mut(),
+ 0,
+ )
+ };
+
+ let mut signature = vec![0u8; size];
+ // SAFETY: We own the `AVmAttestationResult` pointer, so it is valid. The function only
+ // writes within the bounds of `signature`, which we just allocated so cannot be aliased.
+ let size = unsafe {
+ AVmAttestationResult_sign(
+ ptr,
+ message.as_ptr() as *const c_void,
+ message.len(),
+ signature.as_mut_ptr() as *mut c_void,
+ signature.len(),
+ )
+ };
+ assert!(size <= signature.len());
+ signature.truncate(size);
+ signature
+ }
+
+ /// Returns an iterator over the certificates forming the certificate chain for the VM, and its
+ /// public key, obtained by the attestation process.
+ ///
+ /// The certificate chain consists of a sequence of DER-encoded X.509 certificates that form
+ /// the attestation key's certificate chain. It starts with the leaf certificate covering the
+ /// attested public key and ends with the root certificate.
+ pub fn certificate_chain(&self) -> CertIterator {
+ // SAFETY: We own the `AVmAttestationResult` pointer, so it is valid.
+ let count = unsafe { AVmAttestationResult_getCertificateCount(self.as_const_ptr()) };
+
+ CertIterator { result: self, count, current: 0 }
+ }
+
+ fn certificate(&self, index: usize) -> Vec<u8> {
+ let ptr = self.as_const_ptr();
+
+ let size =
+ // SAFETY: We own the `AVmAttestationResult` pointer, so it is valid. The function
+ // writes no data since we pass a zero size, and null is explicitly allowed for the
+ // destination in that case. The function will panic if `index` is out of range (which
+ // is safe).
+ unsafe { AVmAttestationResult_getCertificateAt(ptr, index, ptr::null_mut(), 0) };
+
+ let mut cert = vec![0u8; size];
+ // SAFETY: We own the `AVmAttestationResult` pointer, so it is valid. The function only
+ // writes within the bounds of `cert`, which we just allocated so cannot be aliased.
+ let size = unsafe {
+ AVmAttestationResult_getCertificateAt(
+ ptr,
+ index,
+ cert.as_mut_ptr() as *mut c_void,
+ cert.len(),
+ )
+ };
+ assert_eq!(size, cert.len());
+ cert
+ }
+}
+
+/// An iterator over the DER-encoded X.509 certificates containin in an [`AttestationResult`].
+/// See [`certificate_chain`](AttestationResult::certificate_chain) for more details.
+pub struct CertIterator<'a> {
+ result: &'a AttestationResult,
+ count: usize,
+ current: usize, // Invariant: current <= count
+}
+
+impl<'a> Iterator for CertIterator<'a> {
+ type Item = Vec<u8>;
+
+ fn next(&mut self) -> Option<Self::Item> {
+ if self.current < self.count {
+ let cert = self.result.certificate(self.current);
+ self.current += 1;
+ Some(cert)
+ } else {
+ None
+ }
+ }
+
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ let size = self.count - self.current;
+ (size, Some(size))
+ }
+}
+
+impl<'a> ExactSizeIterator for CertIterator<'a> {}
+impl<'a> FusedIterator for CertIterator<'a> {}
diff --git a/libs/libvm_payload/wrapper/lib.rs b/libs/libvm_payload/wrapper/lib.rs
new file mode 100644
index 0000000..b9ce6c8
--- /dev/null
+++ b/libs/libvm_payload/wrapper/lib.rs
@@ -0,0 +1,196 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+//! Rust wrapper for the VM Payload API, allowing virtual machine payload code to be written in
+//! Rust. This wraps the raw C API, accessed via bindgen, into a more idiomatic Rust interface.
+//!
+//! See `https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/libs/libvm_payload/README.md`
+//! for more information on the VM Payload API.
+
+mod attestation;
+
+pub use attestation::{request_attestation, AttestationError, AttestationResult};
+use binder::unstable_api::AsNative;
+use binder::{FromIBinder, Strong};
+use std::ffi::{c_void, CStr, OsStr};
+use std::os::unix::ffi::OsStrExt;
+use std::path::Path;
+use std::ptr;
+use vm_payload_bindgen::{
+ AIBinder, AVmPayload_getApkContentsPath, AVmPayload_getEncryptedStoragePath,
+ AVmPayload_getVmInstanceSecret, AVmPayload_notifyPayloadReady, AVmPayload_runVsockRpcServer,
+};
+
+/// The functions declared here are restricted to VMs created with a config file;
+/// they will fail, or panic, if called in other VMs. The ability to create such VMs
+/// requires the android.permission.USE_CUSTOM_VIRTUAL_MACHINE permission, and is
+/// therefore not available to privileged or third party apps.
+///
+/// These functions can be used by tests, if the permission is granted via shell.
+pub mod restricted {
+ pub use crate::attestation::request_attestation_for_testing;
+}
+
+/// Marks the main function of the VM payload.
+///
+/// When the VM is run, this function is called. If it returns, the VM ends normally with a 0 exit
+/// code.
+///
+/// Example:
+///
+/// ```rust
+/// use log::info;
+///
+/// vm_payload::main!(vm_main);
+///
+/// fn vm_main() {
+/// android_logger::init_once(
+/// android_logger::Config::default()
+/// .with_tag("example_vm_payload")
+/// .with_max_level(log::LevelFilter::Info),
+/// );
+/// info!("Hello world");
+/// }
+/// ```
+#[macro_export]
+macro_rules! main {
+ ($name:path) => {
+ // Export a symbol with a name matching the extern declaration below.
+ #[export_name = "rust_main"]
+ fn __main() {
+ // Ensure that the main function provided by the application has the correct type.
+ $name()
+ }
+ };
+}
+
+// This is the real C entry point for the VM; we just forward to the Rust entry point.
+#[allow(non_snake_case)]
+#[no_mangle]
+extern "C" fn AVmPayload_main() {
+ extern "Rust" {
+ fn rust_main();
+ }
+
+ // SAFETY: rust_main is provided by the application using the `main!` macro above, which makes
+ // sure it has the right type.
+ unsafe { rust_main() }
+}
+
+/// Notifies the host that the payload is ready.
+///
+/// If the host app has set a `VirtualMachineCallback` for the VM, its
+/// `onPayloadReady` method will be called.
+///
+/// Note that subsequent calls to this function after the first have no effect;
+/// `onPayloadReady` is never called more than once.
+pub fn notify_payload_ready() {
+ // SAFETY: Invokes a method from the bindgen library `vm_payload_bindgen` which is safe to
+ // call at any time.
+ unsafe { AVmPayload_notifyPayloadReady() };
+}
+
+/// Runs a binder RPC server, serving the supplied binder service implementation on the given vsock
+/// port.
+///
+/// If and when the server is ready for connections (i.e. it is listening on the port),
+/// [`notify_payload_ready`] is called to notify the host that the server is ready. This is
+/// appropriate for VM payloads that serve a single binder service - which is common.
+///
+/// Note that this function does not return. The calling thread joins the binder
+/// thread pool to handle incoming messages.
+pub fn run_single_vsock_service<T>(service: Strong<T>, port: u32) -> !
+where
+ T: FromIBinder + ?Sized,
+{
+ extern "C" fn on_ready(_param: *mut c_void) {
+ notify_payload_ready();
+ }
+
+ let mut service = service.as_binder();
+ // The cast here is needed because the compiler doesn't know that our vm_payload_bindgen
+ // AIBinder is the same type as binder_ndk_sys::AIBinder.
+ let service = service.as_native_mut() as *mut AIBinder;
+ let param = ptr::null_mut();
+ // SAFETY: We have a strong reference to the service, so the raw pointer remains valid. It is
+ // safe for on_ready to be invoked at any time, with any parameter.
+ unsafe { AVmPayload_runVsockRpcServer(service, port, Some(on_ready), param) }
+}
+
+/// Gets the path to the contents of the APK containing the VM payload. It is a directory, under
+/// which are the unzipped contents of the APK containing the payload, all read-only
+/// but accessible to the payload.
+pub fn apk_contents_path() -> &'static Path {
+ // SAFETY: AVmPayload_getApkContentsPath always returns a non-null pointer to a
+ // nul-terminated C string with static lifetime.
+ let c_str = unsafe { CStr::from_ptr(AVmPayload_getApkContentsPath()) };
+ Path::new(OsStr::from_bytes(c_str.to_bytes()))
+}
+
+/// Gets the path to the encrypted persistent storage for the VM, if any. This is
+/// a directory under which any files or directories created will be stored on
+/// behalf of the VM by the host app. All data is encrypted using a key known
+/// only to the VM, so the host cannot decrypt it, but may delete it.
+///
+/// Returns `None` if no encrypted storage was requested in the VM configuration.
+pub fn encrypted_storage_path() -> Option<&'static Path> {
+ // SAFETY: AVmPayload_getEncryptedStoragePath returns either null or a pointer to a
+ // nul-terminated C string with static lifetime.
+ let ptr = unsafe { AVmPayload_getEncryptedStoragePath() };
+ if ptr.is_null() {
+ None
+ } else {
+ // SAFETY: We know the pointer is not null, and so it is a valid C string.
+ let c_str = unsafe { CStr::from_ptr(ptr) };
+ Some(Path::new(OsStr::from_bytes(c_str.to_bytes())))
+ }
+}
+
+/// Retrieves all or part of a 32-byte secret that is bound to this unique VM
+/// instance and the supplied identifier. The secret can be used e.g. as an
+/// encryption key.
+///
+/// Every VM has a secret that is derived from a device-specific value known to
+/// the hypervisor, the code that runs in the VM and its non-modifiable
+/// configuration; it is not made available to the host OS.
+///
+/// This function performs a further derivation from the VM secret and the
+/// supplied identifier. As long as the VM identity doesn't change the same value
+/// will be returned for the same identifier, even if the VM is stopped &
+/// restarted or the device rebooted.
+///
+/// If multiple secrets are required for different purposes, a different
+/// identifier should be used for each. The identifiers otherwise are arbitrary
+/// byte sequences and do not need to be kept secret; typically they are
+/// hardcoded in the calling code.
+///
+/// The secret is returned in [`secret`], truncated to its size, which must be between
+/// 1 and 32 bytes (inclusive) or the function will panic.
+pub fn get_vm_instance_secret(identifier: &[u8], secret: &mut [u8]) {
+ let secret_size = secret.len();
+ assert!((1..=32).contains(&secret_size), "VM instance secrets can be up to 32 bytes long");
+
+ // SAFETY: The function only reads from `[identifier]` within its bounds, and only writes to
+ // `[secret]` within its bounds. Neither reference is retained, and we know neither is null.
+ unsafe {
+ AVmPayload_getVmInstanceSecret(
+ identifier.as_ptr() as *const c_void,
+ identifier.len(),
+ secret.as_mut_ptr() as *mut c_void,
+ secret_size,
+ )
+ }
+}