• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright 2015 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 SYSTEM_KEYMASTER_KEYMASTER_CONTEXT_H_
18 #define SYSTEM_KEYMASTER_KEYMASTER_CONTEXT_H_
19 
20 #include <optional>
21 
22 #include <assert.h>
23 
24 #include <hardware/keymaster_defs.h>
25 #include <keymaster/android_keymaster_utils.h>
26 #include <keymaster/keymaster_enforcement.h>
27 #include <keymaster/km_version.h>
28 #include <keymaster/remote_provisioning_context.h>
29 #include <keymaster/secure_key_storage.h>
30 
31 namespace keymaster {
32 
33 class AuthorizationSet;
34 class KeyFactory;
35 class OperationFactory;
36 template <typename BlobType> struct TKeymasterBlob;
37 typedef TKeymasterBlob<keymaster_key_blob_t> KeymasterKeyBlob;
38 class Key;
39 
40 /**
41  * KeymasterContext provides a singleton abstract interface that encapsulates various
42  * environment-dependent elements of AndroidKeymaster.
43  *
44  * AndroidKeymaster runs in multiple contexts.  Primarily:
45  *
46  * - In a trusted execution environment (TEE) as a "secure hardware" implementation.  In this
47  *   context keys are wrapped with an master key that never leaves the TEE, TEE-specific routines
48  *   are used for random number generation, all AndroidKeymaster-enforced authorizations are
49  *   considered hardware-enforced, and there's a bootloader-provided root of trust.
50  *
51  * - In the non-secure world as a software-only implementation.  In this context keys are not
52  *   encrypted (though they are integrity-checked) because there is no place to securely store a
53  *   key, OpenSSL is used for random number generation, no AndroidKeymaster-enforced authorizations
54  *   are considered hardware enforced and the root of trust is a static string.
55  *
56  * - In the non-secure world as a hybrid implementation fronting a less-capable hardware
57  *   implementation.  For example, a keymaster0 hardware implementation.  In this context keys are
58  *   not encrypted by AndroidKeymaster, but some may be opaque blobs provided by the backing
59  *   hardware, but blobs that lack the extended authorization lists of keymaster1.  In addition,
60  *   keymaster0 lacks many features of keymaster1, including modes of operation related to the
61  *   backing keymaster0 keys.  AndroidKeymaster must extend the blobs to add authorization lists,
62  *   and must provide the missing operation mode implementations in software, which means that
63  *   authorization lists are partially hardware-enforced (the bits that are enforced by the
64  *   underlying keymaster0) and partially software-enforced (the rest). OpenSSL is used for number
65  *   generation and the root of trust is a static string.
66  *
67  * More contexts are possible.
68  */
69 class KeymasterContext {
70   public:
KeymasterContext()71     KeymasterContext() {}
~KeymasterContext()72     virtual ~KeymasterContext(){};
73 
74     /**
75      * Returns the Keymaster/KeyMint version we're currently implementing.
76      *
77      * Because AndroidKeymaster supports multiple versions of Keymaster/KeyMint, with slightly
78      * different behavior, we sometimes need to branch based on the version currently being
79      * implemented.  This method provides the currently-implemented version.
80      */
81     virtual KmVersion GetKmVersion() const = 0;
82 
83     /**
84      * Sets the system version as reported by the system *itself*.  This is used to verify that the
85      * system believes itself to be running the same version that is reported by the bootloader, in
86      * hardware implementations.  For SoftKeymasterDevice, this sets the version information used.
87      *
88      * If the specified values don't match the bootloader-provided values, this method must return
89      * KM_ERROR_INVALID_ARGUMENT;
90      */
91     virtual keymaster_error_t SetSystemVersion(uint32_t os_version, uint32_t os_patchlevel) = 0;
92 
93     /**
94      * Returns the system version.  For hardware-based implementations this will be the value
95      * reported by the bootloader.  For SoftKeymasterDevice it will be the verion information set by
96      * SetSystemVersion above.
97      */
98     virtual void GetSystemVersion(uint32_t* os_version, uint32_t* os_patchlevel) const = 0;
99 
100     virtual const KeyFactory* GetKeyFactory(keymaster_algorithm_t algorithm) const = 0;
101     virtual const OperationFactory* GetOperationFactory(keymaster_algorithm_t algorithm,
102                                                         keymaster_purpose_t purpose) const = 0;
103     virtual const keymaster_algorithm_t* GetSupportedAlgorithms(size_t* algorithms_count) const = 0;
104 
105     /**
106      * UpgradeKeyBlob takes an existing blob, parses out key material and constructs a new blob with
107      * the current format and OS version info.
108      */
109     virtual keymaster_error_t UpgradeKeyBlob(const KeymasterKeyBlob& key_to_upgrade,
110                                              const AuthorizationSet& upgrade_params,
111                                              KeymasterKeyBlob* upgraded_key) const = 0;
112 
113     /**
114      * ParseKeyBlob takes a blob and extracts authorization sets and key material, returning an
115      * error if the blob fails integrity checking or decryption.  Note that the returned key
116      * material may itself be an opaque blob usable only by secure hardware (in the hybrid case).
117      *
118      * This method is called by AndroidKeymaster.
119      */
120     virtual keymaster_error_t ParseKeyBlob(const KeymasterKeyBlob& blob,
121                                            const AuthorizationSet& additional_params,
122                                            UniquePtr<Key>* key) const = 0;
123 
124     /**
125      * Take whatever environment-specific action is appropriate (if any) to delete the specified
126      * key.
127      */
DeleteKey(const KeymasterKeyBlob &)128     virtual keymaster_error_t DeleteKey(const KeymasterKeyBlob& /* blob */) const {
129         return KM_ERROR_OK;
130     }
131 
132     /**
133      * Take whatever environment-specific action is appropriate to delete all keys.
134      */
DeleteAllKeys()135     virtual keymaster_error_t DeleteAllKeys() const { return KM_ERROR_OK; }
136 
137     /**
138      * Adds entropy to the Cryptographic Pseudo Random Number Generator used to generate key
139      * material, and other cryptographic protocol elements.  Note that if the underlying CPRNG
140      * tracks the size of its entropy pool, it should not assume that the provided data contributes
141      * any entropy, and it should also ensure that data provided through this interface cannot
142      * "poison" the CPRNG outputs, making them predictable.
143      */
144     virtual keymaster_error_t AddRngEntropy(const uint8_t* buf, size_t length) const = 0;
145 
146     /**
147      * Return the enforcement policy for this context, or null if no enforcement should be done.
148      */
149     virtual KeymasterEnforcement* enforcement_policy() = 0;
150 
151     /**
152      * Generate an attestation certificate, with chain.
153      *
154      * If attest_key is null, the certificate will be signed with the factory attestation key (from
155      * AttestationContext) and have the issuer subject set to the subject name from the signing key
156      * certificate.  If attest_key is non-null, it will be used to sign the certificate and the
157      * provided issuer subject will be used (must contain a DER-encoded X.509 NAME).
158      */
159     virtual CertificateChain GenerateAttestation(const Key& key,
160                                                  const AuthorizationSet& attest_params,
161                                                  UniquePtr<Key> attest_key,
162                                                  const KeymasterBlob& issuer_subject,
163                                                  keymaster_error_t* error) const = 0;
164 
165     /**
166      * Generate a self-signed certificate.  If fake_signature is true, a fake signature is installed
167      * in the certificate, rather than an actual self-signature.  The fake signature will not
168      * verify, of course.  In this case the certificate is primarily a way to convey the public key.
169      *
170      * Note that although the return type is CertificateChain, this is for convenience and
171      * consistency with GenerateAttestation, the chain never contains more than a single
172      * certificate.
173      */
174     virtual CertificateChain GenerateSelfSignedCertificate(const Key& key,
175                                                            const AuthorizationSet& cert_params,
176                                                            bool fake_signature,
177                                                            keymaster_error_t* error) const = 0;
178 
179     virtual keymaster_error_t
180     UnwrapKey(const KeymasterKeyBlob& wrapped_key_blob, const KeymasterKeyBlob& wrapping_key_blob,
181               const AuthorizationSet& wrapping_key_params, const KeymasterKeyBlob& masking_key,
182               AuthorizationSet* wrapped_key_params, keymaster_key_format_t* wrapped_key_format,
183               KeymasterKeyBlob* wrapped_key_material) const = 0;
184 
185     /**
186      * Return the secure key storage for this context, or null if there is no available secure key
187      * storage.
188      */
secure_key_storage()189     virtual SecureKeyStorage* secure_key_storage() { return nullptr; }
190 
191     /**
192      * Checks that the data in |input_data| of size |input_data_size| matches the
193      * confirmation token given by |confirmation_token|.
194      *
195      * Note that |input_data| will already contain the prefixed message tag
196      * "confirmation token" (not including NUL byte) so all the implementation
197      * of this method needs to do is to calculate HMAC-SHA256 over |input_data|
198      * and compare it with |confirmation_token|. To do this the implementation
199      * needs access to the secret key shared with the ConfirmationUI TA.
200      *
201      * Returns KM_ERROR_OK if |input_data| matches |confirmation_token|,
202      * KM_ERROR_NO_USER_CONFIRMATION if it doesn't, and if memory allocation
203      * fails KM_ERROR_MEMORY_ALLOCATION_FAILED. If not implemented then
204      * KM_ERROR_UNIMPLEMENTED is returned.
205      */
206     virtual keymaster_error_t
CheckConfirmationToken(const uint8_t *,size_t,const uint8_t[kConfirmationTokenSize])207     CheckConfirmationToken(const uint8_t* /*input_data*/, size_t /*input_data_size*/,
208                            const uint8_t /*confirmation_token*/[kConfirmationTokenSize]) const {
209         return KM_ERROR_UNIMPLEMENTED;
210     }
211 
212     /**
213      * Return the remote provisioning context object, or null if remote provisioning is not
214      * supported.
215      */
GetRemoteProvisioningContext()216     virtual RemoteProvisioningContext* GetRemoteProvisioningContext() const { return nullptr; }
217 
218     /**
219      * Sets the vendor patchlevel (format YYYYMMDD) for the implementation. This value should
220      * be set by the HAL service at start of day.  A subsequent attempt to set a different
221      * value will return KM_ERROR_INVALID_ARGUMENT.
222      */
SetVendorPatchlevel(uint32_t)223     virtual keymaster_error_t SetVendorPatchlevel(uint32_t /* vendor_patchlevel */) {
224         return KM_ERROR_UNIMPLEMENTED;
225     }
226 
227     /**
228      * Sets the boot patchlevel (format YYYYMMDD) for the implementation. This value should be set
229      * by the bootloader.  A subsequent to set a different value will return
230      * KM_ERROR_INVALID_ARGUMENT;
231      */
SetBootPatchlevel(uint32_t)232     virtual keymaster_error_t SetBootPatchlevel(uint32_t /* boot_patchlevel */) {
233         return KM_ERROR_UNIMPLEMENTED;
234     }
235 
236     /**
237      * Returns the vendor patchlevel, as set by the HAL service using SetVendorPatchlevel.
238      */
GetVendorPatchlevel()239     virtual std::optional<uint32_t> GetVendorPatchlevel() const { return std::nullopt; }
240 
241     /**
242      * Returns the boot patchlevel. For hardware-based implementations this will be the value set by
243      * the bootloader. For software implementations this will be the information set by
244      * SetBootPatchLevel.
245      */
GetBootPatchlevel()246     virtual std::optional<uint32_t> GetBootPatchlevel() const { return std::nullopt; }
247 
248   private:
249     // Uncopyable.
250     KeymasterContext(const KeymasterContext&);
251     void operator=(const KeymasterContext&);
252 };
253 
254 }  // namespace keymaster
255 
256 #endif  // SYSTEM_KEYMASTER_KEYMASTER_CONTEXT_H_
257