fragattacks/wpa_supplicant/README-DPP

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 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 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.

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

The following changes must go in the config file used to compile hostapd
and wpa_supplicant.

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

Enable DPP and protected management frame in wpa_supplicant build config
file

CONFIG_IEEE80211W=y
CONFIG_DPP=y

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

Enable DPP and protected management frame in hostapd build config file

CONFIG_IEEE80211W=y
CONFIG_DPP=y

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

Any STA or AP device can act as a Configurator. Enable DPP and protected
managment frames in build config. For an AP to act as Configurator,
Interworking needs to be enabled. 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-channel> key=<key of the device>
(returns bootstrapping info id)

Get 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 channel 1 is
2412) in case if enrollee is a client device.

> dpp_listen <frequency>

On Configurator side:

Enter the QR Code in the Configurator.
> dpp_qr_code "<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> configurator=<configurator-id>

The DPP values will be printed in the console. Save this 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>


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>
}