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 #pragma once 18 19 #include <hardware/keymaster_defs.h> 20 21 #include <keymaster/android_keymaster_utils.h> 22 #include <keymaster/authorization_set.h> 23 #include <keymaster/keymaster_utils.h> 24 25 namespace keymaster { 26 27 class Buffer; 28 class RandomSource; 29 30 // Define the formats this code knows about. Note that "format" here implies both structure and KEK 31 // derivation and encryption algorithm, though the KEK derivation and encryption is performed prior 32 // to serialization. 33 enum AuthEncryptedBlobFormat : uint8_t { 34 AES_OCB = 0, 35 AES_GCM_WITH_SW_ENFORCED = 1, 36 AES_GCM_WITH_SECURE_DELETION = 2, 37 AES_GCM_WITH_SW_ENFORCED_VERSIONED = 3, 38 AES_GCM_WITH_SECURE_DELETION_VERSIONED = 4, 39 }; 40 41 /** 42 * SecureDeletionData provides additional secrets that are mixed into key encryption key derivation 43 * for AES_GCM_WITH_SECURE_DELETION key blobs. Loss of these secrets ensures that the blobs 44 * encrypt3ed with keys derived from them cannot be decrypted. 45 */ 46 struct SecureDeletionData { 47 /** 48 * The factory reset secret is intended to be erased and randomly re-generated on every factory 49 * reset. It should provide a large amount of entropy, 256 bits is recommended. 50 */ 51 Buffer factory_reset_secret; 52 53 /** 54 * The secure deletion secret is intended to be randomly-generated for every key that requires 55 * secure deletion (e.g. KM_TAG_ROLLBACK_RESISTANT and KM_TAG_USAGE_COUNT_LIMIT) and when the 56 * key is deleted the secure deletion secret should be securely erased. It should provide a 57 * significant amount of entropy, but this must be balanced against size, since there may be 58 * many such secrets that need to be stored. 128 bits is recommended. 59 */ 60 Buffer secure_deletion_secret; 61 62 /** 63 * `key_slot` is the secure storage slot in which the `secure_deletion_secret` is found, if any. 64 * 0 if unused. 65 */ 66 uint32_t key_slot = 0; 67 }; 68 69 struct EncryptedKey { 70 AuthEncryptedBlobFormat format; 71 KeymasterKeyBlob ciphertext; 72 Buffer nonce; 73 Buffer tag; 74 uint32_t kdf_version; 75 int32_t addl_info; 76 }; 77 78 struct DeserializedKey { 79 EncryptedKey encrypted_key; 80 AuthorizationSet hw_enforced; 81 AuthorizationSet sw_enforced; 82 uint32_t key_slot; 83 }; 84 85 /** 86 * Encrypt the provided plaintext with format `format`, using the provided authorization lists and 87 * master_key to derive the key encryption key. 88 * 89 * The `secure_deletion_data` argument is used for format AES_GCM_WITH_SECURE_DELETION. It contains 90 * additional high-entropy secrets used in key encryption key derivation which are erased on factory 91 * reset and key deletion, respectively. 92 */ 93 KmErrorOr<EncryptedKey> 94 EncryptKey(const KeymasterKeyBlob& plaintext, AuthEncryptedBlobFormat format, 95 const AuthorizationSet& hw_enforced, const AuthorizationSet& sw_enforced, 96 const AuthorizationSet& hidden, const SecureDeletionData& secure_deletion_data, 97 const KeymasterKeyBlob& master_key, const RandomSource& random); 98 99 /** 100 * Serialize `encrypted_key` (which contains necessary nonce & tag information), along with the 101 * associated authorization data into a blob. 102 * 103 * The `key_slot` is used for format AES_GCM_WITH_SECURE_DELETION. It indicates the slot in the 104 * secure deletion file at which a secure deletion key for this encrypted key may be found. It 105 * should be set to zero when unused. 106 */ 107 KmErrorOr<KeymasterKeyBlob> SerializeAuthEncryptedBlob(const EncryptedKey& encrypted_key, 108 const AuthorizationSet& hw_enforced, 109 const AuthorizationSet& sw_enforced, 110 uint32_t key_slot); 111 112 /** 113 * Deserialize a blob, retrieving the key ciphertext, decryption parameters and associated 114 * authorization lists. 115 */ 116 KmErrorOr<DeserializedKey> DeserializeAuthEncryptedBlob(const KeymasterKeyBlob& key_blob); 117 118 /** 119 * Decrypt key material from the Deserialized data in `key'. 120 */ 121 KmErrorOr<KeymasterKeyBlob> DecryptKey(const DeserializedKey& key, const AuthorizationSet& hidden, 122 const SecureDeletionData& secure_deletion_data, 123 const KeymasterKeyBlob& master_key); 124 125 bool requiresSecureDeletion(const AuthEncryptedBlobFormat& fmt); 126 127 bool isVersionedFormat(const AuthEncryptedBlobFormat& fmt); 128 129 } // namespace keymaster 130