1 /* 2 * Copyright (C) 2017 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 package android.hardware.weaver@1.0; 17 18 /** 19 * Weaver provides secure storage of secret values that may only be read if the 20 * corresponding key has been presented. 21 * 22 * The storage must be secure as the device's user authentication and encryption 23 * relies on the security of these values. The cardinality of the domains of the 24 * key and value must be suitably large such that they cannot be easily guessed. 25 * 26 * Weaver is structured as an array of slots, each containing a key-value pair. 27 * Slots are uniquely identified by an ID in the range [0, `getConfig().slots`). 28 */ 29 interface IWeaver { 30 /** 31 * Retrieves the config information for this implementation of Weaver. 32 * 33 * The config is static i.e. every invocation returns the same information. 34 * 35 * @return status is OK if the config was successfuly obtained. 36 * @return config data for this implementation of Weaver if status is OK, 37 * otherwise undefined. 38 */ 39 getConfig() generates (WeaverStatus status, WeaverConfig config); 40 41 /** 42 * Overwrites the identified slot with the provided key and value. 43 * 44 * The new values are written regardless of the current state of the slot in 45 * order to remain idempotent. 46 * 47 * @param slotId of the slot to write to. 48 * @param key to write to the slot. 49 * @param value to write to slot. 50 * @return status is OK if the write was successfully completed. 51 */ 52 write(uint32_t slotId, vec<uint8_t> key, vec<uint8_t> value) 53 generates (WeaverStatus status); 54 55 /** 56 * Attempts to retrieve the value stored in the identified slot. 57 * 58 * The value is only returned if the provided key matches the key stored in 59 * the slot. The value is never returned if the wrong key is provided. 60 * 61 * Throttling must be used to limit the frequency of failed read attempts. 62 * The value is only returned when throttling is not active, even if the 63 * correct key is provided. If called when throttling is active, the time 64 * until the next attempt can be made is returned. 65 * 66 * @param slotId of the slot to read from. 67 * @param key that is stored in the slot. 68 * @return status is OK if the value was successfully read, INCORRECT_KEY if 69 * the key does not match the key in the slot, THROTTLE if 70 * throttling is active or FAILED if the read was unsuccessful for 71 * another reason. 72 * @return readResponse contains the value read and the timeout to wait 73 * before making the next request. If the status is OK, value is set 74 * to the value in the slot and timeout is 0. Otherwise, value is 75 * empty and timeout is set accordingly. 76 */ 77 read(uint32_t slotId, vec<uint8_t> key) 78 generates (WeaverReadStatus status, 79 WeaverReadResponse readResponse); 80 }; 81
