1.. _wifi_mgmt: 2 3Wi-Fi Management 4################ 5 6Overview 7======== 8 9The Wi-Fi management API is used to manage Wi-Fi networks. It supports below modes: 10 11* IEEE802.11 Station (STA) 12* IEEE802.11 Access Point (AP) 13 14Only personal mode security is supported with below types: 15 16* Open 17* WPA2-PSK 18* WPA2-PSK-256 19* WPA3-SAE 20 21The Wi-Fi management API is implemented in the ``wifi_mgmt`` module as a part of the networking L2 22stack. 23Currently, two types of Wi-Fi drivers are supported: 24 25* Networking or socket offloaded drivers 26* Native L2 Ethernet drivers 27 28Compiled Features 29***************** 30 31To support applications that only require a certain subset of Wi-Fi features, :kconfig:option:`CONFIG_WIFI_USAGE_MODE` can be used 32as a hint for drivers to limit the functionality that needs to be compiled in. The following usage hints are available: 33 34 * :kconfig:option:`CONFIG_WIFI_USAGE_MODE_STA` (Connecting to an access point) 35 * :kconfig:option:`CONFIG_WIFI_USAGE_MODE_AP` (Being an access point) 36 * :kconfig:option:`CONFIG_WIFI_USAGE_MODE_STA_AP` (Both being and connecting to an access point) 37 * :kconfig:option:`CONFIG_WIFI_USAGE_MODE_SCAN_ONLY` (Access point SSID scanning only) 38 39.. note:: 40 41 Support for a requested usage mode is hardware dependent. 42 43Wi-Fi PSA crypto supported build 44******************************** 45 46To enable PSA crypto API supported Wi-Fi build, the :kconfig:option:`CONFIG_WIFI_NM_WPA_SUPPLICANT_CRYPTO_ALT` and the :kconfig:option:`CONFIG_WIFI_NM_WPA_SUPPLICANT_CRYPTO_MBEDTLS_PSA` need to be set. 47 48Wi-Fi Enterprise test: X.509 Certificate management 49*************************************************** 50 51Wi-Fi enterprise security requires use of X.509 certificates, two methods of installing certificates are supported: 52 53Compile time certificates 54------------------------- 55 56Test certificates in PEM format are committed to the repo at :zephyr_file:`samples/net/wifi/test_certs` and the during the 57build process the certificates are converted to a C header file that is included by the Wi-Fi shell 58module. 59 60If you want to use your own certificates, you can replace the existing certificates with your own certificates in the same directory. 61 62.. code-block:: bash 63 64 $ export WIFI_TEST_CERTS_DIR=samples/net/wifi/test_certs/rsa3k 65 $ cp client.pem $WIFI_TEST_CERTS_DIR 66 $ cp client-key.pem $WIFI_TEST_CERTS_DIR 67 $ cp ca.pem $WIFI_TEST_CERTS_DIR 68 $ cp client2.pem $WIFI_TEST_CERTS_DIR 69 $ cp client-key2.pem $WIFI_TEST_CERTS_DIR 70 $ cp ca2.pem $WIFI_TEST_CERTS_DIR 71 $ west build -p -b <board> samples/net/wifi -S wifi-enterprise 72 73or alternatively copy ``rsa2k`` certificates by changing the ``WIFI_TEST_CERTS_DIR`` environment variable. 74 75.. code-block:: bash 76 77 $ export WIFI_TEST_CERTS_DIR=samples/net/wifi/test_certs/rsa2k 78 79or you can set the :envvar:`WIFI_TEST_CERTS_DIR` environment variable to point to the directory containing your certificates. 80 81.. code-block:: bash 82 83 $ west build -p -b <board> samples/net/wifi -S wifi-enterprise -- -DWIFI_TEST_CERTS_DIR=<path_to_your_certificates> 84 85Run time certificates 86--------------------- 87 88The Wi-Fi shell module uses TLS credentials subsystem to store and manage the certificates. The certificates can be added at runtime using the shell commands, see :ref:`tls_credentials_shell` for more details. 89The sample or application need to enable the :kconfig:option:`CONFIG_WIFI_SHELL_RUNTIME_CERTIFICATES` option to use this feature. 90 91To facilitate installation of the certificates, a helper script is provided, see below for usage. 92 93.. code-block:: bash 94 95 $ ./scripts/utils/wifi_ent_cert_installer.py -p samples/net/wifi/test_certs/rsa2k 96 97The script will install the certificates in the ``rsa2k`` directory to the TLS credentials store in the device over UART and using TLS credentials shell commands. 98 99 100To initiate a Wi-Fi connection using enterprise security, use one of the following commands depending on the EAP method: 101 102* EAP-TLS 103 104 .. code-block:: console 105 106 uart:~$ wifi connect -s <SSID> -c <channel> -k 7 -w 2 -a <Anonymous identity> --key1-pwd <Password EAP phase1> --key2-pwd <Password EAP phase2> 107 108* EAP-TTLS-MSCHAPV2 109 110 .. code-block:: console 111 112 uart:~$ wifi connect -s <SSID> -c <channel> -k 14 -K <Private key Password> --eap-id1 <Client Identity> --eap-pwd1 <Client Password> -a <Anonymous identity> 113 114* EAP-PEAP-MSCHAPV2 115 116 .. code-block:: console 117 118 uart:~$ wifi connect -s <SSID> -c <channel> -k 12 -K <Private key Password> --eap-id1 <Client Identity> --eap-pwd1 <Client Password> -a <Anonymous identity> 119 120Server certificate is also provided in the same directory for testing purposes. 121Any AAA server can be used for testing purposes, for example, ``FreeRADIUS`` or ``hostapd``. 122 123Certificate requirements for EAP methods 124---------------------------------------- 125 126Different EAP methods have varying client-side certificate requirements, as outlined below: 127 128* EAP-TLS - Requires both a client certificate (and its private key) and a CA certificate on the client. 129 The client authenticates itself to the server using its certificate. 130 131* EAP-TTLS-MSCHAPV2 - Requires only the CA certificate on the client. 132 The client authenticates to the server using a username and password <MSCHAPV2> inside the TLS tunnel. 133 No client certificate is needed. 134 135* EAP-PEAP-MSCHAPV2 - Requires only the CA certificate on the client. 136 Like TTLS, the client uses a username and password <MSCHAPV2> inside the TLS tunnel and does not require a client certificate. 137 138.. note:: 139 140 The certificates are for testing purposes only and should not be used in production. 141 They are generated using `FreeRADIUS raddb <https://github.com/FreeRADIUS/freeradius-server/tree/master/raddb/certs>`_ scripts. 142 143.. note:: 144 145 When using TLS credentials subsystem, by default the volatile backend i.e., :kconfig:option:`CONFIG_TLS_CREDENTIALS_BACKEND_VOLATILE` is chosen. When using the volatile backend, the certificates are stored in RAM and are lost on reboot, so the certificates need to be installed again after reboot. As an alternative, the PS (protected storage) backend i.e., :kconfig:option:`CONFIG_TLS_CREDENTIALS_BACKEND_PROTECTED_STORAGE` can be used to store the certificates in the non-volatile storage. 146 147How to Generate Test Certificates Using FreeRADIUS 148-------------------------------------------------- 149 150The test certificates in ``samples/net/wifi/test_certs/rsa2k`` are generated using the `FreeRADIUS raddb/certs scripts <https://github.com/FreeRADIUS/freeradius-server/tree/master/raddb/certs>`_. You can generate your own certificates for testing as follows: 151 1521. **Prerequisites** 153 - Install OpenSSL and GNU Make. 154 - Download the `FreeRADIUS raddb/certs directory <https://github.com/FreeRADIUS/freeradius-server/tree/master/raddb/certs>`_. 155 1562. **Edit the Makefile** 157 In the ``raddb/certs`` directory, edit the ``Makefile`` to add ``-nodes`` to the OpenSSL commands for server and client keys. This ensures the private keys are not password-protected (Zephyr Wi-Fi shell does not support private key passwords): 158 159 :: 160 161 $(OPENSSL) req -new -out server.csr -keyout server.key -nodes -config ./server.cnf 162 $(OPENSSL) req -new -out client.csr -keyout client.key -nodes -config ./client.cnf 163 1643. **(Optional) Edit the .cnf files** 165 Customize ``server.cnf`` and ``client.cnf`` as needed for your environment. 166 1674. **Generate Certificates** 168 Run the following commands in the ``raddb/certs`` directory: 169 170 :: 171 172 make destroycerts 173 make server 174 make client 175 1765. **Rename Files for Zephyr** 177 Match the filenames used in Zephyr samples: 178 179 +-------------------+---------------------+ 180 | FreeRADIUS Output | Zephyr Sample Name | 181 +===================+=====================+ 182 | ca.pem | ca.pem | 183 | server.key | server-key.pem | 184 | server.pem | server.pem | 185 | client.key | client-key.pem | 186 | client.pem | client.pem | 187 +-------------------+---------------------+ 188 1896. **Copy the files** 190 Place the renamed files in your Zephyr project's certificate directory (e.g., ``samples/net/wifi/test_certs/rsa2k``). 191 192.. note:: 193 These certificates are for testing only and should not be used in production. 194 195API Reference 196************* 197 198.. doxygengroup:: wifi_mgmt 199