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 17 #ifndef ESE_APP_WEAVER_H_ 18 #define ESE_APP_WEAVER_H_ 1 19 20 #include "../../../../../libese/include/ese/ese.h" 21 #include "../../../../../libese/include/ese/log.h" 22 #include "../../../../../libese-sysdeps/include/ese/sysdeps.h" 23 24 #include "../../../../include/ese/app/result.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** 31 * EseWeaverSession carries the necessary start for interfacing 32 * with the methods below. 33 * 34 * Its usage follows a lifecycle like: 35 * 36 * EseAppResult res; 37 * EseWeaverSession session; 38 * ese_weaver_session_init(&session); 39 * res = ese_weaver_session_open(ese, &session); 40 * if (res != ESE_APP_RESULT_OK) { 41 * ... handle error (especially cooldown) ... 42 * } 43 * ... ese_weaver_* ... 44 * ese_weaver_session_close(&session); 45 * 46 */ 47 struct EseWeaverSession { 48 struct EseInterface *ese; 49 bool active; 50 uint8_t channel_id; 51 }; 52 53 /** The keys are 16 bytes */ 54 const uint8_t kEseWeaverKeySize = 16; 55 56 /** The values are 16 bytes */ 57 const uint8_t kEseWeaverValueSize = 16; 58 59 60 const int ESE_WEAVER_READ_WRONG_KEY = ese_make_app_result(0x6a, 0x85); 61 const int ESE_WEAVER_READ_TIMEOUT = ese_make_app_result(0x6a, 0x87); 62 63 /** 64 * Initializes a pre-allocated |session| for use. 65 */ 66 void ese_weaver_session_init(struct EseWeaverSession *session); 67 68 /** 69 * Configures a communication session with the Storage applet using a logical 70 * channel on an already open |ese| object. 71 * 72 * @returns ESE_APP_RESULT_OK on success. 73 */ 74 EseAppResult ese_weaver_session_open(struct EseInterface *ese, struct EseWeaverSession *session); 75 76 /** 77 * Shuts down the logical channel with the Storage applet and invalidates 78 * the |session| internal state. 79 * 80 * @returns ESE_APP_RESULT_OK on success. 81 */ 82 EseAppResult ese_weaver_session_close(struct EseWeaverSession *session); 83 84 /** 85 * Retreives the number of slots available. 86 * @returns ESE_APP_RESULT_OK if |numSlots| contains a valid value. 87 */ 88 EseAppResult ese_weaver_get_num_slots(struct EseWeaverSession *session, uint32_t *numSlots); 89 90 /** 91 * Writes a new key-value pair into the slot. 92 * 93 * |key| and |value| must be buffers of sizes |kEseWeaverKeySize| and 94 * |kEseWeaverValueSize| respectively. 95 * 96 * @returns ESE_APP_RESULT_OK on success. 97 */ 98 EseAppResult ese_weaver_write(struct EseWeaverSession *session, uint32_t slotId, 99 const uint8_t *key, const uint8_t *value); 100 101 102 /** 103 * Reads the value in the slot provided the correct key was passed. 104 * 105 * |key| and |value| must be buffers of sizes |kEseWeaverKeySize| and 106 * |kEseWeaverValueSize| respectively. 107 * 108 * @returns ESE_APP_RESULT_OK if |value| was filled with the value. 109 * ESE_WEAVER_READ_WRONG_KEY if |key| was wrong and |timeout| contains 110 * a valid timeout. 111 * ESE_WEAVER_READ_TIMEOUT if Weaver is in backoff mode and |timeout| 112 * contains a valid timeout. 113 */ 114 EseAppResult ese_weaver_read(struct EseWeaverSession *session, uint32_t slotId, 115 const uint8_t *key, uint8_t *value, uint32_t *timeout); 116 117 /** 118 * Erase the value of a slot whilst maintaining the same key. 119 * 120 * @returns ESE_APP_RESULT_OK on success. 121 */ 122 EseAppResult ese_weaver_erase_value(struct EseWeaverSession *session, uint32_t slotId); 123 124 #ifdef __cplusplus 125 } /* extern "C" */ 126 #endif 127 128 #endif /* ESE_APP_WEAVER_H_ */ 129