1 /* 2 * Copyright 2014 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_KEY_BLOB_H_ 18 #define SYSTEM_KEYMASTER_KEY_BLOB_H_ 19 20 #include <cstddef> 21 22 #include <stdint.h> 23 24 #include <UniquePtr.h> 25 26 #include <keymaster/authorization_set.h> 27 #include <keymaster/google_keymaster_utils.h> 28 #include <keymaster/keymaster_defs.h> 29 #include <keymaster/serializable.h> 30 31 namespace keymaster { 32 33 /** 34 * This class represents a Keymaster key blob, including authorization sets and key material, both 35 * encrypted and unencrypted. It's primary purpose is to serialize and deserialize blob arrays, and 36 * provide access to the data in the blob. 37 */ 38 class KeyBlob : public Serializable { 39 public: 40 static const size_t NONCE_LENGTH = 12; 41 static const size_t TAG_LENGTH = 128 / 8; 42 43 /** 44 * Create a KeyBlob containing the specified authorization data and key material. The copy of 45 * \p key will be encrypted with key derived from \p master_key, using OCB authenticated 46 * encryption with \p nonce. It is critically important that nonces NEVER be reused. The most 47 * convenient way to accomplish that is to choose them randomly (assuming good randomness, that 48 * means there's a probability of reuse of one in 2^96). 49 * 50 * Note that this interface abuses \p keymaster_key_blob_t a bit. Normally, that struct is used 51 * to contain a full Keymaster blob, i.e. what KeyBlob is designed to create and manage. In 52 * this case we're using it to hold pure key material without any of the additional structure 53 * needed for a true Keymaster key. 54 * 55 * IMPORTANT: After constructing a KeyBlob, call error() to verify that the blob is usable. 56 */ 57 KeyBlob(const AuthorizationSet& enforced, const AuthorizationSet& unenforced, 58 const AuthorizationSet& hidden, const keymaster_key_blob_t& key, 59 const keymaster_key_blob_t& master_key, const uint8_t nonce[NONCE_LENGTH]); 60 61 /** 62 * Create a KeyBlob, reconstituting it from the encrypted material in \p encrypted_key, 63 * decrypted with key derived from \p master_key. The KeyBlob takes ownership of the \p 64 * keymaster_blob.key_material. 65 * 66 * Note, again, that \p master_key here is an abuse of \p keymaster_key_blob_t, since it 67 * is just key material, not a full Keymaster blob. 68 * 69 * IMPORTANT: After constructing a KeyBlob, call error() to verify that the blob is usable. 70 */ 71 KeyBlob(const keymaster_key_blob_t& keymaster_blob, const AuthorizationSet& hidden, 72 const keymaster_key_blob_t& master_key); 73 74 /** 75 * Create a KeyBlob, extracting the enforced and unenforced sets, but not decrypting the key, or 76 * even keeping it. The KeyBlob does *not* take ownership of key_blob. 77 * 78 * IMPORTANT: After constructing a KeyBlob, call error() to verify that the blob is usable. 79 */ 80 KeyBlob(const uint8_t* key_blob, size_t blob_size); 81 82 ~KeyBlob() { 83 memset_s(key_material_.get(), 0, key_material_length_); 84 // The following aren't sensitive, but clear them anyway. 85 memset_s(encrypted_key_material_.get(), 0, key_material_length_); 86 memset_s(nonce_.get(), 0, NONCE_LENGTH); 87 memset_s(tag_.get(), 0, TAG_LENGTH); 88 // AuthorizationSets clear themselves. 89 } 90 91 size_t SerializedSize() const; 92 uint8_t* Serialize(uint8_t* buf, const uint8_t* end) const; 93 bool Deserialize(const uint8_t** buf_ptr, const uint8_t* end); 94 95 /** 96 * Decrypt encrypted key. Call this after calling "Deserialize". Until it's called, 97 * key_material() will return a pointer to an uninitialized buffer. Sets error if there is a 98 * problem. 99 */ 100 void DecryptKey(const keymaster_key_blob_t& master_key); 101 102 /** 103 * Returns KM_ERROR_OK if all is well, or an appropriate error code if there is a problem. This 104 * error code should be checked after constructing or deserializing/decrypting, and if it does 105 * not return KM_ERROR_OK, then don't call any other methods. 106 */ 107 inline keymaster_error_t error() { return error_; } 108 109 inline const uint8_t* nonce() const { return nonce_.get(); } 110 inline const uint8_t* key_material() const { return key_material_.get(); } 111 inline const uint8_t* encrypted_key_material() const { return encrypted_key_material_.get(); } 112 inline size_t key_material_length() const { return key_material_length_; } 113 inline const uint8_t* tag() const { return tag_.get(); } 114 115 inline const AuthorizationSet& enforced() const { return enforced_; } 116 inline const AuthorizationSet& unenforced() const { return unenforced_; } 117 inline const AuthorizationSet& hidden() const { return hidden_; } 118 inline keymaster_algorithm_t algorithm() const { return algorithm_; } 119 inline size_t key_size_bits() const { return key_size_bits_; } 120 121 private: 122 void EncryptKey(const keymaster_key_blob_t& master_key); 123 bool ExtractKeyCharacteristics(); 124 125 /** 126 * Create an AES_OCB context initialized with a key derived using \p master_key and the 127 * authorizations. 128 */ 129 class AeCtx; 130 AeCtx* InitializeKeyWrappingContext(const keymaster_key_blob_t& master_key, 131 keymaster_error_t* error) const; 132 133 const uint8_t* BuildDerivationData(size_t* derivation_data_len) const; 134 135 keymaster_error_t error_; 136 UniquePtr<uint8_t[]> nonce_; 137 UniquePtr<uint8_t[]> key_material_; 138 UniquePtr<uint8_t[]> encrypted_key_material_; 139 UniquePtr<uint8_t[]> tag_; 140 size_t key_material_length_; 141 AuthorizationSet enforced_; 142 AuthorizationSet unenforced_; 143 AuthorizationSet hidden_; 144 keymaster_algorithm_t algorithm_; 145 uint32_t key_size_bits_; 146 }; 147 148 } // namespace keymaster 149 150 #endif // SYSTEM_KEYMASTER_KEY_BLOB_H_ 151