1 /* 2 * Copyright (C) 2021 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 <optional> 20 21 #include <keymaster/key_blob_utils/auth_encrypted_key_blob.h> 22 23 namespace keymaster { 24 25 class RandomSource; 26 27 /** 28 * SecureDeletionSecretStorage stores secure deletion secrets for KeyMint keys. These secrets are 29 * mixed into the key encryption key derivation process, so once the secure deletion secrets 30 * associated with a key blob are destroyed, the key blob can never be decrypted again. 31 */ 32 class SecureDeletionSecretStorage { 33 public: SecureDeletionSecretStorage(const RandomSource & random)34 explicit SecureDeletionSecretStorage(const RandomSource& random) : random_(random) {} ~SecureDeletionSecretStorage()35 virtual ~SecureDeletionSecretStorage() {} 36 37 /** 38 * Create secure deletion data for a new key, and return it. 39 * 40 * If `secure_deletion` is true, a random key is generated and stored in an unused key slot, and 41 * the key slot is returned. If no unused key slot exists or if `secure_deletion` is false, the 42 * returned `key_slot` is zero, indicating that secure deletion is not available for the new 43 * key. 44 * 45 * If `secure_deletion` and `is_upgrade` are both true, the random key will be stored in an 46 * "upgrade-only" slot, if no normal slots are available. The upgrade-only slots reduce the 47 * probability that upgrading blobs can lose secure deletion. 48 * 49 * Whether or not secure deletion is requested, this method must read secure storage to obtain 50 * the factory reset secret. This read may fail for one of three reasons: 51 * 52 * 1. Secure storage is not yet available. In this case the return value is std::nullopt. 53 * 54 * 2. Secure storage is available, but the secure deletion data file doesn't exist. In this 55 * case the method creates the file, generates and stores the factory reset secret (and 56 * possibly secure deletion secret, if requested), and returns a populated result. 57 * 58 * 3. Secure storage is not available but was available previously. In this case the method 59 * blocks until secure storage is available, possibly forever, then processes the request 60 * and returns a populated result. 61 * 62 * @retval is empty if no secure deletion data (factory reset or per-key) is available. 63 * 64 * If the return value is not empty, the secureDeletionData field contains data that can 65 * be used for key derivation. If the keySlot field is 0, the key does not have secure 66 * deletion support. 67 */ 68 virtual std::optional<SecureDeletionData> CreateDataForNewKey(bool secure_deletion, 69 bool is_upgrade) const = 0; 70 71 /** 72 * Get the secure deletion data for a key. 73 * 74 * If the `key_slot` argument is non-zero, this method will retrieve data from the specified 75 * slot and return it in the secure_deletion_secret field, otherwise the `key_slot` field will 76 * be an empty buffer. Whether `key_slot` is zero or not, this method will populate the 77 * factory_reset_secret field. 78 * 79 * This method blocks until secure storage can be read. Possibly forever. 80 */ 81 virtual SecureDeletionData GetDataForKey(uint32_t key_slot) const = 0; 82 83 /** 84 * Delete the secure deletion data in a key slot. 85 */ 86 virtual void DeleteKey(uint32_t key_slot) const = 0; 87 88 /** 89 * Deletes the secure deletion data file, deleting all secure deletion secrets and the factory 90 * reset secret. 91 */ 92 virtual void DeleteAllKeys() const = 0; 93 94 protected: 95 const RandomSource& random_; 96 }; 97 98 } // namespace keymaster 99