Line data Source code
1 0 : /*
2 : * Copyright (c) 2024 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef WIFI_CREDENTIALS_H__
8 : #define WIFI_CREDENTIALS_H__
9 :
10 : #include <zephyr/types.h>
11 : #include <zephyr/net/wifi.h>
12 : #include <zephyr/kernel.h>
13 :
14 : #ifdef __cplusplus
15 : extern "C" {
16 : #endif
17 :
18 : /**
19 : * @brief Library that provides a way to store and load Wi-Fi credentials.
20 : * @defgroup wifi_credentials Wi-Fi credentials library
21 : * @ingroup networking
22 : * @since 4.0
23 : * @version 0.1.0
24 : * @{
25 : */
26 :
27 :
28 : /* this entry contains a BSSID */
29 0 : #define WIFI_CREDENTIALS_FLAG_BSSID BIT(0)
30 : /* this entry is to be preferred over others */
31 0 : #define WIFI_CREDENTIALS_FLAG_FAVORITE BIT(1)
32 : /* this entry can use the 2.4 GHz band */
33 0 : #define WIFI_CREDENTIALS_FLAG_2_4GHz BIT(2)
34 : /* this entry can use the 5 GHz band */
35 0 : #define WIFI_CREDENTIALS_FLAG_5GHz BIT(3)
36 : /* this entry can use the 6 GHz band */
37 0 : #define WIFI_CREDENTIALS_FLAG_6GHz BIT(4)
38 : /* this entry requires management frame protection */
39 0 : #define WIFI_CREDENTIALS_FLAG_MFP_REQUIRED BIT(5)
40 : /* this entry disables management frame protection */
41 0 : #define WIFI_CREDENTIALS_FLAG_MFP_DISABLED BIT(6)
42 : /* this entry has anonymous identity configured */
43 0 : #define WIFI_CREDENTIALS_FLAG_ANONYMOUS_IDENTITY BIT(7)
44 : /* this entry has key password configured */
45 0 : #define WIFI_CREDENTIALS_FLAG_KEY_PASSWORD BIT(8)
46 :
47 : /* Maximum length of the password */
48 0 : #define WIFI_CREDENTIALS_MAX_PASSWORD_LEN \
49 : MAX(WIFI_PSK_MAX_LEN, CONFIG_WIFI_CREDENTIALS_SAE_PASSWORD_LENGTH)
50 :
51 : /**
52 : * @brief Wi-Fi credentials entry header
53 : * @note Every settings entry starts with this header.
54 : * Depending on the `type` field, the header can be casted to a larger type.
55 : * In addition to SSID (usually a string) and BSSID (a MAC address),
56 : * a `flags` field can be used to control some detail settings.
57 : *
58 : */
59 1 : struct wifi_credentials_header {
60 : /** Wi-Fi security type */
61 1 : enum wifi_security_type type;
62 :
63 : /** SSID (Service Set Identifier) */
64 1 : char ssid[WIFI_SSID_MAX_LEN];
65 :
66 : /** Length of the SSID */
67 1 : size_t ssid_len;
68 :
69 : /** Flags for controlling detail settings */
70 1 : uint32_t flags;
71 :
72 : /** Timeout for connecting to the network */
73 1 : uint32_t timeout;
74 :
75 : /** BSSID (Basic Service Set Identifier) */
76 1 : uint8_t bssid[WIFI_MAC_ADDR_LEN];
77 :
78 : /** Channel on which the network operates */
79 1 : uint8_t channel;
80 :
81 : /** Anonymous identifier (Limited to 16 bytes due to settings subsystem overflow) */
82 1 : char anon_id[16];
83 :
84 : /** Length of the Anonymous identifier */
85 1 : uint8_t aid_length;
86 :
87 : /** Password/PSK (Limited to 16 bytes due to settings subsystem overflow) */
88 1 : char key_passwd[16];
89 :
90 : /** Length of the Password */
91 1 : uint8_t key_passwd_length;
92 : };
93 :
94 : /**
95 : * @brief Wi-Fi Personal credentials entry
96 : * @note Contains only the header and a password.
97 : * For PSK security, passwords can be up to `WIFI_PSK_MAX_LEN` bytes long
98 : * including NULL termination. For SAE security it can range up to
99 : * `CONFIG_WIFI_CREDENTIALS_SAE_PASSWORD_LENGTH`.
100 : *
101 : */
102 1 : struct wifi_credentials_personal {
103 : /** Header */
104 1 : struct wifi_credentials_header header;
105 :
106 : /** Password/PSK */
107 1 : char password[WIFI_CREDENTIALS_MAX_PASSWORD_LEN];
108 :
109 : /** Length of the password */
110 1 : size_t password_len;
111 : };
112 :
113 : /**
114 : * @brief Wi-Fi Enterprise credentials entry
115 : * @note This functionality is not yet implemented.
116 : */
117 1 : struct wifi_credentials_enterprise {
118 : /** Header */
119 1 : struct wifi_credentials_header header;
120 :
121 : /** Length of the identity */
122 1 : size_t identity_len;
123 :
124 : /** Length of the anonymous identity */
125 1 : size_t anonymous_identity_len;
126 :
127 : /** Length of the password */
128 1 : size_t password_len;
129 :
130 : /** Length of the CA certificate */
131 1 : size_t ca_cert_len;
132 :
133 : /** Length of the client certificate */
134 1 : size_t client_cert_len;
135 :
136 : /** Length of the private key */
137 1 : size_t private_key_len;
138 :
139 : /** Length of the private key password */
140 1 : size_t private_key_pw_len;
141 : };
142 :
143 : /**
144 : * @brief Get credentials for given SSID.
145 : *
146 : * @param[in] ssid SSID to look for
147 : * @param[in] ssid_len length of SSID
148 : * @param[out] type Wi-Fi security type
149 : * @param[out] bssid_buf buffer to store BSSID if it was fixed
150 : * @param[in] bssid_buf_len length of bssid_buf
151 : * @param[out] password_buf buffer to store password
152 : * @param[in] password_buf_len length of password_buf
153 : * @param[out] password_len length of password
154 : * @param[out] flags flags
155 : * @param[out] channel channel
156 : * @param[out] timeout timeout
157 : *
158 : * @return 0 Success.
159 : * @return -ENOENT No network with this SSID was found.
160 : * @return -EINVAL A required buffer was NULL or invalid SSID length.
161 : * @return -EPROTO The network with this SSID is not a personal network.
162 : */
163 1 : int wifi_credentials_get_by_ssid_personal(const char *ssid, size_t ssid_len,
164 : enum wifi_security_type *type, uint8_t *bssid_buf,
165 : size_t bssid_buf_len, char *password_buf,
166 : size_t password_buf_len, size_t *password_len,
167 : uint32_t *flags, uint8_t *channel, uint32_t *timeout);
168 :
169 : /**
170 : * @brief Set credentials for given SSID.
171 : *
172 : * @param[in] ssid SSID to look for
173 : * @param[in] ssid_len length of SSID
174 : * @param[in] type Wi-Fi security type
175 : * @param[in] bssid BSSID (may be NULL)
176 : * @param[in] bssid_len length of BSSID buffer (either 0 or WIFI_MAC_ADDR_LEN)
177 : * @param[in] password password
178 : * @param[in] password_len length of password
179 : * @param[in] flags flags
180 : * @param[in] channel Channel
181 : * @param[in] timeout Timeout
182 : *
183 : * @return 0 Success. Credentials are stored in persistent storage.
184 : * @return -EINVAL A required buffer was NULL or security type is not supported.
185 : * @return -ENOTSUP Security type is not supported.
186 : * @return -ENOBUFS All slots are already taken.
187 : */
188 1 : int wifi_credentials_set_personal(const char *ssid, size_t ssid_len, enum wifi_security_type type,
189 : const uint8_t *bssid, size_t bssid_len, const char *password,
190 : size_t password_len, uint32_t flags, uint8_t channel,
191 : uint32_t timeout);
192 :
193 : /**
194 : * @brief Get credentials for given SSID by struct.
195 : *
196 : * @param[in] ssid SSID to look for
197 : * @param[in] ssid_len length of SSID
198 : * @param[out] buf credentials Pointer to struct where credentials are stored
199 : *
200 : * @return 0 Success.
201 : * @return -ENOENT No network with this SSID was found.
202 : * @return -EINVAL A required buffer was NULL or too small.
203 : * @return -EPROTO The network with this SSID is not a personal network.
204 : */
205 1 : int wifi_credentials_get_by_ssid_personal_struct(const char *ssid, size_t ssid_len,
206 : struct wifi_credentials_personal *buf);
207 :
208 : /**
209 : * @brief Set credentials for given SSID by struct.
210 : *
211 : * @param[in] creds credentials Pointer to struct from which credentials are loaded
212 : *
213 : * @return 0 Success.
214 : * @return -ENOENT No network with this SSID was found.
215 : * @return -EINVAL A required buffer was NULL or incorrect size.
216 : * @return -ENOBUFS All slots are already taken.
217 : */
218 1 : int wifi_credentials_set_personal_struct(const struct wifi_credentials_personal *creds);
219 :
220 : /**
221 : * @brief Delete credentials for given SSID.
222 : *
223 : * @param[in] ssid SSID to look for
224 : * @param[in] ssid_len length of SSID
225 : *
226 : * @return -ENOENT if No network with this SSID was found.
227 : * @return 0 on success, otherwise a negative error code
228 : */
229 1 : int wifi_credentials_delete_by_ssid(const char *ssid, size_t ssid_len);
230 :
231 : /**
232 : * @brief Check if credentials storage is empty.
233 : *
234 : * @return true if credential storage is empty, otherwise false
235 : */
236 1 : bool wifi_credentials_is_empty(void);
237 :
238 : /**
239 : * @brief Deletes all stored Wi-Fi credentials.
240 : *
241 : * This function deletes all Wi-Fi credentials that have been stored in the system.
242 : * It is typically used when you want to clear all saved networks.
243 : *
244 : * @return 0 on successful, otherwise a negative error code
245 : */
246 1 : int wifi_credentials_delete_all(void);
247 :
248 : /**
249 : * @brief Callback type for wifi_credentials_for_each_ssid.
250 : *
251 : * @param[in] cb_arg arguments for the callback function. Appropriate cb_arg is
252 : * transferred by wifi_credentials_for_each_ssid.
253 : * @param[in] ssid SSID
254 : * @param[in] ssid_len length of SSID
255 : */
256 1 : typedef void (*wifi_credentials_ssid_cb)(void *cb_arg, const char *ssid, size_t ssid_len);
257 :
258 : /**
259 : * @brief Call callback for each registered SSID.
260 : *
261 : * @param cb callback
262 : * @param cb_arg argument for callback function
263 : */
264 1 : void wifi_credentials_for_each_ssid(wifi_credentials_ssid_cb cb, void *cb_arg);
265 :
266 : #ifdef __cplusplus
267 : }
268 : #endif
269 :
270 : /** @} */
271 :
272 : #endif /* WIFI_CREDENTIALS_H__ */
|
