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