• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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