1 /* 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 19 #include <stdbool.h> 20 #include <stddef.h> 21 #include <stdint.h> 22 #include <sys/cdefs.h> 23 24 #include "vm_main.h" 25 26 __BEGIN_DECLS 27 28 typedef struct AIBinder AIBinder; 29 30 /** 31 * Introduced in API 35. 32 * Remote attestation result if the attestation succeeds. 33 */ 34 typedef struct AVmAttestationResult AVmAttestationResult; 35 36 /** 37 * Introduced in API 35. 38 * Remote attestation status types returned from remote attestation functions. 39 */ 40 typedef enum AVmAttestationStatus : int32_t { 41 /** The remote attestation completes successfully. */ 42 ATTESTATION_OK = 0, 43 44 /** The challenge size is not between 0 and 64. */ 45 ATTESTATION_ERROR_INVALID_CHALLENGE = -10001, 46 47 /** Failed to attest the VM. Please retry at a later time. */ 48 ATTESTATION_ERROR_ATTESTATION_FAILED = -10002, 49 50 /** Remote attestation is not supported in the current environment. */ 51 ATTESTATION_ERROR_UNSUPPORTED = -10003, 52 } AVmAttestationStatus; 53 54 /** 55 * Notifies the host that the payload is ready. 56 * 57 * If the host app has set a `VirtualMachineCallback` for the VM, its 58 * `onPayloadReady` method will be called. 59 * 60 * Note that subsequent calls to this function after the first have no effect; 61 * `onPayloadReady` is never called more than once. 62 */ 63 void AVmPayload_notifyPayloadReady(void); 64 65 /** 66 * Runs a binder RPC server, serving the supplied binder service implementation on the given vsock 67 * port. 68 * 69 * If and when the server is ready for connections (it is listening on the port), `on_ready` is 70 * called to allow appropriate action to be taken - e.g. to notify clients that they may now 71 * attempt to connect with `AVmPayload_notifyPayloadReady`. 72 * 73 * Note that this function does not return. The calling thread joins the binder 74 * thread pool to handle incoming messages. 75 * 76 * \param service the service to bind to the given port. 77 * \param port vsock port. 78 * \param on_ready the callback to execute once the server is ready for connections. If not null the 79 * callback will be called at most once. 80 * \param param parameter to be passed to the `on_ready` callback. 81 */ 82 __attribute__((noreturn)) void AVmPayload_runVsockRpcServer( 83 AIBinder* _Nonnull service, uint32_t port, 84 void (*_Nullable on_ready)(void* _Nullable param), void* _Nullable param); 85 86 /** 87 * Returns all or part of a 32-byte secret that is bound to this unique VM 88 * instance and the supplied identifier. The secret can be used e.g. as an 89 * encryption key. 90 * 91 * Every VM has a secret that is derived from a device-specific value known to 92 * the hypervisor, the code that runs in the VM and its non-modifiable 93 * configuration; it is not made available to the host OS. 94 * 95 * This function performs a further derivation from the VM secret and the 96 * supplied identifier. As long as the VM identity doesn't change the same value 97 * will be returned for the same identifier, even if the VM is stopped & 98 * restarted or the device rebooted. 99 * 100 * If multiple secrets are required for different purposes, a different 101 * identifier should be used for each. The identifiers otherwise are arbitrary 102 * byte sequences and do not need to be kept secret; typically they are 103 * hardcoded in the calling code. 104 * 105 * \param identifier identifier of the secret to return. 106 * \param identifier_size size of the secret identifier. 107 * \param secret pointer to size bytes where the secret is written. 108 * \param size number of bytes of the secret to get, <= 32. 109 */ 110 void AVmPayload_getVmInstanceSecret(const void* _Nonnull identifier, size_t identifier_size, 111 void* _Nonnull secret, size_t size); 112 113 /** 114 * Gets the path to the APK contents. It is a directory, under which are 115 * the unzipped contents of the APK containing the payload, all read-only 116 * but accessible to the payload. 117 * 118 * \return the path to the APK contents. The returned string should not be 119 * deleted or freed by the application. The string remains valid for the 120 * lifetime of the VM. 121 */ 122 const char* _Nonnull AVmPayload_getApkContentsPath(void); 123 124 /** 125 * Gets the path to the encrypted persistent storage for the VM, if any. This is 126 * a directory under which any files or directories created will be stored on 127 * behalf of the VM by the host app. All data is encrypted using a key known 128 * only to the VM, so the host cannot decrypt it, but may delete it. 129 * 130 * \return the path to the encrypted storage directory, or NULL if no encrypted 131 * storage was requested in the VM configuration. If non-null the returned 132 * string should not be deleted or freed by the application and remains valid 133 * for the lifetime of the VM. 134 */ 135 const char* _Nullable AVmPayload_getEncryptedStoragePath(void); 136 137 /** 138 * Requests the remote attestation of the client VM. 139 * 140 * The challenge will be included in the certificate chain in the attestation result, 141 * serving as proof of the freshness of the result. 142 * 143 * \param challenge A pointer to the challenge buffer. 144 * \param challenge_size size of the challenge. The maximum supported challenge size is 145 * 64 bytes. The status ATTESTATION_ERROR_INVALID_CHALLENGE will be returned if 146 * an invalid challenge is passed. 147 * \param result The remote attestation result will be filled here if the attestation 148 * succeeds. The result remains valid until it is freed with 149 * `AVmPayload_freeAttestationResult`. 150 * 151 * \return ATTESTATION_OK upon successful attestation. 152 */ 153 AVmAttestationStatus AVmPayload_requestAttestation(const void* _Nonnull challenge, 154 size_t challenge_size, 155 AVmAttestationResult* _Nullable* _Nonnull result) 156 __INTRODUCED_IN(__ANDROID_API_V__); 157 158 /** 159 * Converts the return value from `AVmPayload_requestAttestation` to a text string 160 * representing the status code. 161 * 162 * \return a constant string value representing the status code. The string should not 163 * be deleted or freed by the application and remains valid for the lifetime of the VM. 164 */ 165 const char* _Nonnull AVmAttestationStatus_toString(AVmAttestationStatus status) 166 __INTRODUCED_IN(__ANDROID_API_V__); 167 168 /** 169 * Frees all the data owned by the provided attestation result, including the result itself. 170 * 171 * Callers should ensure to invoke this API only once on a valid attestation result 172 * returned by `AVmPayload_requestAttestation` to avoid undefined behavior. 173 * 174 * \param result A pointer to the attestation result. 175 */ 176 void AVmAttestationResult_free(AVmAttestationResult* _Nullable result) 177 __INTRODUCED_IN(__ANDROID_API_V__); 178 179 /** 180 * Reads the DER-encoded ECPrivateKey structure specified in [RFC 5915 s3] for the 181 * EC P-256 private key from the provided attestation result. 182 * 183 * \param result A pointer to the attestation result filled in 184 * `AVmPayload_requestAttestation` when the attestation succeeds. 185 * \param data A pointer to the memory where the private key will be written 186 * (can be null if size is 0). 187 * \param size The maximum number of bytes that can be written to the data buffer. 188 * If `size` is smaller than the total size of the private key, the key data will be 189 * truncated to this `size`. 190 * 191 * \return The total size of the private key. 192 * 193 * [RFC 5915 s3]: https://datatracker.ietf.org/doc/html/rfc5915#section-3 194 */ 195 size_t AVmAttestationResult_getPrivateKey(const AVmAttestationResult* _Nonnull result, 196 void* _Nullable data, size_t size) 197 __INTRODUCED_IN(__ANDROID_API_V__); 198 199 /** 200 * Signs the given message using ECDSA P-256, the message is first hashed with SHA-256 and 201 * then it is signed with the attested EC P-256 private key in the attestation result. 202 * 203 * \param result A pointer to the attestation result filled in 204 * `AVmPayload_requestAttestation` when the attestation succeeds. 205 * \param message A pointer to the message buffer. 206 * \param message_size size of the message. 207 * \param data A pointer to the memory where the signature will be written 208 * (can be null if size is 0). The signature is a DER-encoded ECDSASignature structure 209 * detailed in the [RFC 6979]. 210 * \param size The maximum number of bytes that can be written to the data buffer. 211 * If `size` is smaller than the total size of the signature, the signature will be 212 * truncated to this `size`. 213 * 214 * \return The size of the signature, or the size needed if the supplied buffer is too small. 215 * 216 * [RFC 6979]: https://datatracker.ietf.org/doc/html/rfc6979 217 */ 218 size_t AVmAttestationResult_sign(const AVmAttestationResult* _Nonnull result, 219 const void* _Nonnull message, size_t message_size, 220 void* _Nullable data, size_t size) 221 __INTRODUCED_IN(__ANDROID_API_V__); 222 223 /** 224 * Gets the number of certificates in the certificate chain. 225 * 226 * The certificate chain consists of a sequence of DER-encoded X.509 certificates that form 227 * the attestation key's certificate chain. It starts with a leaf certificate covering the attested 228 * public key and ends with a root certificate. 229 * 230 * \param result A pointer to the attestation result obtained from `AVmPayload_requestAttestation` 231 * when the attestation succeeds. 232 * 233 * \return The number of certificates in the certificate chain. 234 */ 235 size_t AVmAttestationResult_getCertificateCount(const AVmAttestationResult* _Nonnull result) 236 __INTRODUCED_IN(__ANDROID_API_V__); 237 238 /** 239 * Retrieves the certificate at the given `index` from the certificate chain in the provided 240 * attestation result. 241 * 242 * The certificate chain consists of a sequence of DER-encoded X.509 certificates that form 243 * the attestation key's certificate chain. It starts with a leaf certificate covering the attested 244 * public key and ends with a root certificate. 245 * 246 * \param result A pointer to the attestation result obtained from `AVmPayload_requestAttestation` 247 * when the attestation succeeds. 248 * \param index Index of the certificate to retrieve. The `index` must be within the range of 249 * [0, number of certificates). The number of certificates can be obtained with 250 * `AVmAttestationResult_getCertificateCount`. 251 * \param data A pointer to the memory where the certificate will be written 252 * (can be null if size is 0). 253 * \param size The maximum number of bytes that can be written to the data buffer. If `size` 254 * is smaller than the total size of the certificate, the certificate will be 255 * truncated to this `size`. 256 * 257 * \return The total size of the certificate at the given `index`. 258 */ 259 size_t AVmAttestationResult_getCertificateAt(const AVmAttestationResult* _Nonnull result, 260 size_t index, void* _Nullable data, size_t size) 261 __INTRODUCED_IN(__ANDROID_API_V__); 262 263 __END_DECLS 264