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      * Gets the DICE attestation chain for the VM.
82      *
83      * The DICE chain must not be made available to all VMs as it contains privacy breaking
84      * identifiers.
85      *
86      * @return the VM's raw DICE certificate chain.
87      * @throws SecurityException if the use of test APIs is not permitted.
88      */
getDiceAttestationChain()89     byte[] getDiceAttestationChain();
90 
91     /**
92      * Gets the DICE attestation CDI for the VM.
93      *
94      * The raw attestation CDI isn't very useful but is used for smoke tests. A better API would
95      * handle key derivation on behalf of the payload so they can't forget to do it themselves and
96      * would also mean the payload doesn't get the raw CDI which reduces the chance of it leaking.
97      *
98      * @return the VM's raw attestation CDI.
99      * @throws SecurityException if the use of test APIs is not permitted.
100      */
getDiceAttestationCdi()101     byte[] getDiceAttestationCdi();
102 
103     /**
104      * Requests the remote attestation of the client VM.
105      *
106      * The challenge will be included in the certificate chain in the attestation result,
107      * serving as proof of the freshness of the result.
108      *
109      * @param challenge the maximum supported challenge size is 64 bytes.
110      * @param testMode whether the attestation is only for testing purposes. If testMode is true,
111      * caller must invoke {@link VirtualMachineManager#enableTestAttestation} prior to
112      * calling this method to provision a key pair to sign the attested result, and the returned
113      * certificate chain will not be RKP server rooted.
114      *
115      * @return An {@link AttestationResult} parcelable containing an attested key pair and its
116      *         certification chain.
117      */
requestAttestation(in byte[] challenge, in boolean testMode)118     AttestationResult requestAttestation(in byte[] challenge, in boolean testMode);
119 }
120