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 /**
86 * @brief Get a call through the callback for each key with the same type
87 *
88 * @param type Key type.
89 * @param func Callback function to be called when a matched record is found.
90 * @param data User data to be passed to the callback function.
91 */
92 void bt_keys_foreach_type(enum bt_keys_type type, void (*func)(struct bt_keys *keys, void *data),
93 void *data);
94
95 /**
96 * @brief Get the key slot reference for an ID and address pair.
97 *
98 * If the pair already exists in the keys pool, no new reference is reserved
99 * and the same reference is returned directly.
100 * Otherwise try to reserve one for the new ID and address pair if there is
101 * a room for the new pair.
102 *
103 * @note If 'CONFIG_BT_KEYS_OVERWRITE_OLDEST' is defined and the keys pool is full,
104 * the function will try to find the oldest key that isn't in use with a connection.
105 * If a key with matched criteria is found, it will be overwritten with the new one.
106 *
107 * @param id Key identifier.
108 * @param addr Destination address.
109 *
110 * @return A valid reference pointer to the key slot if process succeeded.
111 * Otherwise, a NULL value is returned.
112 */
113 struct bt_keys *bt_keys_get_addr(uint8_t id, const bt_addr_le_t *addr);
114
115 /**
116 * @brief Get the key slot reference for an ID and address pair with a certain type.
117 *
118 * If the pair already exists in the keys pool, no new reference is reserved
119 * and the same reference is returned directly.
120 * Otherwise try to reserve one for the new ID and address pair if there is
121 * a room for the new pair and set the type.
122 *
123 * @param type Key type.
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_type(enum bt_keys_type type, uint8_t id, const bt_addr_le_t *addr);
131
132 /**
133 * @brief Find key identified by type, ID and address
134 *
135 * @param type Key type.
136 * @param id Key identifier.
137 * @param addr Destination address.
138 *
139 * @return A valid reference pointer to the key slot if it exists.
140 * Otherwise, a NULL value is returned.
141 */
142 struct bt_keys *bt_keys_find(enum bt_keys_type type, uint8_t id, const bt_addr_le_t *addr);
143
144 /**
145 * @brief Find key reference by trying to resolve an RPA using IRK
146 *
147 * @param id Key identifier.
148 * @param addr Destination address.
149 * @return A valid reference pointer to the key slot on success.
150 * Otherwise, a NULL value is returned.
151 */
152 struct bt_keys *bt_keys_find_irk(uint8_t id, const bt_addr_le_t *addr);
153
154 /**
155 * @brief Find a key by ID and address
156 *
157 * @param id Key identifier.
158 * @param addr Destination address.
159 * @return A valid reference pointer to the key slot if it exists.
160 * Otherwise, a NULL value is returned.
161 */
162 struct bt_keys *bt_keys_find_addr(uint8_t id, const bt_addr_le_t *addr);
163
164 /**
165 * @brief Add a type to a key
166 *
167 * @param keys Key reference.
168 * @param type Key type to be added.
169 */
170 void bt_keys_add_type(struct bt_keys *keys, enum bt_keys_type type);
171
172 /**
173 * @brief Clear a key contents
174 *
175 * @param keys Key reference to be cleared.
176 */
177 void bt_keys_clear(struct bt_keys *keys);
178
179 #if defined(CONFIG_BT_SETTINGS)
180
181 /**
182 * @brief Store key to persistent memory
183 *
184 * @param keys Key reference.
185 * @return 0 on success, non-zero error code otherwise
186 */
187 int bt_keys_store(struct bt_keys *keys);
188 #else
bt_keys_store(struct bt_keys * keys)189 static inline int bt_keys_store(struct bt_keys *keys)
190 {
191 return 0;
192 }
193 #endif
194
195 enum {
196 BT_LINK_KEY_AUTHENTICATED = BIT(0),
197 BT_LINK_KEY_DEBUG = BIT(1),
198 BT_LINK_KEY_SC = BIT(2),
199 };
200
201 struct bt_keys_link_key {
202 bt_addr_t addr;
203 uint8_t storage_start[0] __aligned(sizeof(void *));
204 uint8_t flags;
205 uint8_t val[16];
206 #if (defined(CONFIG_BT_KEYS_OVERWRITE_OLDEST))
207 uint32_t aging_counter;
208 #endif /* CONFIG_BT_KEYS_OVERWRITE_OLDEST */
209 };
210 #define BT_KEYS_LINK_KEY_STORAGE_LEN (sizeof(struct bt_keys_link_key) - \
211 offsetof(struct bt_keys_link_key, storage_start))
212
213 struct bt_keys_link_key *bt_keys_get_link_key(const bt_addr_t *addr);
214 struct bt_keys_link_key *bt_keys_find_link_key(const bt_addr_t *addr);
215 void bt_keys_link_key_clear(struct bt_keys_link_key *link_key);
216 void bt_keys_link_key_clear_addr(const bt_addr_t *addr);
217 void bt_keys_link_key_store(struct bt_keys_link_key *link_key);
218
219
220 /* This function is used to signal that the key has been used for paring */
221 /* It updates the aging counter and saves it to flash if configuration option */
222 /* BT_KEYS_SAVE_AGING_COUNTER_ON_PAIRING is enabled */
223 void bt_keys_update_usage(uint8_t id, const bt_addr_le_t *addr);
224 void bt_keys_link_key_update_usage(const bt_addr_t *addr);
225
226 void bt_keys_show_sniffer_info(struct bt_keys *keys, void *data);
227
228 /** @endcond */
229
