Wi-Fi credentials

The Wi-Fi credentials library provides means to load and store Wi-Fi network credentials.

Overview

This library uses either Zephyr’s settings subsystem or Platform Security Architecture (PSA) Internal Trusted Storage (ITS) to store credentials. It also holds a list of SSIDs in RAM to provide dictionary-like access using SSIDs as keys.

Configuration

To use the Wi-Fi credentials library, enable the CONFIG_WIFI_CREDENTIALS Kconfig option.

You can pick the backend using the following options:

To configure the maximum number of networks, use the CONFIG_WIFI_CREDENTIALS_MAX_ENTRIES Kconfig option.

The IEEE 802.11 standard does not specify the maximum length of SAE passwords. To change the default, use the CONFIG_WIFI_CREDENTIALS_SAE_PASSWORD_LENGTH Kconfig option.

When using the PSA ITS backend, entries will be saved under consecutive key IDs with an offset configured with the CONFIG_WIFI_CREDENTIALS_BACKEND_PSA_OFFSET Kconfig option.

Adding credentials

You can add credentials using the wifi_credentials_set_personal() and wifi_credentials_set_personal_struct() functions. The former will build the internally used struct from given fields, while the latter takes the struct directly. If you add credentials with the same SSID twice, the older entry will be overwritten.

Querying credentials

With an SSID, you can query credentials using the wifi_credentials_get_by_ssid_personal() and wifi_credentials_get_by_ssid_personal_struct() functions.

You can iterate over all stored credentials with the wifi_credentials_for_each_ssid() function. Deleting or overwriting credentials while iterating is allowed, since these operations do not change internal indices.

Removing credentials

You can remove credentials using the wifi_credentials_delete_by_ssid() function.

Limitations

The library has the following limitations:

  • Although permitted by the IEEE 802.11 standard, this library does not support zero-length SSIDs.

  • Wi-Fi Protected Access (WPA) Enterprise credentials are not yet supported.

  • The number of networks stored is fixed compile time.

API documentation

Header file: include/net/wifi_credentials.h
Source files: subsys/net/lib/wifi_credentials
group wifi_credentials

Library that provides a way to store and load Wi-Fi credentials.

Defines

WIFI_CREDENTIALS_FLAG_BSSID
WIFI_CREDENTIALS_FLAG_FAVORITE
WIFI_CREDENTIALS_FLAG_2_4GHz
WIFI_CREDENTIALS_FLAG_5GHz
WIFI_CREDENTIALS_FLAG_MFP_REQUIRED
WIFI_CREDENTIALS_FLAG_MFP_DISABLED
WIFI_CREDENTIALS_MAX_PASSWORD_LEN

Typedefs

typedef void (*wifi_credentials_ssid_cb)(void *cb_arg, const char *ssid, size_t ssid_len)

Callback type for wifi_credentials_for_each_ssid.

Param cb_arg:

[in] arguments for the callback function. Appropriate cb_arg is transferred by wifi_credentials_for_each_ssid.

Param ssid:

[in] SSID

Param ssid_len:

[in] length of SSID

Functions

int wifi_credentials_get_by_ssid_personal(const char *ssid, size_t ssid_len, enum wifi_security_type *type, uint8_t *bssid_buf, size_t bssid_buf_len, char *password_buf, size_t password_buf_len, size_t *password_len, uint32_t *flags, uint8_t *channel, uint32_t *timeout)

Get credentials for given SSID.

Parameters:

  • ssid – [in] SSID to look for

  • ssid_len – [in] length of SSID

  • type – [out] Wi-Fi security type

  • bssid_buf – [out] buffer to store BSSID if it was fixed

  • bssid_buf_len – [in] length of bssid_buf

  • password_buf – [out] buffer to store password

  • password_buf_len – [in] length of password_buf

  • password_len – [out] length of password

  • flags – [out] flags

  • channel – [out] channel

  • timeout – [out] timeout

Returns:

