blob: a1a2627946fa0ed6e0ecec1aac364654a9ea6059 [file] [log] [blame]
Alice Wangfb46ee12022-09-30 13:08:52 +00001/*
2 * Copyright (C) 2022 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#pragma once
18
Andrew Scull102067a2022-10-07 00:34:40 +000019#include <stdbool.h>
20#include <stddef.h>
Alan Stokes88805d52022-12-16 16:07:33 +000021#include <stdint.h>
Alan Stokesd4ea5a82022-11-10 12:17:42 +000022#include <sys/cdefs.h>
Andrew Scull102067a2022-10-07 00:34:40 +000023
Alan Stokes52d3c722022-10-04 17:27:13 +010024#include "vm_main.h"
25
Alan Stokesd4ea5a82022-11-10 12:17:42 +000026__BEGIN_DECLS
Alice Wangfb46ee12022-09-30 13:08:52 +000027
Alice Wang2be64f32022-10-13 14:37:35 +000028struct AIBinder;
29typedef struct AIBinder AIBinder;
30
Andrew Sculld64ae7d2022-10-05 17:41:43 +000031/**
32 * Notifies the host that the payload is ready.
Andrew Scull655e98e2022-10-10 22:24:58 +000033 *
Alan Stokes65bbb912022-11-23 09:39:34 +000034 * If the host app has set a `VirtualMachineCallback` for the VM, its
35 * `onPayloadReady` method will be called.
36 *
37 * Note that subsequent calls to this function after the first have no effect;
38 * `onPayloadReady` is never called more than once.
Andrew Sculld64ae7d2022-10-05 17:41:43 +000039 */
Alan Stokes65bbb912022-11-23 09:39:34 +000040void AVmPayload_notifyPayloadReady(void);
Alice Wangfb46ee12022-09-30 13:08:52 +000041
Andrew Sculld64ae7d2022-10-05 17:41:43 +000042/**
Alice Wang2be64f32022-10-13 14:37:35 +000043 * Runs a binder RPC server, serving the supplied binder service implementation on the given vsock
44 * port.
45 *
46 * If and when the server is ready for connections (it is listening on the port), `on_ready` is
47 * called to allow appropriate action to be taken - e.g. to notify clients that they may now
48 * attempt to connect with `AVmPayload_notifyPayloadReady`.
49 *
Alan Stokese0945ad2022-11-24 13:29:57 +000050 * Note that this function does not return. The calling thread joins the binder
51 * thread pool to handle incoming messages.
Alice Wang2be64f32022-10-13 14:37:35 +000052 *
53 * \param service the service to bind to the given port.
54 * \param port vsock port.
Alan Stokes88805d52022-12-16 16:07:33 +000055 * \param on_ready the callback to execute once the server is ready for connections. If not null the
56 * callback will be called at most once.
57 * \param param parameter to be passed to the `on_ready` callback.
Alice Wang2be64f32022-10-13 14:37:35 +000058 */
Henri Chataingd6377b42023-11-10 16:21:02 +000059__attribute__((noreturn)) void AVmPayload_runVsockRpcServer(
60 AIBinder* _Nonnull service, uint32_t port,
61 void (*_Nullable on_ready)(void* _Nullable param), void* _Nullable param);
Alice Wang2be64f32022-10-13 14:37:35 +000062
63/**
Alan Stokes6979b5f2023-01-04 15:41:39 +000064 * Returns all or part of a 32-byte secret that is bound to this unique VM
65 * instance and the supplied identifier. The secret can be used e.g. as an
66 * encryption key.
67 *
68 * Every VM has a secret that is derived from a device-specific value known to
69 * the hypervisor, the code that runs in the VM and its non-modifiable
70 * configuration; it is not made available to the host OS.
71 *
72 * This function performs a further derivation from the VM secret and the
73 * supplied identifier. As long as the VM identity doesn't change the same value
74 * will be returned for the same identifier, even if the VM is stopped &
75 * restarted or the device rebooted.
76 *
77 * If multiple secrets are required for different purposes, a different
78 * identifier should be used for each. The identifiers otherwise are arbitrary
79 * byte sequences and do not need to be kept secret; typically they are
80 * hardcoded in the calling code.
Andrew Scull102067a2022-10-07 00:34:40 +000081 *
82 * \param identifier identifier of the secret to return.
83 * \param identifier_size size of the secret identifier.
84 * \param secret pointer to size bytes where the secret is written.
Alan Stokes65bbb912022-11-23 09:39:34 +000085 * \param size number of bytes of the secret to get, <= 32.
Andrew Scull102067a2022-10-07 00:34:40 +000086 */
Alan Stokes88805d52022-12-16 16:07:33 +000087void AVmPayload_getVmInstanceSecret(const void* _Nonnull identifier, size_t identifier_size,
88 void* _Nonnull secret, size_t size);
Andrew Scull102067a2022-10-07 00:34:40 +000089
90/**
Alice Wang6bbb6da2022-10-26 12:44:06 +000091 * Gets the path to the APK contents. It is a directory, under which are
92 * the unzipped contents of the APK containing the payload, all read-only
93 * but accessible to the payload.
94 *
95 * \return the path to the APK contents. The returned string should not be
96 * deleted or freed by the application. The string remains valid for the
97 * lifetime of the VM.
98 */
Alan Stokes88805d52022-12-16 16:07:33 +000099const char* _Nonnull AVmPayload_getApkContentsPath(void);
Alice Wang6bbb6da2022-10-26 12:44:06 +0000100
Alan Stokes78d24702022-11-21 15:28:31 +0000101/**
102 * Gets the path to the encrypted persistent storage for the VM, if any. This is
103 * a directory under which any files or directories created will be stored on
104 * behalf of the VM by the host app. All data is encrypted using a key known
105 * only to the VM, so the host cannot decrypt it, but may delete it.
106 *
Alan Stokes159d3d62023-09-07 16:24:20 +0100107 * \return the path to the encrypted storage directory, or NULL if no encrypted
108 * storage was requested in the VM configuration. If non-null the returned
109 * string should not be deleted or freed by the application and remains valid
110 * for the lifetime of the VM.
Alan Stokes78d24702022-11-21 15:28:31 +0000111 */
Alan Stokes88805d52022-12-16 16:07:33 +0000112const char* _Nullable AVmPayload_getEncryptedStoragePath(void);
Alan Stokes78d24702022-11-21 15:28:31 +0000113
Alan Stokesd4ea5a82022-11-10 12:17:42 +0000114__END_DECLS