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