1 /* 2 * Copyright (C) 2020 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.security.remoteprovisioning; 18 19 import android.hardware.security.keymint.DeviceInfo; 20 import android.hardware.security.keymint.ProtectedData; 21 import android.hardware.security.keymint.SecurityLevel; 22 import android.security.remoteprovisioning.AttestationPoolStatus; 23 import android.security.remoteprovisioning.ImplInfo; 24 25 /** 26 * `IRemoteProvisioning` is the interface provided to use the remote provisioning functionality 27 * provided through KeyStore. The intent is for a higher level system component to use these 28 * functions in order to drive the process through which the device can receive functioning 29 * attestation certificates. 30 * 31 * ## Error conditions 32 * Error conditions are reported as service specific errors. 33 * Positive codes correspond to `android.security.remoteprovisioning.ResponseCode` 34 * and indicate error conditions diagnosed by the Keystore 2.0 service. 35 * TODO: Remote Provisioning HAL error code info 36 * 37 * `ResponseCode::PERMISSION_DENIED` if the caller does not have the permissions 38 * to use the RemoteProvisioning API. This permission is defined under access_vectors in SEPolicy 39 * in the keystore2 class: remotely_provision 40 * 41 * `ResponseCode::SYSTEM_ERROR` for any unexpected errors like IO or IPC failures. 42 * 43 * @hide 44 */ 45 interface IRemoteProvisioning { 46 47 /** 48 * Returns the status of the attestation key pool in the database. 49 * 50 * @param expiredBy The date as seconds since epoch by which to judge expiration status of 51 * certificates. 52 * 53 * @param secLevel The security level to specify which KM instance to get the pool for. 54 * 55 * @return The `AttestationPoolStatus` parcelable contains fields communicating information 56 * relevant to making decisions about when to generate and provision 57 * more attestation keys. 58 */ getPoolStatus(in long expiredBy, in SecurityLevel secLevel)59 AttestationPoolStatus getPoolStatus(in long expiredBy, in SecurityLevel secLevel); 60 61 /** 62 * This is the primary entry point for beginning a remote provisioning flow. The caller 63 * specifies how many CSRs should be generated and provides an X25519 ECDH public key along 64 * with a challenge to encrypt privacy sensitive portions of the returned CBOR blob and 65 * guarantee freshness of the request to the certifying third party. 66 * 67 * ## Error conditions 68 * `ResponseCode::NO_UNSIGNED_KEYS` if there are no unsigned keypairs in the database that can 69 * be used for the CSRs. 70 * 71 * A RemoteProvisioning HAL response code may indicate backend errors such as failed EEK 72 * verification. 73 * 74 * @param testMode Whether or not the TA implementing the Remote Provisioning HAL should accept 75 * any EEK (Endpoint Encryption Key), or only one signed by a chain 76 * that verifies back to the Root of Trust baked into the TA. True 77 * means that any key is accepted. 78 * 79 * @param numCsr How many certificate signing requests should be generated. 80 * 81 * @param eek A chain of certificates terminating in an X25519 public key, the Endpoint 82 * Encryption Key. 83 * 84 * @param challenge A challenge to be included and MACed in the returned CBOR blob. 85 * 86 * @param secLevel The security level to specify which KM instance from which to generate a 87 * CSR. 88 * 89 * @param protectedData The encrypted CBOR blob generated by the remote provisioner 90 * 91 * @return A CBOR blob composed of various elements required by the server to verify the 92 * request. 93 */ generateCsr(in boolean testMode, in int numCsr, in byte[] eek, in byte[] challenge, in SecurityLevel secLevel, out ProtectedData protectedData, out DeviceInfo deviceInfo)94 byte[] generateCsr(in boolean testMode, in int numCsr, in byte[] eek, in byte[] challenge, 95 in SecurityLevel secLevel, out ProtectedData protectedData, out DeviceInfo deviceInfo); 96 97 /** 98 * This method provides a way for the returned attestation certificate chains to be provisioned 99 * to the attestation key database. When an app requests an attesation key, it will be assigned 100 * one of these certificate chains along with the corresponding private key. 101 * 102 * @param publicKey The raw public key encoded in the leaf certificate. 103 * 104 * @param batchCert The batch certificate corresponding to the attestation key. Separated for 105 * the purpose of making Subject lookup for KM attestation easier. 106 * 107 * @param certs An X.509, DER encoded certificate chain for the attestation key. 108 * 109 * @param expirationDate The expiration date on the certificate chain, provided by the caller 110 * for convenience. 111 * 112 * @param secLevel The security level representing the KM instance containing the key that this 113 * chain corresponds to. 114 */ provisionCertChain(in byte[] publicKey, in byte[] batchCert, in byte[] certs, in long expirationDate, in SecurityLevel secLevel)115 void provisionCertChain(in byte[] publicKey, in byte[] batchCert, in byte[] certs, 116 in long expirationDate, in SecurityLevel secLevel); 117 118 /** 119 * This method allows the caller to instruct KeyStore to generate and store a key pair to be 120 * used for attestation in the `generateCsr` method. The caller should handle spacing out these 121 * requests so as not to jam up the KeyStore work queue. 122 * 123 * @param is_test_mode Instructs the underlying HAL interface to mark the generated key with a 124 * tag to indicate that it's for testing. 125 * 126 * @param secLevel The security level to specify which KM instance should generate a key pair. 127 */ generateKeyPair(in boolean is_test_mode, in SecurityLevel secLevel)128 void generateKeyPair(in boolean is_test_mode, in SecurityLevel secLevel); 129 130 /** 131 * This method returns implementation information for whichever instances of 132 * IRemotelyProvisionedComponent are running on the device. The RemoteProvisioner app needs to 133 * know which KM instances it should be generating and managing attestation keys for, and which 134 * EC curves are supported in those instances. 135 * 136 * @return The array of ImplInfo parcelables. 137 */ getImplementationInfo()138 ImplInfo[] getImplementationInfo(); 139 140 /** 141 * This method deletes all remotely provisioned attestation keys in the database, regardless 142 * of what state in their life cycle they are in. This is primarily useful to facilitate 143 * testing. 144 * 145 * @return Number of keys deleted 146 */ deleteAllKeys()147 long deleteAllKeys(); 148 } 149