blob: e0c261314ae538998d8bca22318c5ee4659a079e [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 Stokese0945ad2022-11-24 13:29:57 +000022#include <stdnoreturn.h>
Alan Stokesd4ea5a82022-11-10 12:17:42 +000023#include <sys/cdefs.h>
Andrew Scull102067a2022-10-07 00:34:40 +000024
Alan Stokes52d3c722022-10-04 17:27:13 +010025#include "vm_main.h"
26
Alan Stokesd4ea5a82022-11-10 12:17:42 +000027__BEGIN_DECLS
Alice Wangfb46ee12022-09-30 13:08:52 +000028
Alice Wang2be64f32022-10-13 14:37:35 +000029struct AIBinder;
30typedef struct AIBinder AIBinder;
31
Andrew Sculld64ae7d2022-10-05 17:41:43 +000032/**
33 * Notifies the host that the payload is ready.
Andrew Scull655e98e2022-10-10 22:24:58 +000034 *
Alan Stokes65bbb912022-11-23 09:39:34 +000035 * If the host app has set a `VirtualMachineCallback` for the VM, its
36 * `onPayloadReady` method will be called.
37 *
38 * Note that subsequent calls to this function after the first have no effect;
39 * `onPayloadReady` is never called more than once.
Andrew Sculld64ae7d2022-10-05 17:41:43 +000040 */
Alan Stokes65bbb912022-11-23 09:39:34 +000041void AVmPayload_notifyPayloadReady(void);
Alice Wangfb46ee12022-09-30 13:08:52 +000042
Andrew Sculld64ae7d2022-10-05 17:41:43 +000043/**
Alice Wang2be64f32022-10-13 14:37:35 +000044 * Runs a binder RPC server, serving the supplied binder service implementation on the given vsock
45 * port.
46 *
47 * If and when the server is ready for connections (it is listening on the port), `on_ready` is
48 * called to allow appropriate action to be taken - e.g. to notify clients that they may now
49 * attempt to connect with `AVmPayload_notifyPayloadReady`.
50 *
Alan Stokese0945ad2022-11-24 13:29:57 +000051 * Note that this function does not return. The calling thread joins the binder
52 * thread pool to handle incoming messages.
Alice Wang2be64f32022-10-13 14:37:35 +000053 *
54 * \param service the service to bind to the given port.
55 * \param port vsock port.
Alan Stokes88805d52022-12-16 16:07:33 +000056 * \param on_ready the callback to execute once the server is ready for connections. If not null the
57 * callback will be called at most once.
58 * \param param parameter to be passed to the `on_ready` callback.
Alice Wang2be64f32022-10-13 14:37:35 +000059 */
Alan Stokes88805d52022-12-16 16:07:33 +000060noreturn void AVmPayload_runVsockRpcServer(AIBinder* _Nonnull service, uint32_t port,
61 void (*_Nullable on_ready)(void* _Nullable param),
62 void* _Nullable param);
Alice Wang2be64f32022-10-13 14:37:35 +000063
64/**
Alan Stokes0cbfdf92022-11-21 17:17:53 +000065 * Get a secret that is uniquely bound to this VM instance. The secrets are
Alan Stokes65bbb912022-11-23 09:39:34 +000066 * 32-byte values and the value associated with an identifier will not change
67 * over the lifetime of the VM instance.
Andrew Scull102067a2022-10-07 00:34:40 +000068 *
69 * \param identifier identifier of the secret to return.
70 * \param identifier_size size of the secret identifier.
71 * \param secret pointer to size bytes where the secret is written.
Alan Stokes65bbb912022-11-23 09:39:34 +000072 * \param size number of bytes of the secret to get, <= 32.
Andrew Scull102067a2022-10-07 00:34:40 +000073 */
Alan Stokes88805d52022-12-16 16:07:33 +000074void AVmPayload_getVmInstanceSecret(const void* _Nonnull identifier, size_t identifier_size,
75 void* _Nonnull secret, size_t size);
Andrew Scull102067a2022-10-07 00:34:40 +000076
77/**
Alice Wang6bbb6da2022-10-26 12:44:06 +000078 * Gets the path to the APK contents. It is a directory, under which are
79 * the unzipped contents of the APK containing the payload, all read-only
80 * but accessible to the payload.
81 *
82 * \return the path to the APK contents. The returned string should not be
83 * deleted or freed by the application. The string remains valid for the
84 * lifetime of the VM.
85 */
Alan Stokes88805d52022-12-16 16:07:33 +000086const char* _Nonnull AVmPayload_getApkContentsPath(void);
Alice Wang6bbb6da2022-10-26 12:44:06 +000087
Alan Stokes78d24702022-11-21 15:28:31 +000088/**
89 * Gets the path to the encrypted persistent storage for the VM, if any. This is
90 * a directory under which any files or directories created will be stored on
91 * behalf of the VM by the host app. All data is encrypted using a key known
92 * only to the VM, so the host cannot decrypt it, but may delete it.
93 *
94 * \return the path to the APK contents, or NULL if no encrypted storage was
95 * requested in the VM configuration. If non-null the returned string should not
96 * be deleted or freed by the application and remains valid for the lifetime of
97 * the VM.
98 */
Alan Stokes88805d52022-12-16 16:07:33 +000099const char* _Nullable AVmPayload_getEncryptedStoragePath(void);
Alan Stokes78d24702022-11-21 15:28:31 +0000100
Alan Stokesd4ea5a82022-11-10 12:17:42 +0000101__END_DECLS