1Device Provisioning Protocol (DPP)
2==================================
3
4This document describes how the Device Provisioning Protocol (DPP)
5implementation in wpa_supplicant and hostapd can be configured and how
6the STA device and AP can be configured to connect each other using DPP
7Connector mechanism.
8
9Introduction to DPP
10-------------------
11
12Device Provisioning Protocol (also known as Wi-Fi Easy Connect) allows
13enrolling of interface-less devices in a secure Wi-Fi network using many
14methods like QR code based authentication (detailed below), PKEX based
15authentication (password with in-band provisioning), etc. In DPP a
16Configurator is used to provide network credentials to the devices. The
17three phases of DPP connection are authentication, configuration and
18network introduction.
19
20More information about Wi-Fi Easy Connect is available from this Wi-Fi
21Alliance web page:
22https://www.wi-fi.org/discover-wi-fi/wi-fi-easy-connect
23
24Build config setup
25------------------
26
27The following parameters must be included in the config file used to
28compile hostapd and wpa_supplicant.
29
30wpa_supplicant build config
31---------------------------
32
33Enable DPP in wpa_supplicant build config file
34
35CONFIG_DPP=y
36
37hostapd build config
38--------------------
39
40Enable DPP in hostapd build config file
41
42CONFIG_DPP=y
43
44Configurator build config
45-------------------------
46
47Any STA or AP device can act as a Configurator. Enable DPP in build
48config. For an AP to act as a Configurator, Interworking needs to be
49enabled for GAS. For wpa_supplicant it is not required.
50
51CONFIG_INTERWORKING=y
52
53
54Sample supplicant config file before provisioning
55-------------------------------------------------
56
57ctrl_interface=DIR=/var/run/wpa_supplicant
58ctrl_interface_group=0
59update_config=1
60pmf=2
61dpp_config_processing=2
62
63Sample hostapd config file before provisioning
64----------------------------------------------
65
66interface=wlan0
67driver=nl80211
68ctrl_interface=/var/run/hostapd
69ssid=test
70channel=1
71wpa=2
72wpa_key_mgmt=DPP
73ieee80211w=1
74wpa_pairwise=CCMP
75rsn_pairwise=CCMP
76
77
78Pre-requisites
79--------------
80
81It is assumed that an AP and client station are up by running hostapd
82and wpa_supplicant using respective config files.
83
84
85Creating Configurator
86---------------------
87
88Add a Configurator over the control interface (wpa_cli/hostapd_cli)
89
90> dpp_configurator_add
91(returns id)
92
93To get key of Configurator
94> dpp_configurator_get_key <id>
95
96
97How to configure an Enrollee using Configurator
98-----------------------------------------------
99
100On Enrollee side:
101
102Generate QR code for the device. Store the QR code id returned by the
103command.
104
105> dpp_bootstrap_gen type=qrcode mac=<mac-address-of-device> chan=<operating-class/channel> key=<key of the device>
106(Returns bootstrapping info id. If the key parameter is not included, a new key
107is generated automatically. The MAC address is specified without octet
108separating colons. The channel list includes the possible channels on which the
109device is waiting. This uses global operating classes; e.g., 81/1 is the 2.4
110GHz channel 1 on 2412 MHz.)
111
112Get URI for the QR Code of device using the bootstrap info id.
113> dpp_bootstrap_get_uri <bootstrap-id>
114
115Make device listen to DPP request. The central frequency of the 2.4 GHz
116band channel 1 is 2412 MHz) in case the Enrollee is a client device. An
117AP as an Enrollee is listening on its operating channel.
118
119> dpp_listen <frequency>
120
121On Configurator side:
122
123Enter the QR Code in the Configurator.
124> dpp_qr_code "<URI-from-QR-Code-read-from-enrollee>"
125
126On successfully adding QR Code, a bootstrapping info id is returned.
127
128Send provisioning request to Enrollee. (conf is ap-dpp if Enrollee is an
129AP. conf is sta-dpp if Enrollee is a client)
130> dpp_auth_init peer=<qr-code-id> conf=<ap-dpp|sta-dpp> ssid=<SSID hexdump> configurator=<configurator-id>
131or for legacy (PSK/SAE) provisioning for a station Enrollee:
132> dpp_auth_init peer=<qr-code-id> conf=sta-psk ssid=<SSID hexdump> pass=<passphrase hexdump>
133
134The DPP values will be printed in the console. Save these values into the
135config file. If the Enrollee is an AP, we need to manually write these
136values to the hostapd config file. If the Enrollee is a client device,
137these details can be automatically saved to config file using the
138following command.
139
140> save_config
141
142To set values in runtime for AP enrollees
143
144> set dpp_connector <Connector-value-printed-on-console>
145> set dpp_csign <csign-value-on-console>
146> set dpp_netaccesskey <netaccess-value-on-console>
147
148To set values in runtime for client enrollees, set dpp_config_processing
149to 2 in wpa_supplicant conf file.
150
151Once the values are set in run-time (if not set in run-time, but saved
152in config files, they are taken up in next restart), the client device
153will automatically connect to the already provisioned AP and connection
154will be established.
155
156
157Self-configuring a device
158-------------------------
159
160It is possible for a device to configure itself if it is the
161Configurator for the network.
162
163Create a Configurator in the device and use the dpp_configurator_sign
164command to get DPP credentials.
165
166> dpp_configurator_add
167(returns configurator id)
168> dpp_configurator_sign conf=<ap-dpp|sta-dpp> configurator=<configurator-id> ssid=<SSID hexdump>
169
170
171Sample AP configuration files after provisioning
172------------------------------------------------
173
174interface=wlan0
175driver=nl80211
176ctrl_interface=/var/run/hostapd
177ssid=test
178channel=1
179wpa=2
180wpa_key_mgmt=DPP
181ieee80211w=1
182wpa_pairwise=CCMP
183rsn_pairwise=CCMP
184dpp_connector=<Connector value provided by Configurator>
185dpp_csign=<C-Sign-Key value provided by Configurator>
186dpp_netaccesskey=<Net access key provided by Configurator>
187
188
189Sample station configuration file after provisioning
190----------------------------------------------------
191
192ctrl_interface=DIR=/var/run/wpa_supplicant
193ctrl_interface_group=0
194update_config=1
195pmf=2
196dpp_config_processing=2
197network={
198	ssid="test"
199	key_mgmt=DPP
200	ieee80211w=2
201	dpp_connector="<Connector value provided by Configurator>"
202	dpp_netaccesskey=<Net access key provided by Configurator>
203	dpp_csign=<C-sign-key value provided by Configurator>
204}
205