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