1 /* 2 * Copyright 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 package android.system.virtualization.payload; 18 19 import android.system.virtualizationcommon.Certificate; 20 21 /** 22 * This interface regroups the tasks that payloads delegate to 23 * Microdroid Manager for execution. 24 */ 25 interface IVmPayloadService { 26 /** The constants STATUS_* are status code returned by this service. */ 27 /** Failed to prepare the CSR and key pair for attestation. */ 28 const int STATUS_FAILED_TO_PREPARE_CSR_AND_KEY = 1; 29 30 /** Socket name of the service IVmPayloadService. */ 31 const String VM_PAYLOAD_SERVICE_SOCKET_NAME = "vm_payload_service"; 32 33 /** Path to the APK contents path. */ 34 const String VM_APK_CONTENTS_PATH = "/mnt/apk"; 35 36 /** 37 * Path to the encrypted storage. Note the path will not exist if encrypted storage 38 * is not enabled. 39 */ 40 const String ENCRYPTEDSTORE_MOUNTPOINT = "/mnt/encryptedstore"; 41 42 /** 43 * An {@link AttestationResult} holds an attested private key and the remotely 44 * provisioned certificate chain covering its corresponding public key. 45 */ 46 parcelable AttestationResult { 47 /** 48 * DER-encoded ECPrivateKey structure specified in [RFC 5915 s3] for the 49 * EC P-256 private key, which is attested. 50 * 51 * The corresponding public key is included in the leaf certificate of 52 * the certificate chain. 53 * 54 * [RFC 5915 s3]: https://datatracker.ietf.org/doc/html/rfc5915#section-3 55 */ 56 byte[] privateKey; 57 58 /** 59 * Sequence of DER-encoded X.509 certificates that make up the attestation 60 * key's certificate chain. 61 * 62 * The certificate chain starts with a leaf certificate covering the attested 63 * public key and ends with a root certificate. 64 */ 65 Certificate[] certificateChain; 66 } 67 68 /** Notifies that the payload is ready to serve. */ notifyPayloadReady()69 void notifyPayloadReady(); 70 71 /** 72 * Gets a secret that is uniquely bound to this VM instance. 73 * 74 * @param identifier the identifier of the secret to return. 75 * @param size the number of bytes of the secret to return. 76 * @return size bytes of the identified secret. 77 */ getVmInstanceSecret(in byte[] identifier, int size)78 byte[] getVmInstanceSecret(in byte[] identifier, int size); 79 80 /** 81 * Write `data`, on behalf of the client, to Secretkeeper. 82 * This is confidential to the pVM and protected via appropriate DICE policy 83 * on the payload's DICE chain. 84 */ writePayloadRpData(in byte[32] data)85 void writePayloadRpData(in byte[32] data); 86 87 /** 88 * Read payload's `data` written on behalf of the payload in Secretkeeper. 89 * The returned value can be null either due to no value written or because 90 * Android maliciously deleted the value - Secretkeeper deletion are not authenticated. 91 */ readPayloadRpData()92 @nullable byte[32] readPayloadRpData(); 93 94 /** 95 * Gets the DICE attestation chain for the VM. 96 * 97 * The DICE chain must not be made available to all VMs as it contains privacy breaking 98 * identifiers. 99 * 100 * @return the VM's raw DICE certificate chain. 101 * @throws SecurityException if the use of test APIs is not permitted. 102 */ getDiceAttestationChain()103 byte[] getDiceAttestationChain(); 104 105 /** 106 * Gets the DICE attestation CDI for the VM. 107 * 108 * The raw attestation CDI isn't very useful but is used for smoke tests. A better API would 109 * handle key derivation on behalf of the payload so they can't forget to do it themselves and 110 * would also mean the payload doesn't get the raw CDI which reduces the chance of it leaking. 111 * 112 * @return the VM's raw attestation CDI. 113 * @throws SecurityException if the use of test APIs is not permitted. 114 */ getDiceAttestationCdi()115 byte[] getDiceAttestationCdi(); 116 117 /** 118 * Requests the remote attestation of the client VM. 119 * 120 * The challenge will be included in the certificate chain in the attestation result, 121 * serving as proof of the freshness of the result. 122 * 123 * @param challenge the maximum supported challenge size is 64 bytes. 124 * @param testMode whether the attestation is only for testing purposes. If testMode is true, 125 * caller must invoke {@link VirtualMachineManager#enableTestAttestation} prior to 126 * calling this method to provision a key pair to sign the attested result, and the returned 127 * certificate chain will not be RKP server rooted. 128 * 129 * @return An {@link AttestationResult} parcelable containing an attested key pair and its 130 * certification chain. 131 */ requestAttestation(in byte[] challenge, in boolean testMode)132 AttestationResult requestAttestation(in byte[] challenge, in boolean testMode); 133 134 /** 135 * Checks whether the VM instance is new - i.e., if this is the first run of an instance. 136 * This is an indication of fresh new VM secrets. Payload can use this to setup the fresh 137 * instance if needed. 138 * 139 * @return true on the first boot of the instance & false on subsequent boot. 140 */ isNewInstance()141 boolean isNewInstance(); 142 } 143