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