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