1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 #ifndef H_BLE_STORE_ 21 #define H_BLE_STORE_ 22 23 #include <stdint.h> 24 #include "nimble/ble.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #define BLE_STORE_OBJ_TYPE_OUR_SEC 1 31 #define BLE_STORE_OBJ_TYPE_PEER_SEC 2 32 #define BLE_STORE_OBJ_TYPE_CCCD 3 33 34 /** Failed to persist record; insufficient storage capacity. */ 35 #define BLE_STORE_EVENT_OVERFLOW 1 36 37 /** About to execute a procedure that may fail due to overflow. */ 38 #define BLE_STORE_EVENT_FULL 2 39 40 /** 41 * Used as a key for lookups of security material. This struct corresponds to 42 * the following store object types: 43 * o BLE_STORE_OBJ_TYPE_OUR_SEC 44 * o BLE_STORE_OBJ_TYPE_PEER_SEC 45 */ 46 struct ble_store_key_sec { 47 /** 48 * Key by peer identity address; 49 * peer_addr=BLE_ADDR_NONE means don't key off peer. 50 */ 51 ble_addr_t peer_addr; 52 53 /** Key by ediv; ediv_rand_present=0 means don't key off ediv. */ 54 uint16_t ediv; 55 56 /** Key by rand_num; ediv_rand_present=0 means don't key off rand_num. */ 57 uint64_t rand_num; 58 59 unsigned ediv_rand_present : 1; 60 61 /** Number of results to skip; 0 means retrieve the first match. */ 62 uint8_t idx; 63 }; 64 65 /** 66 * Represents stored security material. This struct corresponds to the 67 * following store object types: 68 * o BLE_STORE_OBJ_TYPE_OUR_SEC 69 * o BLE_STORE_OBJ_TYPE_PEER_SEC 70 */ 71 struct ble_store_value_sec { 72 ble_addr_t peer_addr; 73 74 uint8_t key_size; 75 uint16_t ediv; 76 uint64_t rand_num; 77 uint8_t ltk[16]; 78 uint8_t ltk_present : 1; 79 80 uint8_t irk[16]; 81 uint8_t irk_present : 1; 82 83 uint8_t csrk[16]; 84 uint8_t csrk_present : 1; 85 86 unsigned authenticated : 1; 87 uint8_t sc : 1; 88 }; 89 90 /** 91 * Used as a key for lookups of stored client characteristic configuration 92 * descriptors (CCCDs). This struct corresponds to the BLE_STORE_OBJ_TYPE_CCCD 93 * store object type. 94 */ 95 struct ble_store_key_cccd { 96 /** 97 * Key by peer identity address; 98 * peer_addr=BLE_ADDR_NONE means don't key off peer. 99 */ 100 ble_addr_t peer_addr; 101 102 /** 103 * Key by characteristic value handle; 104 * chr_val_handle=0 means don't key off characteristic handle. 105 */ 106 uint16_t chr_val_handle; 107 108 /** Number of results to skip; 0 means retrieve the first match. */ 109 uint8_t idx; 110 }; 111 112 /** 113 * Represents a stored client characteristic configuration descriptor (CCCD). 114 * This struct corresponds to the BLE_STORE_OBJ_TYPE_CCCD store object type. 115 */ 116 struct ble_store_value_cccd { 117 ble_addr_t peer_addr; 118 uint16_t chr_val_handle; 119 uint16_t flags; 120 unsigned value_changed : 1; 121 }; 122 123 /** 124 * Used as a key for store lookups. This union must be accompanied by an 125 * object type code to indicate which field is valid. 126 */ 127 union ble_store_key { 128 struct ble_store_key_sec sec; 129 struct ble_store_key_cccd cccd; 130 }; 131 132 /** 133 * Represents stored data. This union must be accompanied by an object type 134 * code to indicate which field is valid. 135 */ 136 union ble_store_value { 137 struct ble_store_value_sec sec; 138 struct ble_store_value_cccd cccd; 139 }; 140 141 struct ble_store_status_event { 142 /** 143 * The type of event being reported; one of the BLE_STORE_EVENT_TYPE_[...] 144 * codes. 145 */ 146 int event_code; 147 148 /** 149 * Additional data related to the event; the valid field is inferred from 150 * the obj_type,event_code pair. 151 */ 152 union { 153 /** 154 * Represents a write that failed due to storage exhaustion. Valid for 155 * the following event types: 156 * o BLE_STORE_EVENT_OVERFLOW 157 */ 158 struct { 159 /** The type of object that failed to be written. */ 160 int obj_type; 161 162 /** The object that failed to be written. */ 163 const union ble_store_value *value; 164 } overflow; 165 166 /** 167 * Represents the possibility that a scheduled write will fail due to 168 * storage exhaustion. Valid for the following event types: 169 * o BLE_STORE_EVENT_FULL 170 */ 171 struct { 172 /** The type of object that may fail to be written. */ 173 int obj_type; 174 175 /** The handle of the connection which prompted the write. */ 176 uint16_t conn_handle; 177 } full; 178 }; 179 }; 180 181 /** 182 * Searches the store for an object matching the specified criteria. If a 183 * match is found, it is read from the store and the dst parameter is populated 184 * with the retrieved object. 185 * 186 * @param obj_type The type of object to search for; one of the 187 * BLE_STORE_OBJ_TYPE_[...] codes. 188 * @param key Specifies properties of the object to search 189 * for. An object is retrieved if it matches 190 * these criteria. 191 * @param dst On success, this is populated with the 192 * retrieved object. 193 * 194 * @return 0 if an object was successfully retreived; 195 * BLE_HS_ENOENT if no matching object was found; 196 * Other nonzero on error. 197 */ 198 typedef int ble_store_read_fn(int obj_type, const union ble_store_key *key, 199 union ble_store_value *dst); 200 201 /** 202 * Writes the specified object to the store. If an object with the same 203 * identity is already in the store, it is replaced. If the store lacks 204 * sufficient capacity to write the object, this function may remove previously 205 * stored values to make room. 206 * 207 * @param obj_type The type of object being written; one of the 208 * BLE_STORE_OBJ_TYPE_[...] codes. 209 * @param val The object to persist. 210 * 211 * @return 0 if the object was successfully written; 212 * Other nonzero on error. 213 */ 214 typedef int ble_store_write_fn(int obj_type, const union ble_store_value *val); 215 216 /** 217 * Searches the store for the first object matching the specified criteria. If 218 * a match is found, it is deleted from the store. 219 * 220 * @param obj_type The type of object to delete; one of the 221 * BLE_STORE_OBJ_TYPE_[...] codes. 222 * @param key Specifies properties of the object to search 223 * for. An object is deleted if it matches 224 * these criteria. 225 * @return 0 if an object was successfully retrieved; 226 * BLE_HS_ENOENT if no matching object was found; 227 * Other nonzero on error. 228 */ 229 typedef int ble_store_delete_fn(int obj_type, const union ble_store_key *key); 230 231 /** 232 * Indicates an inability to perform a store operation. This callback should 233 * do one of two things: 234 * o Address the problem and return 0, indicating that the store operation 235 * should proceed. 236 * o Return nonzero to indicate that the store operation should be aborted. 237 * 238 * @param event Describes the store event being reported. 239 * @param arg Optional user argument. 240 * 241 * @return 0 if the store operation should proceed; 242 * nonzero if the store operation should be 243 * aborted. 244 */ 245 typedef int ble_store_status_fn(struct ble_store_status_event *event, 246 void *arg); 247 248 typedef int ble_store_flush_fn(void); 249 250 int ble_store_read(int obj_type, const union ble_store_key *key, 251 union ble_store_value *val); 252 int ble_store_write(int obj_type, const union ble_store_value *val); 253 int ble_store_delete(int obj_type, const union ble_store_key *key); 254 int ble_store_overflow_event(int obj_type, const union ble_store_value *value); 255 int ble_store_full_event(int obj_type, uint16_t conn_handle); 256 257 int ble_store_read_our_sec(const struct ble_store_key_sec *key_sec, 258 struct ble_store_value_sec *value_sec); 259 int ble_store_write_our_sec(const struct ble_store_value_sec *value_sec); 260 int ble_store_delete_our_sec(const struct ble_store_key_sec *key_sec); 261 int ble_store_read_peer_sec(const struct ble_store_key_sec *key_sec, 262 struct ble_store_value_sec *value_sec); 263 int ble_store_write_peer_sec(const struct ble_store_value_sec *value_sec); 264 int ble_store_delete_peer_sec(const struct ble_store_key_sec *key_sec); 265 266 int ble_store_read_cccd(const struct ble_store_key_cccd *key, 267 struct ble_store_value_cccd *out_value); 268 int ble_store_write_cccd(const struct ble_store_value_cccd *value); 269 int ble_store_delete_cccd(const struct ble_store_key_cccd *key); 270 271 void ble_store_key_from_value_sec(struct ble_store_key_sec *out_key, 272 const struct ble_store_value_sec *value); 273 void ble_store_key_from_value_cccd(struct ble_store_key_cccd *out_key, 274 const struct ble_store_value_cccd *value); 275 276 void ble_store_key_from_value(int obj_type, 277 union ble_store_key *out_key, 278 const union ble_store_value *value); 279 280 typedef int ble_store_iterator_fn(int obj_type, 281 union ble_store_value *val, 282 void *cookie); 283 284 int ble_store_iterate(int obj_type, 285 ble_store_iterator_fn *callback, 286 void *cookie); 287 288 int ble_store_clear(void); 289 290 /*** Utility functions. */ 291 292 int ble_store_util_bonded_peers(ble_addr_t *out_peer_id_addrs, 293 int *out_num_peers, 294 int max_peers); 295 int ble_store_util_delete_all(int type, const union ble_store_key *key); 296 int ble_store_util_delete_peer(const ble_addr_t *peer_id_addr); 297 int ble_store_util_delete_oldest_peer(ble_addr_t *peer_id_addr); 298 int ble_store_util_get_peer_by_index(int idex, ble_addr_t *peer_id_addrs); 299 300 int ble_store_util_count(int type, int *out_count); 301 int ble_store_util_status_rr(struct ble_store_status_event *event, void *arg); 302 int ble_store_flush(void); 303 304 #ifdef __cplusplus 305 } 306 #endif 307 308 #endif 309