1 /* 2 * Copyright 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 #ifndef ANDROID_HARDWARE_IDENTITY_SECUREHARDWAREPROXY_H 18 #define ANDROID_HARDWARE_IDENTITY_SECUREHARDWAREPROXY_H 19 20 #include <utils/RefBase.h> 21 #include <optional> 22 #include <string> 23 #include <utility> 24 #include <vector> 25 26 namespace android::hardware::identity { 27 28 using ::android::RefBase; 29 using ::std::optional; 30 using ::std::pair; 31 using ::std::string; 32 using ::std::vector; 33 34 // These classes are used to communicate with Secure Hardware. They mimic the 35 // API in libEmbeddedIC 1:1 (except for using C++ types) as each call is intended 36 // to be forwarded to the Secure Hardware. 37 // 38 // Instances are instantiated when a provisioning or presentation session 39 // starts. When the session is complete, the shutdown() method is called. 40 // 41 42 // Forward declare. 43 // 44 class SecureHardwareProvisioningProxy; 45 class SecureHardwareSessionProxy; 46 class SecureHardwarePresentationProxy; 47 48 // This is a class used to create proxies. 49 // 50 class SecureHardwareProxyFactory : public RefBase { 51 public: SecureHardwareProxyFactory()52 SecureHardwareProxyFactory() {} ~SecureHardwareProxyFactory()53 virtual ~SecureHardwareProxyFactory() {} 54 55 virtual sp<SecureHardwareProvisioningProxy> createProvisioningProxy() = 0; 56 virtual sp<SecureHardwareSessionProxy> createSessionProxy() = 0; 57 virtual sp<SecureHardwarePresentationProxy> createPresentationProxy() = 0; 58 }; 59 60 // The proxy used for provisioning. 61 // 62 class SecureHardwareProvisioningProxy : public RefBase { 63 public: SecureHardwareProvisioningProxy()64 SecureHardwareProvisioningProxy() {} ~SecureHardwareProvisioningProxy()65 virtual ~SecureHardwareProvisioningProxy() {} 66 67 virtual bool initialize(bool testCredential) = 0; 68 69 virtual bool initializeForUpdate(bool testCredential, const string& docType, 70 const vector<uint8_t>& encryptedCredentialKeys) = 0; 71 72 virtual optional<uint32_t> getId() = 0; 73 74 virtual bool shutdown() = 0; 75 76 // Returns public key certificate chain with attestation. 77 // 78 // This must return an entire certificate chain and its implementation must 79 // be coordinated with the implementation of eicOpsCreateCredentialKey() on 80 // the TA side (which may return just a single certificate or the entire 81 // chain). 82 virtual optional<vector<uint8_t>> createCredentialKey(const vector<uint8_t>& challenge, 83 const vector<uint8_t>& applicationId) = 0; 84 85 // Returns public key certificate with a remotely provisioned attestation key. 86 // 87 // This returns a single certificate that is signed by the given |attestationKeyBlob|. 88 // The implementation of eicOpsCreateCredentialKey() on the TA side must coordinate 89 // with its corresponding keymint implementation to sign using the attestation key. The 90 // |attestationKeyCert| parameter is the certificates for |attestationKeyBlob|, 91 // formatted as concatenated, DER-encoded, X.509 certificates. 92 virtual optional<vector<uint8_t>> createCredentialKeyUsingRkp( 93 const vector<uint8_t>& challenge, const vector<uint8_t>& applicationId, 94 const vector<uint8_t>& attestationKeyBlob, 95 const vector<uint8_t>& attestationKeyCert) = 0; 96 97 virtual bool startPersonalization(int accessControlProfileCount, const vector<int>& entryCounts, 98 const string& docType, 99 size_t expectedProofOfProvisioningSize) = 0; 100 101 // Returns MAC (28 bytes). 102 virtual optional<vector<uint8_t>> addAccessControlProfile( 103 int id, const vector<uint8_t>& readerCertificate, bool userAuthenticationRequired, 104 uint64_t timeoutMillis, uint64_t secureUserId) = 0; 105 106 virtual bool beginAddEntry(const vector<int>& accessControlProfileIds, const string& nameSpace, 107 const string& name, uint64_t entrySize) = 0; 108 109 // Returns encryptedContent. 110 virtual optional<vector<uint8_t>> addEntryValue(const vector<int>& accessControlProfileIds, 111 const string& nameSpace, const string& name, 112 const vector<uint8_t>& content) = 0; 113 114 // Returns signatureOfToBeSigned (EIC_ECDSA_P256_SIGNATURE_SIZE bytes). 115 virtual optional<vector<uint8_t>> finishAddingEntries() = 0; 116 117 // Returns encryptedCredentialKeys (80 bytes). 118 virtual optional<vector<uint8_t>> finishGetCredentialData(const string& docType) = 0; 119 }; 120 121 enum AccessCheckResult { 122 kOk, 123 kFailed, 124 kNoAccessControlProfiles, 125 kUserAuthenticationFailed, 126 kReaderAuthenticationFailed, 127 }; 128 129 // The proxy used for sessions. 130 // 131 class SecureHardwareSessionProxy : public RefBase { 132 public: SecureHardwareSessionProxy()133 SecureHardwareSessionProxy() {} 134 ~SecureHardwareSessionProxy()135 virtual ~SecureHardwareSessionProxy() {} 136 137 virtual bool initialize() = 0; 138 139 virtual optional<uint32_t> getId() = 0; 140 141 virtual bool shutdown() = 0; 142 143 virtual optional<uint64_t> getAuthChallenge() = 0; 144 145 // Returns private key 146 virtual optional<vector<uint8_t>> getEphemeralKeyPair() = 0; 147 148 virtual bool setReaderEphemeralPublicKey(const vector<uint8_t>& readerEphemeralPublicKey) = 0; 149 150 virtual bool setSessionTranscript(const vector<uint8_t>& sessionTranscript) = 0; 151 }; 152 153 // The proxy used for presentation. 154 // 155 class SecureHardwarePresentationProxy : public RefBase { 156 public: SecureHardwarePresentationProxy()157 SecureHardwarePresentationProxy() {} ~SecureHardwarePresentationProxy()158 virtual ~SecureHardwarePresentationProxy() {} 159 160 virtual bool initialize(uint32_t sessionId, bool testCredential, const string& docType, 161 const vector<uint8_t>& encryptedCredentialKeys) = 0; 162 163 virtual optional<uint32_t> getId() = 0; 164 165 virtual bool shutdown() = 0; 166 167 // Returns publicKeyCert (1st component) and signingKeyBlob (2nd component) 168 virtual optional<pair<vector<uint8_t>, vector<uint8_t>>> generateSigningKeyPair( 169 const string& docType, time_t now) = 0; 170 171 // Returns private key 172 virtual optional<vector<uint8_t>> createEphemeralKeyPair() = 0; 173 174 virtual optional<uint64_t> createAuthChallenge() = 0; 175 176 virtual bool startRetrieveEntries() = 0; 177 178 virtual bool setAuthToken(uint64_t challenge, uint64_t secureUserId, uint64_t authenticatorId, 179 int hardwareAuthenticatorType, uint64_t timeStamp, 180 const vector<uint8_t>& mac, uint64_t verificationTokenChallenge, 181 uint64_t verificationTokenTimestamp, 182 int verificationTokenSecurityLevel, 183 const vector<uint8_t>& verificationTokenMac) = 0; 184 185 virtual bool pushReaderCert(const vector<uint8_t>& certX509) = 0; 186 187 virtual optional<bool> validateAccessControlProfile(int id, 188 const vector<uint8_t>& readerCertificate, 189 bool userAuthenticationRequired, 190 int timeoutMillis, uint64_t secureUserId, 191 const vector<uint8_t>& mac) = 0; 192 193 virtual bool validateRequestMessage(const vector<uint8_t>& sessionTranscript, 194 const vector<uint8_t>& requestMessage, int coseSignAlg, 195 const vector<uint8_t>& readerSignatureOfToBeSigned) = 0; 196 197 virtual bool prepareDeviceAuthentication(const vector<uint8_t>& sessionTranscript, 198 const vector<uint8_t>& readerEphemeralPublicKey, 199 const vector<uint8_t>& signingKeyBlob, 200 const string& docType, 201 unsigned int numNamespacesWithValues, 202 size_t expectedDeviceNamespacesSize) = 0; 203 204 virtual AccessCheckResult startRetrieveEntryValue( 205 const string& nameSpace, const string& name, unsigned int newNamespaceNumEntries, 206 int32_t entrySize, const vector<int32_t>& accessControlProfileIds) = 0; 207 208 virtual optional<vector<uint8_t>> retrieveEntryValue( 209 const vector<uint8_t>& encryptedContent, const string& nameSpace, const string& name, 210 const vector<int32_t>& accessControlProfileIds) = 0; 211 212 virtual optional<vector<uint8_t>> finishRetrieval(); 213 virtual optional<pair<vector<uint8_t>, vector<uint8_t>>> finishRetrievalWithSignature(); 214 215 virtual optional<vector<uint8_t>> deleteCredential(const string& docType, 216 const vector<uint8_t>& challenge, 217 bool includeChallenge, 218 size_t proofOfDeletionCborSize) = 0; 219 220 virtual optional<vector<uint8_t>> proveOwnership(const string& docType, bool testCredential, 221 const vector<uint8_t>& challenge, 222 size_t proofOfOwnershipCborSize) = 0; 223 }; 224 225 } // namespace android::hardware::identity 226 227 #endif // ANDROID_HARDWARE_IDENTITY_SECUREHARDWAREPROXY_H 228