1.. _lib_wifi_credentials:
2
3Wi-Fi credentials Library
4#########################
5
6.. contents::
7   :local:
8   :depth: 2
9
10The Wi-Fi credentials library provides means to load and store Wi-Fi® network credentials.
11
12Overview
13********
14
15This library uses either Zephyr's settings subsystem or Platform Security Architecture (PSA) Internal Trusted Storage (ITS) to store credentials.
16It also holds a list of SSIDs in RAM to provide dictionary-like access using SSIDs as keys.
17
18Configuration
19*************
20
21To use the Wi-Fi credentials library, enable the :kconfig:option:`CONFIG_WIFI_CREDENTIALS` Kconfig option.
22
23You can pick the backend using the following options:
24
25* :kconfig:option:`CONFIG_WIFI_CREDENTIALS_BACKEND_PSA` - Default option for non-secure targets, which includes a TF-M partition (non-minimal TF-M profile type).
26* :kconfig:option:`CONFIG_WIFI_CREDENTIALS_BACKEND_SETTINGS` - Default option for secure targets.
27
28To configure the maximum number of networks, use the :kconfig:option:`CONFIG_WIFI_CREDENTIALS_MAX_ENTRIES` Kconfig option.
29
30The IEEE 802.11 standard does not specify the maximum length of SAE passwords.
31To change the default, use the :kconfig:option:`CONFIG_WIFI_CREDENTIALS_SAE_PASSWORD_LENGTH` Kconfig option.
32
33Adding credentials
34******************
35
36You can add credentials using the :c:func:`wifi_credentials_set_personal` and :c:func:`wifi_credentials_set_personal_struct` functions.
37The former will build the internally used struct from given fields, while the latter takes the struct directly.
38If you add credentials with the same SSID twice, the older entry will be overwritten.
39
40Querying credentials
41********************
42
43With an SSID, you can query credentials using the :c:func:`wifi_credentials_get_by_ssid_personal` and :c:func:`wifi_credentials_get_by_ssid_personal_struct` functions.
44
45You can iterate over all stored credentials with the :c:func:`wifi_credentials_for_each_ssid` function.
46Deleting or overwriting credentials while iterating is allowed, since these operations do not change internal indices.
47
48Removing credentials
49********************
50
51You can remove credentials using the :c:func:`wifi_credentials_delete_by_ssid` function.
52
53Shell commands
54**************
55
56``wifi cred`` is an extension to the Wi-Fi command line.
57It adds the following subcommands to interact with the Wi-Fi credentials library:
58
59.. list-table:: Wi-Fi credentials shell subcommands
60   :header-rows: 1
61
62   * - Subcommands
63     - Description
64   * - add
65     - | Add a network to the credentials storage with following parameters:
66       | <-s --ssid \"<SSID>\">: SSID.
67       | [-c --channel]: Channel that needs to be scanned for connection. 0:any channel
68       | [-b, --band] 0: any band (2:2.4GHz, 5:5GHz, 6:6GHz)
69       | [-p, --passphrase]: Passphrase (valid only for secure SSIDs)
70       | [-k, --key-mgmt]: Key management type.
71       | 0:None, 1:WPA2-PSK, 2:WPA2-PSK-256, 3:SAE-HNP, 4:SAE-H2E, 5:SAE-AUTO, 6:WAPI,"
72       | " 7:EAP-TLS, 8:WEP, 9: WPA-PSK, 10: WPA-Auto-Personal, 11: DPP
73       | [-w, --ieee-80211w]: MFP (optional: needs security type to be specified)
74       | : 0:Disable, 1:Optional, 2:Required.
75       | [-m, --bssid]: MAC address of the AP (BSSID).
76       | [-t, --timeout]: Duration after which connection attempt needs to fail.
77       | [-a, --identity]: Identity for enterprise mode.
78       | [-K, --key-passwd]: Private key passwd for enterprise mode.
79       | [-h, --help]: Print out the help for the connect command.
80   * - delete <SSID>
81     - Removes network from credentials storage.
82   * - list
83     - Lists networks in credential storage.
84   * - auto_connect
85     - Automatically connects to any stored network.
86
87Limitations
88***********
89
90The library has the following limitations:
91
92* Although permitted by the IEEE 802.11 standard, this library does not support zero-length SSIDs.
93* Wi-Fi Protected Access (WPA) Enterprise credentials are only partially supported.
94* The number of networks stored is fixed compile time.
95
96API documentation
97*****************
98
99The following section provides an overview and reference for the Wi-Fi credentials API available in Zephyr:
100
101.. doxygengroup:: wifi_credentials
102