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 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(const vector<uint8_t>& challenge, 77 const vector<uint8_t>& applicationId) = 0; 78 79 virtual bool startPersonalization(int accessControlProfileCount, vector<int> entryCounts, 80 const string& docType, 81 size_t expectedProofOfProvisioningSize) = 0; 82 83 // Returns MAC (28 bytes). 84 virtual optional<vector<uint8_t>> addAccessControlProfile( 85 int id, const vector<uint8_t>& readerCertificate, bool userAuthenticationRequired, 86 uint64_t timeoutMillis, uint64_t secureUserId) = 0; 87 88 virtual bool beginAddEntry(const vector<int>& accessControlProfileIds, const string& nameSpace, 89 const string& name, uint64_t entrySize) = 0; 90 91 // Returns encryptedContent. 92 virtual optional<vector<uint8_t>> addEntryValue(const vector<int>& accessControlProfileIds, 93 const string& nameSpace, const string& name, 94 const vector<uint8_t>& content) = 0; 95 96 // Returns signatureOfToBeSigned (EIC_ECDSA_P256_SIGNATURE_SIZE bytes). 97 virtual optional<vector<uint8_t>> finishAddingEntries() = 0; 98 99 // Returns encryptedCredentialKeys (80 bytes). 100 virtual optional<vector<uint8_t>> finishGetCredentialData(const string& docType) = 0; 101 102 virtual bool shutdown() = 0; 103 }; 104 105 enum AccessCheckResult { 106 kOk, 107 kFailed, 108 kNoAccessControlProfiles, 109 kUserAuthenticationFailed, 110 kReaderAuthenticationFailed, 111 }; 112 113 // The proxy used for presentation. 114 // 115 class SecureHardwarePresentationProxy : public RefBase { 116 public: SecureHardwarePresentationProxy()117 SecureHardwarePresentationProxy() {} ~SecureHardwarePresentationProxy()118 virtual ~SecureHardwarePresentationProxy() {} 119 120 virtual bool initialize(bool testCredential, string docType, 121 vector<uint8_t> encryptedCredentialKeys) = 0; 122 123 // Returns publicKeyCert (1st component) and signingKeyBlob (2nd component) 124 virtual optional<pair<vector<uint8_t>, vector<uint8_t>>> generateSigningKeyPair(string docType, 125 time_t now) = 0; 126 127 // Returns private key 128 virtual optional<vector<uint8_t>> createEphemeralKeyPair() = 0; 129 130 virtual optional<uint64_t> createAuthChallenge() = 0; 131 132 virtual bool startRetrieveEntries() = 0; 133 134 virtual bool setAuthToken(uint64_t challenge, uint64_t secureUserId, uint64_t authenticatorId, 135 int hardwareAuthenticatorType, uint64_t timeStamp, 136 const vector<uint8_t>& mac, uint64_t verificationTokenChallenge, 137 uint64_t verificationTokenTimestamp, 138 int verificationTokenSecurityLevel, 139 const vector<uint8_t>& verificationTokenMac) = 0; 140 141 virtual bool pushReaderCert(const vector<uint8_t>& certX509) = 0; 142 143 virtual optional<bool> validateAccessControlProfile(int id, 144 const vector<uint8_t>& readerCertificate, 145 bool userAuthenticationRequired, 146 int timeoutMillis, uint64_t secureUserId, 147 const vector<uint8_t>& mac) = 0; 148 149 virtual bool validateRequestMessage(const vector<uint8_t>& sessionTranscript, 150 const vector<uint8_t>& requestMessage, int coseSignAlg, 151 const vector<uint8_t>& readerSignatureOfToBeSigned) = 0; 152 153 virtual bool calcMacKey(const vector<uint8_t>& sessionTranscript, 154 const vector<uint8_t>& readerEphemeralPublicKey, 155 const vector<uint8_t>& signingKeyBlob, const string& docType, 156 unsigned int numNamespacesWithValues, 157 size_t expectedProofOfProvisioningSize) = 0; 158 159 virtual AccessCheckResult startRetrieveEntryValue( 160 const string& nameSpace, const string& name, unsigned int newNamespaceNumEntries, 161 int32_t entrySize, const vector<int32_t>& accessControlProfileIds) = 0; 162 163 virtual optional<vector<uint8_t>> retrieveEntryValue( 164 const vector<uint8_t>& encryptedContent, const string& nameSpace, const string& name, 165 const vector<int32_t>& accessControlProfileIds) = 0; 166 167 virtual optional<vector<uint8_t>> finishRetrieval(); 168 169 virtual optional<vector<uint8_t>> deleteCredential(const string& docType, 170 const vector<uint8_t>& challenge, 171 bool includeChallenge, 172 size_t proofOfDeletionCborSize) = 0; 173 174 virtual optional<vector<uint8_t>> proveOwnership(const string& docType, bool testCredential, 175 const vector<uint8_t>& challenge, 176 size_t proofOfOwnershipCborSize) = 0; 177 178 virtual bool shutdown() = 0; 179 }; 180 181 } // namespace android::hardware::identity 182 183 #endif // ANDROID_HARDWARE_IDENTITY_SECUREHARDWAREPROXY_H 184