xref: /freebsd/contrib/wpa/wpa_supplicant/README-DPP (revision c1d255d3ffdbe447de3ab875bf4e7d7accc5bfc5)

Device Provisioning Protocol (DPP)
==================================

This document describes how the Device Provisioning Protocol (DPP)
implementation in wpa_supplicant and hostapd can be configured and how
the STA device and AP can be configured to connect each other using DPP
Connector mechanism.

Introduction to DPP
-------------------

Device Provisioning Protocol (also known as Wi-Fi Easy Connect) allows
enrolling of interface-less devices in a secure Wi-Fi network using many
methods like QR code based authentication (detailed below), PKEX based
authentication (password with in-band provisioning), etc. In DPP a
Configurator is used to provide network credentials to the devices. The
three phases of DPP connection are authentication, configuration and
network introduction.

More information about Wi-Fi Easy Connect is available from this Wi-Fi
Alliance web page:
https://www.wi-fi.org/discover-wi-fi/wi-fi-easy-connect

Build config setup
------------------

The following parameters must be included in the config file used to
compile hostapd and wpa_supplicant.

wpa_supplicant build config
---------------------------

Enable DPP in wpa_supplicant build config file

CONFIG_DPP=y

hostapd build config
--------------------

Enable DPP in hostapd build config file

CONFIG_DPP=y

Configurator build config
-------------------------

Any STA or AP device can act as a Configurator. Enable DPP in build
config. For an AP to act as a Configurator, Interworking needs to be
enabled for GAS. For wpa_supplicant it is not required.

CONFIG_INTERWORKING=y


Sample supplicant config file before provisioning
-------------------------------------------------

ctrl_interface=DIR=/var/run/wpa_supplicant
ctrl_interface_group=0
update_config=1
pmf=2
dpp_config_processing=2

Sample hostapd config file before provisioning
----------------------------------------------

interface=wlan0
driver=nl80211
ctrl_interface=/var/run/hostapd
ssid=test
channel=1
wpa=2
wpa_key_mgmt=DPP
ieee80211w=1
wpa_pairwise=CCMP
rsn_pairwise=CCMP


Pre-requisites
--------------

It is assumed that an AP and client station are up by running hostapd
and wpa_supplicant using respective config files.


Creating Configurator
---------------------

Add a Configurator over the control interface (wpa_cli/hostapd_cli)

> dpp_configurator_add
(returns id)

To get key of Configurator
> dpp_configurator_get_key <id>


How to configure an Enrollee using Configurator
-----------------------------------------------

On Enrollee side:

Generate QR code for the device. Store the QR code id returned by the
command.

> dpp_bootstrap_gen type=qrcode mac=<mac-address-of-device> chan=<operating-class/channel> key=<key of the device>
(Returns bootstrapping info id. If the key parameter is not included, a new key
is generated automatically. The MAC address is specified without octet
separating colons. The channel list includes the possible channels on which the
device is waiting. This uses global operating classes; e.g., 81/1 is the 2.4
GHz channel 1 on 2412 MHz.)

Get URI for the QR Code of device using the bootstrap info id.
> dpp_bootstrap_get_uri <bootstrap-id>

Make device listen to DPP request. The central frequency of the 2.4 GHz
band channel 1 is 2412 MHz) in case the Enrollee is a client device. An
AP as an Enrollee is listening on its operating channel.

> dpp_listen <frequency>

On Configurator side:

Enter the QR Code in the Configurator.
> dpp_qr_code "<URI-from-QR-Code-read-from-enrollee>"

On successfully adding QR Code, a bootstrapping info id is returned.

Send provisioning request to Enrollee. (conf is ap-dpp if Enrollee is an
AP. conf is sta-dpp if Enrollee is a client)
> dpp_auth_init peer=<qr-code-id> conf=<ap-dpp|sta-dpp> ssid=<SSID hexdump> configurator=<configurator-id>
or for legacy (PSK/SAE) provisioning for a station Enrollee:
> dpp_auth_init peer=<qr-code-id> conf=sta-psk ssid=<SSID hexdump> pass=<passphrase hexdump>

The DPP values will be printed in the console. Save these values into the
config file. If the Enrollee is an AP, we need to manually write these
values to the hostapd config file. If the Enrollee is a client device,
these details can be automatically saved to config file using the
following command.

> save_config

To set values in runtime for AP enrollees

> set dpp_connector <Connector-value-printed-on-console>
> set dpp_csign <csign-value-on-console>
> set dpp_netaccesskey <netaccess-value-on-console>

To set values in runtime for client enrollees, set dpp_config_processing
to 2 in wpa_supplicant conf file.

Once the values are set in run-time (if not set in run-time, but saved
in config files, they are taken up in next restart), the client device
will automatically connect to the already provisioned AP and connection
will be established.


Self-configuring a device
-------------------------

It is possible for a device to configure itself if it is the
Configurator for the network.

Create a Configurator in the device and use the dpp_configurator_sign
command to get DPP credentials.

> dpp_configurator_add
(returns configurator id)
> dpp_configurator_sign conf=<ap-dpp|sta-dpp> configurator=<configurator-id> ssid=<SSID hexdump>


Sample AP configuration files after provisioning
------------------------------------------------

interface=wlan0
driver=nl80211
ctrl_interface=/var/run/hostapd
ssid=test
channel=1
wpa=2
wpa_key_mgmt=DPP
ieee80211w=1
wpa_pairwise=CCMP
rsn_pairwise=CCMP
dpp_connector=<Connector value provided by Configurator>
dpp_csign=<C-Sign-Key value provided by Configurator>
dpp_netaccesskey=<Net access key provided by Configurator>


Sample station configuration file after provisioning
----------------------------------------------------

ctrl_interface=DIR=/var/run/wpa_supplicant
ctrl_interface_group=0
update_config=1
pmf=2
dpp_config_processing=2
network={
	ssid="test"
	key_mgmt=DPP
	ieee80211w=2
	dpp_connector="<Connector value provided by Configurator>"
	dpp_netaccesskey=<Net access key provided by Configurator>
	dpp_csign=<C-sign-key value provided by Configurator>
}