10a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden/* 20a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Copyright 2014 The Android Open Source Project 30a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * 40a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Licensed under the Apache License, Version 2.0 (the "License"); 50a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * you may not use this file except in compliance with the License. 60a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * You may obtain a copy of the License at 70a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * 80a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * http://www.apache.org/licenses/LICENSE-2.0 90a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * 100a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Unless required by applicable law or agreed to in writing, software 110a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * distributed under the License is distributed on an "AS IS" BASIS, 120a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 130a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * See the License for the specific language governing permissions and 140a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * limitations under the License. 150a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden */ 160a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 170a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#ifndef SYSTEM_KEYMASTER_KEY_BLOB_H_ 180a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#define SYSTEM_KEYMASTER_KEY_BLOB_H_ 190a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 200a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#include <cstddef> 210a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 220a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#include <stdint.h> 230a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 240a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#include <UniquePtr.h> 250a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 260a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#include <keymaster/authorization_set.h> 270a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#include <keymaster/google_keymaster_utils.h> 280a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#include <keymaster/keymaster_defs.h> 290a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#include <keymaster/serializable.h> 300a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 310a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willdennamespace keymaster { 320a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 330a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden/** 340a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * This class represents a Keymaster key blob, including authorization sets and key material, both 350a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * encrypted and unencrypted. It's primary purpose is to serialize and deserialize blob arrays, and 360a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * provide access to the data in the blob. 370a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden */ 380a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willdenclass KeyBlob : public Serializable { 390a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden public: 400a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden static const size_t NONCE_LENGTH = 12; 410a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden static const size_t TAG_LENGTH = 128 / 8; 420a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 430a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden /** 440a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Create a KeyBlob containing the specified authorization data and key material. The copy of 450a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * \p key will be encrypted with key derived from \p master_key, using OCB authenticated 460a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * encryption with \p nonce. It is critically important that nonces NEVER be reused. The most 470a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * convenient way to accomplish that is to choose them randomly (assuming good randomness, that 480a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * means there's a probability of reuse of one in 2^96). 490a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * 500a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Note that this interface abuses \p keymaster_key_blob_t a bit. Normally, that struct is used 510a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * to contain a full Keymaster blob, i.e. what KeyBlob is designed to create and manage. In 520a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * this case we're using it to hold pure key material without any of the additional structure 530a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * needed for a true Keymaster key. 540a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * 550a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * IMPORTANT: After constructing a KeyBlob, call error() to verify that the blob is usable. 560a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden */ 570a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden KeyBlob(const AuthorizationSet& enforced, const AuthorizationSet& unenforced, 580a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden const AuthorizationSet& hidden, const keymaster_key_blob_t& key, 590a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden const keymaster_key_blob_t& master_key, const uint8_t nonce[NONCE_LENGTH]); 600a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 610a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden /** 620a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Create a KeyBlob, reconstituting it from the encrypted material in \p encrypted_key, 630a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * decrypted with key derived from \p master_key. The KeyBlob takes ownership of the \p 640a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * keymaster_blob.key_material. 650a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * 660a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Note, again, that \p master_key here is an abuse of \p keymaster_key_blob_t, since it 670a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * is just key material, not a full Keymaster blob. 680a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * 690a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * IMPORTANT: After constructing a KeyBlob, call error() to verify that the blob is usable. 700a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden */ 710a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden KeyBlob(const keymaster_key_blob_t& keymaster_blob, const AuthorizationSet& hidden, 720a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden const keymaster_key_blob_t& master_key); 730a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 740a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden /** 750a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Create a KeyBlob, extracting the enforced and unenforced sets, but not decrypting the key, or 760a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * even keeping it. The KeyBlob does *not* take ownership of key_blob. 770a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * 780a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * IMPORTANT: After constructing a KeyBlob, call error() to verify that the blob is usable. 790a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden */ 800a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden KeyBlob(const uint8_t* key_blob, size_t blob_size); 810a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 820a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden ~KeyBlob() { 830a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden memset_s(key_material_.get(), 0, key_material_length_); 840a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden // The following aren't sensitive, but clear them anyway. 850a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden memset_s(encrypted_key_material_.get(), 0, key_material_length_); 860a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden memset_s(nonce_.get(), 0, NONCE_LENGTH); 870a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden memset_s(tag_.get(), 0, TAG_LENGTH); 880a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden // AuthorizationSets clear themselves. 890a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden } 900a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 910a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden size_t SerializedSize() const; 920a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden uint8_t* Serialize(uint8_t* buf, const uint8_t* end) const; 930a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden bool Deserialize(const uint8_t** buf_ptr, const uint8_t* end); 940a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 950a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden /** 960a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Decrypt encrypted key. Call this after calling "Deserialize". Until it's called, 970a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * key_material() will return a pointer to an uninitialized buffer. Sets error if there is a 980a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * problem. 990a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden */ 1000a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden void DecryptKey(const keymaster_key_blob_t& master_key); 1010a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 1020a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden /** 1030a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Returns KM_ERROR_OK if all is well, or an appropriate error code if there is a problem. This 1040a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * error code should be checked after constructing or deserializing/decrypting, and if it does 1050a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * not return KM_ERROR_OK, then don't call any other methods. 1060a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden */ 1070a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline keymaster_error_t error() { return error_; } 1080a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 1090a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline const uint8_t* nonce() const { return nonce_.get(); } 1100a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline const uint8_t* key_material() const { return key_material_.get(); } 1110a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline const uint8_t* encrypted_key_material() const { return encrypted_key_material_.get(); } 1120a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline size_t key_material_length() const { return key_material_length_; } 1130a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline const uint8_t* tag() const { return tag_.get(); } 1140a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 1150a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline const AuthorizationSet& enforced() const { return enforced_; } 1160a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline const AuthorizationSet& unenforced() const { return unenforced_; } 1170a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline const AuthorizationSet& hidden() const { return hidden_; } 1180a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline keymaster_algorithm_t algorithm() const { return algorithm_; } 1190a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden inline size_t key_size_bits() const { return key_size_bits_; } 1200a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 1210a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden private: 1220a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden void EncryptKey(const keymaster_key_blob_t& master_key); 1230a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden bool ExtractKeyCharacteristics(); 1240a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 1250a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden /** 1260a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * Create an AES_OCB context initialized with a key derived using \p master_key and the 1270a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden * authorizations. 1280a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden */ 1290a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden class AeCtx; 1300a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden AeCtx* InitializeKeyWrappingContext(const keymaster_key_blob_t& master_key, 1310a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden keymaster_error_t* error) const; 1320a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 1330a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden const uint8_t* BuildDerivationData(size_t* derivation_data_len) const; 1340a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 1350a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden keymaster_error_t error_; 1360a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden UniquePtr<uint8_t[]> nonce_; 1370a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden UniquePtr<uint8_t[]> key_material_; 1380a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden UniquePtr<uint8_t[]> encrypted_key_material_; 1390a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden UniquePtr<uint8_t[]> tag_; 1400a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden size_t key_material_length_; 1410a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden AuthorizationSet enforced_; 1420a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden AuthorizationSet unenforced_; 1430a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden AuthorizationSet hidden_; 1440a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden keymaster_algorithm_t algorithm_; 1450a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden uint32_t key_size_bits_; 1460a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden}; 1470a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 1480a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden} // namespace keymaster 1490a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden 1500a4df7e3a83a59e4a5abc3f605d7d7e9f636c682Shawn Willden#endif // SYSTEM_KEYMASTER_KEY_BLOB_H_ 151