0 Success.

Returns:

-ENOENT No network with this SSID was found.

Returns:

-EINVAL A required buffer was NULL or invalid SSID length.

Returns:

-EPROTO The network with this SSID is not a personal network.

int wifi_credentials_set_personal(const char *ssid, size_t ssid_len, enum wifi_security_type type, const uint8_t *bssid, size_t bssid_len, const char *password, size_t password_len, uint32_t flags, uint8_t channel, uint32_t timeout)

Set credentials for given SSID.

Parameters:

  • ssid – [in] SSID to look for

  • ssid_len – [in] length of SSID

  • type – [in] Wi-Fi security type

  • bssid – [in] BSSID (may be NULL)

  • bssid_len – [in] length of BSSID buffer (either 0 or WIFI_MAC_ADDR_LEN)

  • password – [in] password

  • password_len – [in] length of password

  • flags – [in] flags

  • channel – [in] Channel

  • timeout – [in] Timeout

Returns:

0 Success. Credentials are stored in persistent storage.

Returns:

-EINVAL A required buffer was NULL or security type is not supported.

Returns:

-ENOTSUP Security type is not supported.

Returns:

-ENOBUFS All slots are already taken.

int wifi_credentials_get_by_ssid_personal_struct(const char *ssid, size_t ssid_len, struct wifi_credentials_personal *buf)

Get credentials for given SSID by struct.

Parameters:

  • ssid – [in] SSID to look for

  • ssid_len – [in] length of SSID

  • buf – [out] credentials Pointer to struct where credentials are stored

Returns:

0 Success.

Returns:

-ENOENT No network with this SSID was found.

Returns:

-EINVAL A required buffer was NULL or too small.

Returns:

-EPROTO The network with this SSID is not a personal network.

int wifi_credentials_set_personal_struct(const struct wifi_credentials_personal *creds)

Set credentials for given SSID by struct.

Parameters:

  • creds – [in] credentials Pointer to struct from which credentials are loaded

Returns:

0 Success.

Returns:

-ENOENT No network with this SSID was found.

Returns:

-EINVAL A required buffer was NULL or incorrect size.

Returns:

-ENOBUFS All slots are already taken.

int wifi_credentials_delete_by_ssid(const char *ssid, size_t ssid_len)

Delete credentials for given SSID.

Parameters:

  • ssid – [in] SSID to look for

  • ssid_len – [in] length of SSID

Returns:

-ENOENT if No network with this SSID was found.

Returns:

0 on success, otherwise a negative error code

bool wifi_credentials_is_empty(void)

Check if credentials storage is empty.

Returns:

true if credential storage is empty, otherwise false

int wifi_credentials_delete_all(void)

Deletes all stored Wi-Fi credentials.

This function deletes all Wi-Fi credentials that have been stored in the system. It is typically used when you want to clear all saved networks.

Returns:

0 on successful, otherwise a negative error code

void wifi_credentials_for_each_ssid(wifi_credentials_ssid_cb cb, void *cb_arg)

Call callback for each registered SSID.

Parameters:

  • cb – callback

  • cb_arg – argument for callback function

struct wifi_credentials_header
#include <wifi_credentials.h>

Wi-Fi credentials entry header.

Note

Every settings entry starts with this header. Depending on the type field, the header can be casted to a larger type. In addition to SSID (usually a string) and BSSID (a MAC address), a flags field can be used to control some detail settings.

struct wifi_credentials_personal
#include <wifi_credentials.h>

Wi-Fi Personal credentials entry.

Note

Contains only the header and a password. For PSK security, passwords can be up to WIFI_PSK_MAX_LEN bytes long including NULL termination. For SAE security it can range up to CONFIG_WIFI_CREDENTIALS_SAE_PASSWORD_LENGTH.

struct wifi_credentials_enterprise
#include <wifi_credentials.h>

Wi-Fi Enterprise credentials entry.

Note

This functionality is not yet implemented.