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 25 namespace keymaster { 26 27 class AuthorizationSet; 28 class KeyFactory; 29 class OperationFactory; 30 struct KeymasterKeyBlob; 31 32 /** 33 * KeymasterContext provides a singleton abstract interface that encapsulates various 34 * environment-dependent elements of AndroidKeymaster. 35 * 36 * AndroidKeymaster runs in multiple contexts. Primarily: 37 * 38 * - In a trusted execution environment (TEE) as a "secure hardware" implementation. In this 39 * context keys are wrapped with an master key that never leaves the TEE, TEE-specific routines 40 * are used for random number generation, all AndroidKeymaster-enforced authorizations are 41 * considered hardware-enforced, and there's a bootloader-provided root of trust. 42 * 43 * - In the non-secure world as a software-only implementation. In this context keys are not 44 * encrypted (though they are integrity-checked) because there is no place to securely store a 45 * key, OpenSSL is used for random number generation, no AndroidKeymaster-enforced authorizations 46 * are considered hardware enforced and the root of trust is a static string. 47 * 48 * - In the non-secure world as a hybrid implementation fronting a less-capable hardware 49 * implementation. For example, a keymaster0 hardware implementation. In this context keys are 50 * not encrypted by AndroidKeymaster, but some may be opaque blobs provided by the backing 51 * hardware, but blobs that lack the extended authorization lists of keymaster1. In addition, 52 * keymaster0 lacks many features of keymaster1, including modes of operation related to the 53 * backing keymaster0 keys. AndroidKeymaster must extend the blobs to add authorization lists, 54 * and must provide the missing operation mode implementations in software, which means that 55 * authorization lists are partially hardware-enforced (the bits that are enforced by the 56 * underlying keymaster0) and partially software-enforced (the rest). OpenSSL is used for number 57 * generation and the root of trust is a static string. 58 * 59 * More contexts are possible. 60 */ 61 class KeymasterContext { 62 public: 63 KeymasterContext() {} 64 virtual ~KeymasterContext(){}; 65 66 virtual KeyFactory* GetKeyFactory(keymaster_algorithm_t algorithm) const = 0; 67 virtual OperationFactory* GetOperationFactory(keymaster_algorithm_t algorithm, 68 keymaster_purpose_t purpose) const = 0; 69 virtual keymaster_algorithm_t* GetSupportedAlgorithms(size_t* algorithms_count) const = 0; 70 71 /** 72 * CreateKeyBlob takes authorization sets and key material and produces a key blob and hardware 73 * and software authorization lists ready to be returned to the AndroidKeymaster client 74 * (Keystore, generally). The blob is integrity-checked and may be encrypted, depending on the 75 * needs of the context. 76 * 77 * This method is generally called only by KeyFactory subclassses. 78 */ 79 virtual keymaster_error_t CreateKeyBlob(const AuthorizationSet& key_description, 80 keymaster_key_origin_t origin, 81 const KeymasterKeyBlob& key_material, 82 KeymasterKeyBlob* blob, AuthorizationSet* hw_enforced, 83 AuthorizationSet* sw_enforced) const = 0; 84 85 /** 86 * ParseKeyBlob takes a blob and extracts authorization sets and key material, returning an 87 * error if the blob fails integrity checking or decryption. Note that the returned key 88 * material may itself be an opaque blob usable only by secure hardware (in the hybrid case). 89 * 90 * This method is called by AndroidKeymaster. 91 */ 92 virtual keymaster_error_t ParseKeyBlob(const KeymasterKeyBlob& blob, 93 const AuthorizationSet& additional_params, 94 KeymasterKeyBlob* key_material, 95 AuthorizationSet* hw_enforced, 96 AuthorizationSet* sw_enforced) const = 0; 97 98 /** 99 * Take whatever environment-specific action is appropriate (if any) to delete the specified 100 * key. 101 */ 102 virtual keymaster_error_t DeleteKey(const KeymasterKeyBlob& /* blob */) const { 103 return KM_ERROR_OK; 104 } 105 106 /** 107 * Take whatever environment-specific action is appropriate to delete all keys. 108 */ 109 virtual keymaster_error_t DeleteAllKeys() const { return KM_ERROR_OK; } 110 111 /** 112 * Adds entropy to the Cryptographic Pseudo Random Number Generator used to generate key 113 * material, and other cryptographic protocol elements. Note that if the underlying CPRNG 114 * tracks the size of its entropy pool, it should not assume that the provided data contributes 115 * any entropy, and it should also ensure that data provided through this interface cannot 116 * "poison" the CPRNG outputs, making them predictable. 117 */ 118 virtual keymaster_error_t AddRngEntropy(const uint8_t* buf, size_t length) const = 0; 119 120 /** 121 * Generates \p length random bytes, placing them in \p buf. 122 */ 123 virtual keymaster_error_t GenerateRandom(uint8_t* buf, size_t length) const = 0; 124 125 /** 126 * Return the enforcement policy for this context, or null if no enforcement should be done. 127 */ 128 virtual KeymasterEnforcement* enforcement_policy() = 0; 129 130 private: 131 // Uncopyable. 132 KeymasterContext(const KeymasterContext&); 133 void operator=(const KeymasterContext&); 134 }; 135 136 } // namespace keymaster 137 138 #endif // SYSTEM_KEYMASTER_KEYMASTER_CONTEXT_H_ 139
