1 /* keys.h - Bluetooth key handling */
2 
3 /*
4  * Copyright (c) 2015-2016 Intel Corporation
5  *
6  * SPDX-License-Identifier: Apache-2.0
7  */
8 
9 #ifndef ZEPHYR_SUBSYS_BLUETOOTH_HOST_KEYS_H_
10 #define ZEPHYR_SUBSYS_BLUETOOTH_HOST_KEYS_H_
11 
12 #include <stdbool.h>
13 #include <stddef.h>
14 #include <stdint.h>
15 
16 #include <zephyr/bluetooth/addr.h>
17 #include <zephyr/bluetooth/bluetooth.h>
18 #include <zephyr/sys/util.h>
19 #include <zephyr/sys/util_macro.h>
20 #include <zephyr/toolchain.h>
21 
22 /** @cond INTERNAL_HIDDEN */
23 
24 enum bt_keys_type {
25 	BT_KEYS_PERIPH_LTK = BIT(0),
26 	BT_KEYS_IRK = BIT(1),
27 	BT_KEYS_LTK = BIT(2),
28 	BT_KEYS_LOCAL_CSRK = BIT(3),
29 	BT_KEYS_REMOTE_CSRK = BIT(4),
30 	BT_KEYS_LTK_P256 = BIT(5),
31 
32 	BT_KEYS_ALL = (BT_KEYS_PERIPH_LTK | BT_KEYS_IRK | BT_KEYS_LTK | BT_KEYS_LOCAL_CSRK |
33 		       BT_KEYS_REMOTE_CSRK | BT_KEYS_LTK_P256),
34 };
35 
36 enum {
37 	BT_KEYS_ID_PENDING_ADD = BIT(0),
38 	BT_KEYS_ID_PENDING_DEL = BIT(1),
39 	BT_KEYS_ID_ADDED = BIT(2),
40 };
41 
42 enum {
43 	BT_KEYS_AUTHENTICATED = BIT(0),
44 	BT_KEYS_DEBUG = BIT(1),
45 	/* Bit 2 and 3 might accidentally exist in old stored keys */
46 	BT_KEYS_SC = BIT(4),
47 	BT_KEYS_OOB = BIT(5),
48 };
49 
50 struct bt_ltk {
51 	uint8_t rand[8];
52 	uint8_t ediv[2];
53 	uint8_t val[16];
54 };
55 
56 struct bt_irk {
57 	uint8_t val[16];
58 	/* Cache for `bt_keys_find_irk`. Not reliable as "current RPA"! */
59 	bt_addr_t rpa;
60 };
61 
bt_irk_eq(struct bt_irk const * a,struct bt_irk const * b)62 static inline bool bt_irk_eq(struct bt_irk const *a, struct bt_irk const *b)
63 {
64 	return util_memeq(a->val, b->val, sizeof(a->val));
65 }
66 
67 struct bt_csrk {
68 	uint8_t val[16];
69 	uint32_t cnt;
70 };
71 
72 struct bt_keys {
73 	uint8_t id;
74 	bt_addr_le_t addr;
75 	uint8_t state;
76 	uint8_t storage_start[0] __aligned(sizeof(void *));
77 	uint8_t enc_size;
78 	uint8_t flags;
79 	uint16_t keys;
80 	struct bt_ltk ltk;
81 	struct bt_irk irk;
82 #if defined(CONFIG_BT_SIGNING)
83 	struct bt_csrk local_csrk;
84 	struct bt_csrk remote_csrk;
85 #endif /* BT_SIGNING */
86 #if !defined(CONFIG_BT_SMP_SC_PAIR_ONLY)
87 	struct bt_ltk periph_ltk;
88 #endif /* CONFIG_BT_SMP_SC_PAIR_ONLY */
89 #if (defined(CONFIG_BT_KEYS_OVERWRITE_OLDEST))
90 	uint32_t aging_counter;
91 #endif /* CONFIG_BT_KEYS_OVERWRITE_OLDEST */
92 };
93 
94 #define BT_KEYS_STORAGE_LEN (sizeof(struct bt_keys) - offsetof(struct bt_keys, storage_start))
95 
96 /** Clears all keys.
97  *
98  * Keys stored in settings are not cleared.
99  */
100 void bt_keys_reset(void);
101 
102 /**
103  * @brief Get a call through the callback for each key with the same type
104  *
105  * @param type Key type.
106  * @param func Callback function to be called when a matched record is found.
107  * @param data User data to be passed to the callback function.
108  */
109 void bt_keys_foreach_type(enum bt_keys_type type, void (*func)(struct bt_keys *keys, void *data),
110 			  void *data);
111 
112 /**
113  * @brief Get the key slot reference for an ID and address pair.
114  *
115  * If the pair already exists in the keys pool, no new reference is reserved
116  * and the same reference is returned directly.
117  * Otherwise try to reserve one for the new ID and address pair if there is
118  * a room for the new pair.
119  *
120  * @note If 'CONFIG_BT_KEYS_OVERWRITE_OLDEST' is defined and the keys pool is full,
121  *       the function will try to find the oldest key that isn't in use with a connection.
122  *       If a key with matched criteria is found, it will be overwritten with the new one.
123  *
124  * @param id Key identifier.
125  * @param addr Destination address.
126  *
127  * @return A valid reference pointer to the key slot if process succeeded.
128  *         Otherwise, a NULL value is returned.
129  */
130 struct bt_keys *bt_keys_get_addr(uint8_t id, const bt_addr_le_t *addr);
131 
132 /**
133  * @brief Get the key slot reference for an ID and address pair with a certain type.
134  *
135  * If the pair already exists in the keys pool, no new reference is reserved
136  * and the same reference is returned directly.
137  * Otherwise try to reserve one for the new ID and address pair if there is
138  * a room for the new pair and set the type.
139  *
140  * @param type Key type.
141  * @param id Key identifier.
142  * @param addr Destination address.
143  *
144  * @return A valid reference pointer to the key slot if process succeeded.
145  *         Otherwise, a NULL value is returned.
146  */
147 struct bt_keys *bt_keys_get_type(enum bt_keys_type type, uint8_t id, const bt_addr_le_t *addr);
148 
149 /**
150  * @brief Find key identified by type, ID and address
151  *
152  * @param type Key type.
153  * @param id Key identifier.
154  * @param addr Destination address.
155  *
156  * @return A valid reference pointer to the key slot if it exists.
157  *         Otherwise, a NULL value is returned.
158  */
159 struct bt_keys *bt_keys_find(enum bt_keys_type type, uint8_t id, const bt_addr_le_t *addr);
160 
161 /**
162  * @brief Find key reference by trying to resolve an RPA using IRK
163  *
164  * @param id Key identifier.
165  * @param addr Destination address.
166  * @return A valid reference pointer to the key slot on success.
167  *         Otherwise, a NULL value is returned.
168  */
169 struct bt_keys *bt_keys_find_irk(uint8_t id, const bt_addr_le_t *addr);
170 
171 /**
172  * @brief Find a key by ID and address
173  *
174  * @param id Key identifier.
175  * @param addr Destination address.
176  * @return A valid reference pointer to the key slot if it exists.
177  *         Otherwise, a NULL value is returned.
178  */
179 struct bt_keys *bt_keys_find_addr(uint8_t id, const bt_addr_le_t *addr);
180 
181 /**
182  * @brief Add a type to a key
183  *
184  * @param keys Key reference.
185  * @param type Key type to be added.
186  */
187 void bt_keys_add_type(struct bt_keys *keys, enum bt_keys_type type);
188 
189 /**
190  * @brief Clear a key contents
191  *
192  * @param keys Key reference to be cleared.
193  */
194 void bt_keys_clear(struct bt_keys *keys);
195 
196 #if defined(CONFIG_BT_SETTINGS)
197 
198 /**
199  * @brief Store key to persistent memory
200  *
201  * @param keys Key reference.
202  * @return 0 on success, non-zero error code otherwise
203  */
204 int bt_keys_store(struct bt_keys *keys);
205 #else
bt_keys_store(struct bt_keys * keys)206 static inline int bt_keys_store(struct bt_keys *keys)
207 {
208 	return 0;
209 }
210 #endif
211 
212 enum {
213 	BT_LINK_KEY_AUTHENTICATED = BIT(0),
214 	BT_LINK_KEY_DEBUG = BIT(1),
215 	BT_LINK_KEY_SC = BIT(2),
216 };
217 
218 struct bt_keys_link_key {
219 	bt_addr_t addr;
220 	uint8_t storage_start[0] __aligned(sizeof(void *));
221 	uint8_t flags;
222 	uint8_t val[16];
223 #if (defined(CONFIG_BT_KEYS_OVERWRITE_OLDEST))
224 	uint32_t aging_counter;
225 #endif /* CONFIG_BT_KEYS_OVERWRITE_OLDEST */
226 };
227 #define BT_KEYS_LINK_KEY_STORAGE_LEN                                                               \
228 	(sizeof(struct bt_keys_link_key) - offsetof(struct bt_keys_link_key, storage_start))
229 
230 struct bt_keys_link_key *bt_keys_get_link_key(const bt_addr_t *addr);
231 struct bt_keys_link_key *bt_keys_find_link_key(const bt_addr_t *addr);
232 void bt_keys_link_key_clear(struct bt_keys_link_key *link_key);
233 void bt_keys_link_key_clear_addr(const bt_addr_t *addr);
234 void bt_keys_link_key_store(struct bt_keys_link_key *link_key);
235 
236 /* This function is used to signal that the key has been used for paring */
237 /* It updates the aging counter and saves it to flash if configuration option */
238 /* BT_KEYS_SAVE_AGING_COUNTER_ON_PAIRING is enabled */
239 void bt_keys_update_usage(uint8_t id, const bt_addr_le_t *addr);
240 void bt_keys_link_key_update_usage(const bt_addr_t *addr);
241 
242 void bt_keys_show_sniffer_info(struct bt_keys *keys, void *data);
243 
244 /** @endcond */
245 
246 #endif /* ZEPHYR_SUBSYS_BLUETOOTH_HOST_KEYS_H_ */
247