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 36 // intended 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 SecureHardwarePresentationProxy; 46 47 // This is a class used to create proxies. 48 // 49 class SecureHardwareProxyFactory : public RefBase { 50 public: SecureHardwareProxyFactory()51 SecureHardwareProxyFactory() {} ~SecureHardwareProxyFactory()52 virtual ~SecureHardwareProxyFactory() {} 53 54 virtual sp<SecureHardwareProvisioningProxy> createProvisioningProxy() = 0; 55 virtual sp<SecureHardwarePresentationProxy> createPresentationProxy() = 0; 56 }; 57 58 // The proxy used for provisioning. 59 // 60 class SecureHardwareProvisioningProxy : public RefBase { 61 public: SecureHardwareProvisioningProxy()62 SecureHardwareProvisioningProxy() {} ~SecureHardwareProvisioningProxy()63 virtual ~SecureHardwareProvisioningProxy() {} 64 65 virtual bool initialize(bool testCredential) = 0; 66 67 virtual bool initializeForUpdate(bool testCredential, string docType, 68 vector<uint8_t> encryptedCredentialKeys) = 0; 69 70 // Returns public key certificate chain with attestation. 71 // 72 // This must return an entire certificate chain and its implementation must 73 // be coordinated with the implementation of eicOpsCreateCredentialKey() on 74 // the TA side (which may return just a single certificate or the entire 75 // chain). 76 virtual optional<vector<uint8_t>> createCredentialKey( 77 const vector<uint8_t>& challenge, 78 const vector<uint8_t>& applicationId) = 0; 79 80 virtual bool startPersonalization(int accessControlProfileCount, 81 vector<int> entryCounts, 82 const string& docType, 83 size_t expectedProofOfProvisioningSize) = 0; 84 85 // Returns MAC (28 bytes). 86 virtual optional<vector<uint8_t>> addAccessControlProfile( 87 int id, const vector<uint8_t>& readerCertificate, 88 bool userAuthenticationRequired, uint64_t timeoutMillis, 89 uint64_t secureUserId) = 0; 90 91 virtual bool beginAddEntry(const vector<int>& accessControlProfileIds, 92 const string& nameSpace, const string& name, 93 uint64_t entrySize) = 0; 94 95 // Returns encryptedContent. 96 virtual optional<vector<uint8_t>> addEntryValue( 97 const vector<int>& accessControlProfileIds, const string& nameSpace, 98 const string& name, const vector<uint8_t>& content) = 0; 99 100 // Returns signatureOfToBeSigned (EIC_ECDSA_P256_SIGNATURE_SIZE bytes). 101 virtual optional<vector<uint8_t>> finishAddingEntries() = 0; 102 103 // Returns encryptedCredentialKeys (80 bytes). 104 virtual optional<vector<uint8_t>> finishGetCredentialData( 105 const string& docType) = 0; 106 107 virtual bool shutdown() = 0; 108 }; 109 110 enum AccessCheckResult { 111 kOk, 112 kFailed, 113 kNoAccessControlProfiles, 114 kUserAuthenticationFailed, 115 kReaderAuthenticationFailed, 116 }; 117 118 // The proxy used for presentation. 119 // 120 class SecureHardwarePresentationProxy : public RefBase { 121 public: SecureHardwarePresentationProxy()122 SecureHardwarePresentationProxy() {} ~SecureHardwarePresentationProxy()123 virtual ~SecureHardwarePresentationProxy() {} 124 125 virtual bool initialize(bool testCredential, string docType, 126 vector<uint8_t> encryptedCredentialKeys) = 0; 127 128 // Returns publicKeyCert (1st component) and signingKeyBlob (2nd component) 129 virtual optional<pair<vector<uint8_t>, vector<uint8_t>>> 130 generateSigningKeyPair(string docType, time_t now) = 0; 131 132 // Returns private key 133 virtual optional<vector<uint8_t>> createEphemeralKeyPair() = 0; 134 135 virtual optional<uint64_t> createAuthChallenge() = 0; 136 137 virtual bool startRetrieveEntries() = 0; 138 139 virtual bool setAuthToken(uint64_t challenge, uint64_t secureUserId, 140 uint64_t authenticatorId, 141 int hardwareAuthenticatorType, uint64_t timeStamp, 142 const vector<uint8_t>& mac, 143 uint64_t verificationTokenChallenge, 144 uint64_t verificationTokenTimestamp, 145 int verificationTokenSecurityLevel, 146 const vector<uint8_t>& verificationTokenMac) = 0; 147 148 virtual bool pushReaderCert(const vector<uint8_t>& certX509) = 0; 149 150 virtual optional<bool> validateAccessControlProfile( 151 int id, const vector<uint8_t>& readerCertificate, 152 bool userAuthenticationRequired, int timeoutMillis, uint64_t secureUserId, 153 const vector<uint8_t>& mac) = 0; 154 155 virtual bool validateRequestMessage( 156 const vector<uint8_t>& sessionTranscript, 157 const vector<uint8_t>& requestMessage, int coseSignAlg, 158 const vector<uint8_t>& readerSignatureOfToBeSigned) = 0; 159 160 virtual bool calcMacKey(const vector<uint8_t>& sessionTranscript, 161 const vector<uint8_t>& readerEphemeralPublicKey, 162 const vector<uint8_t>& signingKeyBlob, 163 const string& docType, 164 unsigned int numNamespacesWithValues, 165 size_t expectedProofOfProvisioningSize) = 0; 166 167 virtual AccessCheckResult startRetrieveEntryValue( 168 const string& nameSpace, const string& name, 169 unsigned int newNamespaceNumEntries, int32_t entrySize, 170 const vector<int32_t>& accessControlProfileIds) = 0; 171 172 virtual optional<vector<uint8_t>> retrieveEntryValue( 173 const vector<uint8_t>& encryptedContent, const string& nameSpace, 174 const string& name, const vector<int32_t>& accessControlProfileIds) = 0; 175 176 virtual optional<vector<uint8_t>> finishRetrieval(); 177 178 virtual optional<vector<uint8_t>> deleteCredential( 179 const string& docType, const vector<uint8_t>& challenge, 180 bool includeChallenge, size_t proofOfDeletionCborSize) = 0; 181 182 virtual optional<vector<uint8_t>> proveOwnership( 183 const string& docType, bool testCredential, 184 const vector<uint8_t>& challenge, size_t proofOfOwnershipCborSize) = 0; 185 186 virtual bool shutdown() = 0; 187 }; 188 189 } // namespace android::hardware::identity 190 191 #endif // ANDROID_HARDWARE_IDENTITY_SECUREHARDWAREPROXY_H 192