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 <assert.h> 21 22 #include <hardware/keymaster_defs.h> 23 #include <keymaster/keymaster_enforcement.h> 24 #include <keymaster/android_keymaster_utils.h> 25 26 namespace keymaster { 27 28 class AuthorizationSet; 29 class KeyFactory; 30 class OperationFactory; 31 template<typename BlobType> struct TKeymasterBlob; 32 typedef TKeymasterBlob<keymaster_key_blob_t> KeymasterKeyBlob; 33 class Key; 34 35 /** 36 * KeymasterContext provides a singleton abstract interface that encapsulates various 37 * environment-dependent elements of AndroidKeymaster. 38 * 39 * AndroidKeymaster runs in multiple contexts. Primarily: 40 * 41 * - In a trusted execution environment (TEE) as a "secure hardware" implementation. In this 42 * context keys are wrapped with an master key that never leaves the TEE, TEE-specific routines 43 * are used for random number generation, all AndroidKeymaster-enforced authorizations are 44 * considered hardware-enforced, and there's a bootloader-provided root of trust. 45 * 46 * - In the non-secure world as a software-only implementation. In this context keys are not 47 * encrypted (though they are integrity-checked) because there is no place to securely store a 48 * key, OpenSSL is used for random number generation, no AndroidKeymaster-enforced authorizations 49 * are considered hardware enforced and the root of trust is a static string. 50 * 51 * - In the non-secure world as a hybrid implementation fronting a less-capable hardware 52 * implementation. For example, a keymaster0 hardware implementation. In this context keys are 53 * not encrypted by AndroidKeymaster, but some may be opaque blobs provided by the backing 54 * hardware, but blobs that lack the extended authorization lists of keymaster1. In addition, 55 * keymaster0 lacks many features of keymaster1, including modes of operation related to the 56 * backing keymaster0 keys. AndroidKeymaster must extend the blobs to add authorization lists, 57 * and must provide the missing operation mode implementations in software, which means that 58 * authorization lists are partially hardware-enforced (the bits that are enforced by the 59 * underlying keymaster0) and partially software-enforced (the rest). OpenSSL is used for number 60 * generation and the root of trust is a static string. 61 * 62 * More contexts are possible. 63 */ 64 class KeymasterContext { 65 public: 66 KeymasterContext() {} 67 virtual ~KeymasterContext(){}; 68 69 /** 70 * Sets the system version as reported by the system *itself*. This is used to verify that the 71 * system believes itself to be running the same version that is reported by the bootloader, in 72 * hardware implementations. For SoftKeymasterDevice, this sets the version information used. 73 * 74 * If the specified values don't match the bootloader-provided values, this method must return 75 * KM_ERROR_INVALID_ARGUMENT; 76 */ 77 virtual keymaster_error_t SetSystemVersion(uint32_t os_version, uint32_t os_patchlevel) = 0; 78 79 /** 80 * Returns the system version. For hardware-based implementations this will be the value 81 * reported by the bootloader. For SoftKeymasterDevice it will be the verion information set by 82 * SetSystemVersion above. 83 */ 84 virtual void GetSystemVersion(uint32_t* os_version, uint32_t* os_patchlevel) const = 0; 85 86 virtual KeyFactory* GetKeyFactory(keymaster_algorithm_t algorithm) const = 0; 87 virtual OperationFactory* GetOperationFactory(keymaster_algorithm_t algorithm, 88 keymaster_purpose_t purpose) const = 0; 89 virtual keymaster_algorithm_t* GetSupportedAlgorithms(size_t* algorithms_count) const = 0; 90 91 /** 92 * UpgradeKeyBlob takes an existing blob, parses out key material and constructs a new blob with 93 * the current format and OS version info. 94 */ 95 virtual keymaster_error_t UpgradeKeyBlob(const KeymasterKeyBlob& key_to_upgrade, 96 const AuthorizationSet& upgrade_params, 97 KeymasterKeyBlob* upgraded_key) const = 0; 98 99 /** 100 * ParseKeyBlob takes a blob and extracts authorization sets and key material, returning an 101 * error if the blob fails integrity checking or decryption. Note that the returned key 102 * material may itself be an opaque blob usable only by secure hardware (in the hybrid case). 103 * 104 * This method is called by AndroidKeymaster. 105 */ 106 virtual keymaster_error_t ParseKeyBlob(const KeymasterKeyBlob& blob, 107 const AuthorizationSet& additional_params, 108 UniquePtr<Key>* key) const = 0; 109 110 /** 111 * Take whatever environment-specific action is appropriate (if any) to delete the specified 112 * key. 113 */ 114 virtual keymaster_error_t DeleteKey(const KeymasterKeyBlob& /* blob */) const { 115 return KM_ERROR_OK; 116 } 117 118 /** 119 * Take whatever environment-specific action is appropriate to delete all keys. 120 */ 121 virtual keymaster_error_t DeleteAllKeys() const { return KM_ERROR_OK; } 122 123 /** 124 * Adds entropy to the Cryptographic Pseudo Random Number Generator used to generate key 125 * material, and other cryptographic protocol elements. Note that if the underlying CPRNG 126 * tracks the size of its entropy pool, it should not assume that the provided data contributes 127 * any entropy, and it should also ensure that data provided through this interface cannot 128 * "poison" the CPRNG outputs, making them predictable. 129 */ 130 virtual keymaster_error_t AddRngEntropy(const uint8_t* buf, size_t length) const = 0; 131 132 /** 133 * Return the enforcement policy for this context, or null if no enforcement should be done. 134 */ 135 virtual KeymasterEnforcement* enforcement_policy() = 0; 136 137 virtual keymaster_error_t GenerateAttestation(const Key& key, 138 const AuthorizationSet& attest_params, 139 CertChainPtr* cert_chain) const = 0; 140 141 virtual keymaster_error_t 142 UnwrapKey(const KeymasterKeyBlob& wrapped_key_blob, const KeymasterKeyBlob& wrapping_key_blob, 143 const AuthorizationSet& wrapping_key_params, const KeymasterKeyBlob& masking_key, 144 AuthorizationSet* wrapped_key_params, keymaster_key_format_t* wrapped_key_format, 145 KeymasterKeyBlob* wrapped_key_material) const = 0; 146 147 private: 148 // Uncopyable. 149 KeymasterContext(const KeymasterContext&); 150 void operator=(const KeymasterContext&); 151 }; 152 153 } // namespace keymaster 154 155 #endif // SYSTEM_KEYMASTER_KEYMASTER_CONTEXT_H_ 156
