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