]>
Commit | Line | Data |
---|---|---|
bd034191 JM |
1 | wpa_supplicant and Wi-Fi Protected Setup (WPS) |
2 | ============================================== | |
3 | ||
4 | This document describes how the WPS implementation in wpa_supplicant | |
5 | can be configured and how an external component on the client (e.g., | |
6 | management GUI) is used to enable WPS enrollment and registrar | |
7 | registration. | |
8 | ||
9 | ||
10 | Introduction to WPS | |
11 | ------------------- | |
12 | ||
13 | Wi-Fi Protected Setup (WPS) is a mechanism for easy configuration of a | |
14 | wireless network. It allows automated generation of random keys (WPA | |
15 | passphrase/PSK) and configuration of an access point and client | |
16 | devices. WPS includes number of methods for setting up connections | |
17 | with PIN method and push-button configuration (PBC) being the most | |
18 | commonly deployed options. | |
19 | ||
20 | While WPS can enable more home networks to use encryption in the | |
21 | wireless network, it should be noted that the use of the PIN and | |
22 | especially PBC mechanisms for authenticating the initial key setup is | |
23 | not very secure. As such, use of WPS may not be suitable for | |
24 | environments that require secure network access without chance for | |
25 | allowing outsiders to gain access during the setup phase. | |
26 | ||
27 | WPS uses following terms to describe the entities participating in the | |
28 | network setup: | |
29 | - access point: the WLAN access point | |
30 | - Registrar: a device that control a network and can authorize | |
31 | addition of new devices); this may be either in the AP ("internal | |
32 | Registrar") or in an external device, e.g., a laptop, ("external | |
33 | Registrar") | |
34 | - Enrollee: a device that is being authorized to use the network | |
35 | ||
36 | It should also be noted that the AP and a client device may change | |
37 | roles (i.e., AP acts as an Enrollee and client device as a Registrar) | |
38 | when WPS is used to configure the access point. | |
39 | ||
40 | ||
41 | More information about WPS is available from Wi-Fi Alliance: | |
42 | http://www.wi-fi.org/wifi-protected-setup | |
43 | ||
44 | ||
45 | wpa_supplicant implementation | |
46 | ----------------------------- | |
47 | ||
48 | wpa_supplicant includes an optional WPS component that can be used as | |
49 | an Enrollee to enroll new network credential or as a Registrar to | |
eec92ec5 | 50 | configure an AP. |
bd034191 JM |
51 | |
52 | ||
53 | wpa_supplicant configuration | |
54 | ---------------------------- | |
55 | ||
56 | WPS is an optional component that needs to be enabled in | |
57 | wpa_supplicant build configuration (.config). Here is an example | |
ee8ad5d8 JM |
58 | configuration that includes WPS support and Linux nl80211 -based |
59 | driver interface: | |
bd034191 | 60 | |
ee8ad5d8 | 61 | CONFIG_DRIVER_NL80211=y |
bd034191 | 62 | CONFIG_WPS=y |
53587ec1 | 63 | CONFIG_WPS2=y |
bd034191 | 64 | |
4aced422 JM |
65 | If you want to enable WPS external registrar (ER) functionality, you |
66 | will also need to add following line: | |
67 | ||
68 | CONFIG_WPS_ER=y | |
69 | ||
51ca03f4 JM |
70 | Following parameter can be used to enable support for NFC config method: |
71 | ||
72 | CONFIG_WPS_NFC=y | |
73 | ||
bd034191 JM |
74 | |
75 | WPS needs the Universally Unique IDentifier (UUID; see RFC 4122) for | |
76 | the device. This is configured in the runtime configuration for | |
79da74a2 JM |
77 | wpa_supplicant (if not set, UUID will be generated based on local MAC |
78 | address): | |
bd034191 JM |
79 | |
80 | # example UUID for WPS | |
81 | uuid=12345678-9abc-def0-1234-56789abcdef0 | |
82 | ||
83 | The network configuration blocks needed for WPS are added | |
84 | automatically based on control interface commands, so they do not need | |
85 | to be added explicitly in the configuration file. | |
86 | ||
30f5c941 JM |
87 | WPS registration will generate new network blocks for the acquired |
88 | credentials. If these are to be stored for future use (after | |
89 | restarting wpa_supplicant), wpa_supplicant will need to be configured | |
90 | to allow configuration file updates: | |
91 | ||
92 | update_config=1 | |
93 | ||
94 | ||
bd034191 JM |
95 | |
96 | External operations | |
97 | ------------------- | |
98 | ||
99 | WPS requires either a device PIN code (usually, 8-digit number) or a | |
100 | pushbutton event (for PBC) to allow a new WPS Enrollee to join the | |
101 | network. wpa_supplicant uses the control interface as an input channel | |
102 | for these events. | |
103 | ||
3981cb3c JM |
104 | The PIN value used in the commands must be processed by an UI to |
105 | remove non-digit characters and potentially, to verify the checksum | |
106 | digit. "wpa_cli wps_check_pin <PIN>" can be used to do such processing. | |
107 | It returns FAIL if the PIN is invalid, or FAIL-CHECKSUM if the checksum | |
108 | digit is incorrect, or the processed PIN (non-digit characters removed) | |
109 | if the PIN is valid. | |
110 | ||
bd034191 JM |
111 | If the client device has a display, a random PIN has to be generated |
112 | for each WPS registration session. wpa_supplicant can do this with a | |
113 | control interface request, e.g., by calling wpa_cli: | |
114 | ||
115 | wpa_cli wps_pin any | |
116 | ||
117 | This will return the generated 8-digit PIN which will then need to be | |
118 | entered at the Registrar to complete WPS registration. At that point, | |
119 | the client will be enrolled with credentials needed to connect to the | |
120 | AP to access the network. | |
121 | ||
122 | ||
123 | If the client device does not have a display that could show the | |
124 | random PIN, a hardcoded PIN that is printed on a label can be | |
125 | used. wpa_supplicant is notified this with a control interface | |
126 | request, e.g., by calling wpa_cli: | |
127 | ||
128 | wpa_cli wps_pin any 12345670 | |
129 | ||
130 | This starts the WPS negotiation in the same way as above with the | |
131 | generated PIN. | |
132 | ||
c423708f JM |
133 | When the wps_pin command is issued for an AP (including P2P GO) mode |
134 | interface, an optional timeout parameter can be used to specify | |
135 | expiration timeout for the PIN in seconds. For example: | |
136 | ||
137 | wpa_cli wps_pin any 12345670 300 | |
138 | ||
bd034191 | 139 | |
98aa7ca5 JM |
140 | If a random PIN is needed for a user interface, "wpa_cli wps_pin get" |
141 | can be used to generate a new PIN without starting WPS negotiation. | |
142 | This random PIN can then be passed as an argument to another wps_pin | |
143 | call when the actual operation should be started. | |
144 | ||
bd034191 JM |
145 | If the client design wants to support optional WPS PBC mode, this can |
146 | be enabled by either a physical button in the client device or a | |
147 | virtual button in the user interface. The PBC operation requires that | |
148 | a button is also pressed at the AP/Registrar at about the same time (2 | |
149 | minute window). wpa_supplicant is notified of the local button event | |
150 | over the control interface, e.g., by calling wpa_cli: | |
151 | ||
152 | wpa_cli wps_pbc | |
153 | ||
154 | At this point, the AP/Registrar has two minutes to complete WPS | |
155 | negotiation which will generate a new WPA PSK in the same way as the | |
156 | PIN method described above. | |
157 | ||
158 | ||
52eb293d JM |
159 | If the client wants to operate in the Registrar role to learn the |
160 | current AP configuration and optionally, to configure an AP, | |
161 | wpa_supplicant is notified over the control interface, e.g., with | |
bd034191 JM |
162 | wpa_cli: |
163 | ||
164 | wpa_cli wps_reg <AP BSSID> <AP PIN> | |
165 | (example: wpa_cli wps_reg 02:34:56:78:9a:bc 12345670) | |
eef7d7a1 | 166 | |
52eb293d JM |
167 | This is used to fetch the current AP settings instead of actually |
168 | changing them. The main difference with the wps_pin command is that | |
169 | wps_reg uses the AP PIN (e.g., from a label on the AP) instead of a | |
170 | PIN generated at the client. | |
171 | ||
172 | In order to change the AP configuration, the new configuration | |
173 | parameters are given to the wps_reg command: | |
174 | ||
175 | wpa_cli wps_reg <AP BSSID> <AP PIN> <new SSID> <auth> <encr> <new key> | |
176 | examples: | |
177 | wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 testing WPA2PSK CCMP 12345678 | |
178 | wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 clear OPEN NONE "" | |
179 | ||
180 | <auth> must be one of the following: OPEN WPAPSK WPA2PSK | |
181 | <encr> must be one of the following: NONE WEP TKIP CCMP | |
4625a47f | 182 | |
eef7d7a1 JM |
183 | |
184 | Scanning | |
185 | -------- | |
186 | ||
187 | Scan results ('wpa_cli scan_results' or 'wpa_cli bss <idx>') include a | |
188 | flags field that is used to indicate whether the BSS support WPS. If | |
189 | the AP support WPS, but has not recently activated a Registrar, [WPS] | |
190 | flag will be included. If PIN method has been recently selected, | |
191 | [WPS-PIN] is shown instead. Similarly, [WPS-PBC] is shown if PBC mode | |
192 | is in progress. GUI programs can use these as triggers for suggesting | |
f9e4465c JM |
193 | a guided WPS configuration to the user. In addition, control interface |
194 | monitor events WPS-AP-AVAILABLE{,-PBC,-PIN} can be used to find out if | |
195 | there are WPS enabled APs in scan results without having to go through | |
196 | all the details in the GUI. These notification could be used, e.g., to | |
197 | suggest possible WPS connection to the user. | |
198 | ||
199 | ||
200 | wpa_gui | |
201 | ------- | |
202 | ||
203 | wpa_gui-qt4 directory contains a sample GUI that shows an example of | |
204 | how WPS support can be integrated into the GUI. Its main window has a | |
205 | WPS tab that guides user through WPS registration with automatic AP | |
206 | selection. In addition, it shows how WPS can be started manually by | |
207 | selecting an AP from scan results. | |
695e2b48 JM |
208 | |
209 | ||
210 | Credential processing | |
211 | --------------------- | |
212 | ||
213 | By default, wpa_supplicant processes received credentials and updates | |
214 | its configuration internally. However, it is possible to | |
215 | control these operations from external programs, if desired. | |
216 | ||
217 | This internal processing can be disabled with wps_cred_processing=1 | |
218 | option. When this is used, an external program is responsible for | |
219 | processing the credential attributes and updating wpa_supplicant | |
220 | configuration based on them. | |
221 | ||
222 | Following control interface messages are sent out for external programs: | |
223 | ||
224 | WPS-CRED-RECEIVED <hexdump of Credential attribute(s)> | |
225 | For example: | |
226 | <2>WPS-CRED-RECEIVED 100e006f10260001011045000c6a6b6d2d7770732d74657374100300020020100f000200081027004030653462303435366332363666653064333961643135353461316634626637313234333761636664623766333939653534663166316230323061643434386235102000060266a0ee1727 | |
3085b805 JM |
227 | |
228 | ||
229 | wpa_supplicant as WPS External Registrar (ER) | |
230 | --------------------------------------------- | |
231 | ||
232 | wpa_supplicant can be used as a WPS ER to configure an AP or enroll | |
233 | new Enrollee to join the network. This functionality uses UPnP and | |
234 | requires that a working IP connectivity is available with the AP (this | |
235 | can be either over a wired or wireless connection). | |
236 | ||
237 | Separate wpa_supplicant process can be started for WPS ER | |
238 | operations. A special "none" driver can be used in such a case to | |
239 | indicate that no local network interface is actually controlled. For | |
240 | example, following command could be used to start the ER: | |
241 | ||
242 | wpa_supplicant -Dnone -c er.conf -ieth0 | |
243 | ||
244 | Sample er.conf: | |
245 | ||
246 | ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=admin | |
247 | device_name=WPS External Registrar | |
248 | ||
249 | ||
250 | wpa_cli commands for ER functionality: | |
251 | ||
252 | wps_er_start [IP address] | |
253 | - start WPS ER functionality | |
254 | - the optional IP address parameter can be used to filter operations only | |
255 | to include a single AP | |
256 | - if run again while ER is active, the stored information (discovered APs | |
257 | and Enrollees) are shown again | |
258 | ||
259 | wps_er_stop | |
260 | - stop WPS ER functionality | |
261 | ||
59307b30 | 262 | wps_er_learn <UUID|BSSID> <AP PIN> |
3085b805 JM |
263 | - learn AP configuration |
264 | ||
59307b30 | 265 | wps_er_set_config <UUID|BSSID> <network id> |
ef10f473 JM |
266 | - use AP configuration from a locally configured network (e.g., from |
267 | wps_reg command); this does not change the AP's configuration, but | |
268 | only prepares a configuration to be used when enrolling a new device | |
269 | to the AP | |
270 | ||
59307b30 | 271 | wps_er_config <UUID|BSSID> <AP PIN> <new SSID> <auth> <encr> <new key> |
7d6640a6 JM |
272 | - examples: |
273 | wps_er_config 87654321-9abc-def0-1234-56789abc0002 12345670 testing WPA2PSK CCMP 12345678 | |
274 | wpa_er_config 87654321-9abc-def0-1234-56789abc0002 12345670 clear OPEN NONE "" | |
275 | ||
276 | <auth> must be one of the following: OPEN WPAPSK WPA2PSK | |
277 | <encr> must be one of the following: NONE WEP TKIP CCMP | |
278 | ||
279 | ||
e205401c | 280 | wps_er_pbc <Enrollee UUID|MAC address> |
3085b805 JM |
281 | - accept an Enrollee PBC using External Registrar |
282 | ||
e205401c | 283 | wps_er_pin <Enrollee UUID|"any"|MAC address> <PIN> [Enrollee MAC address] |
3085b805 | 284 | - add an Enrollee PIN to External Registrar |
95ee81e4 JM |
285 | - if Enrollee UUID is not known, "any" can be used to add a wildcard PIN |
286 | - if the MAC address of the enrollee is known, it should be configured | |
287 | to allow the AP to advertise list of authorized enrollees | |
3085b805 JM |
288 | |
289 | ||
290 | WPS ER events: | |
291 | ||
292 | WPS_EVENT_ER_AP_ADD | |
293 | - WPS ER discovered an AP | |
294 | ||
295 | WPS-ER-AP-ADD 87654321-9abc-def0-1234-56789abc0002 02:11:22:33:44:55 pri_dev_type=6-0050F204-1 wps_state=1 |Very friendly name|Company|Long description of the model|WAP|http://w1.fi/|http://w1.fi/hostapd/ | |
296 | ||
297 | WPS_EVENT_ER_AP_REMOVE | |
298 | - WPS ER removed an AP entry | |
299 | ||
300 | WPS-ER-AP-REMOVE 87654321-9abc-def0-1234-56789abc0002 | |
301 | ||
302 | WPS_EVENT_ER_ENROLLEE_ADD | |
303 | - WPS ER discovered a new Enrollee | |
304 | ||
305 | WPS-ER-ENROLLEE-ADD 2b7093f1-d6fb-5108-adbb-bea66bb87333 02:66:a0:ee:17:27 M1=1 config_methods=0x14d dev_passwd_id=0 pri_dev_type=1-0050F204-1 |Wireless Client|Company|cmodel|123|12345| | |
306 | ||
307 | WPS_EVENT_ER_ENROLLEE_REMOVE | |
308 | - WPS ER removed an Enrollee entry | |
309 | ||
310 | WPS-ER-ENROLLEE-REMOVE 2b7093f1-d6fb-5108-adbb-bea66bb87333 02:66:a0:ee:17:27 | |
311 | ||
312 | WPS-ER-AP-SETTINGS | |
313 | - WPS ER learned AP settings | |
314 | ||
315 | WPS-ER-AP-SETTINGS uuid=fd91b4ec-e3fa-5891-a57d-8c59efeed1d2 ssid=test-wps auth_type=0x0020 encr_type=0x0008 key=12345678 | |
51ca03f4 JM |
316 | |
317 | ||
318 | WPS with NFC | |
319 | ------------ | |
320 | ||
321 | WPS can be used with NFC-based configuration method. An NFC tag | |
322 | containing a password token from the Enrollee can be used to | |
323 | authenticate the connection instead of the PIN. In addition, an NFC tag | |
324 | with a configuration token can be used to transfer AP settings without | |
325 | going through the WPS protocol. | |
326 | ||
327 | When the station acts as an Enrollee, a local NFC tag with a password | |
328 | token can be used by touching the NFC interface of a Registrar. | |
329 | ||
330 | "wps_nfc [BSSID]" command starts WPS protocol run with the local end as | |
331 | the Enrollee using the NFC password token that is either pre-configured | |
332 | in the configuration file (wps_nfc_dev_pw_id, wps_nfc_dh_pubkey, | |
333 | wps_nfc_dh_privkey, wps_nfc_dev_pw) or generated dynamically with | |
334 | "wps_nfc_token <WPS|NDEF>" command. The included nfc_pw_token tool | |
335 | (build with "make nfc_pw_token") can be used to generate NFC password | |
336 | tokens during manufacturing (each station needs to have its own random | |
337 | keys). | |
338 | ||
bbf41865 JM |
339 | The "wps_nfc_config_token <WPS/NDEF>" command can be used to build an |
340 | NFC configuration token when wpa_supplicant is controlling an AP | |
341 | interface (AP or P2P GO). The output value from this command is a | |
342 | hexdump of the current AP configuration (WPS parameter requests this to | |
343 | include only the WPS attributes; NDEF parameter requests additional NDEF | |
344 | encapsulation to be included). This data needs to be written to an NFC | |
345 | tag with an external program. Once written, the NFC configuration token | |
346 | can be used to touch an NFC interface on a station to provision the | |
347 | credentials needed to access the network. | |
348 | ||
88c8bf31 JM |
349 | The "wps_nfc_config_token <WPS/NDEF> <network id>" command can be used |
350 | to build an NFC configuration token based on a locally configured | |
351 | network. | |
352 | ||
51ca03f4 JM |
353 | If the station includes NFC interface and reads an NFC tag with a MIME |
354 | media type "application/vnd.wfa.wsc", the NDEF message payload (with or | |
355 | without NDEF encapsulation) can be delivered to wpa_supplicant using the | |
356 | following wpa_cli command: | |
357 | ||
358 | wps_nfc_tag_read <hexdump of payload> | |
359 | ||
360 | If the NFC tag contains a configuration token, the network is added to | |
361 | wpa_supplicant configuration. If the NFC tag contains a password token, | |
362 | the token is added to the WPS Registrar component. This information can | |
363 | then be used with wps_reg command (when the NFC password token was from | |
364 | an AP) using a special value "nfc-pw" in place of the PIN parameter. If | |
365 | the ER functionality has been started (wps_er_start), the NFC password | |
366 | token is used to enable enrollment of a new station (that was the source | |
367 | of the NFC password token). | |
e65552dd JM |
368 | |
369 | "nfc_get_handover_req <NDEF> <WPS>" command can be used to build the | |
370 | contents of a Handover Request Message for connection handover. The | |
371 | first argument selects the format of the output data and the second | |
372 | argument selects which type of connection handover is requested (WPS = | |
373 | Wi-Fi handover as specified in WSC 2.0). | |
374 | ||
c44a19c1 JM |
375 | "nfc_get_handover_sel <NDEF> <WPS> [UUID|BSSID]" command can be used to |
376 | build the contents of a Handover Select Message for connection handover | |
377 | when this does not depend on the contents of the Handover Request | |
378 | Message. The first argument selects the format of the output data and | |
379 | the second argument selects which type of connection handover is | |
380 | requested (WPS = Wi-Fi handover as specified in WSC 2.0). If the options | |
381 | UUID|BSSID argument is included, this is a request to build the handover | |
382 | message for the specified AP when wpa_supplicant is operating as a WPS | |
383 | ER. | |
e65552dd JM |
384 | |
385 | "nfc_rx_handover_req <hexdump of payload>" is used to indicate receipt | |
386 | of NFC connection handover request. The payload may include multiple | |
387 | carriers the the applicable ones are matched based on the media | |
388 | type. The reply data is contents for the Handover Select Message | |
389 | (hexdump). | |
390 | ||
391 | "nfc_rx_handover_sel <hexdump of payload>" is used to indicate receipt | |
392 | of NFC connection handover select. The payload may include multiple | |
393 | carriers the the applicable ones are matched based on the media | |
394 | type. | |
7bfe2777 JM |
395 | |
396 | "nfc_report_handover <INIT/RESP> WPS <carrier from handover request> | |
397 | <carrier from handover select>" can be used as an alternative way for | |
398 | reporting completed NFC connection handover. The first parameter | |
399 | indicates whether the local device initiated or responded to the | |
400 | connection handover and the carrier records are the selected carrier | |
401 | from the handover request and select messages as a hexdump. | |
c44a19c1 JM |
402 | |
403 | The "wps_er_nfc_config_token <WPS/NDEF> <UUID|BSSID>" command can be | |
404 | used to build an NFC configuration token for the specified AP when | |
405 | wpa_supplicant is operating as a WPS ER. The output value from this | |
406 | command is a hexdump of the selected AP configuration (WPS parameter | |
407 | requests this to include only the WPS attributes; NDEF parameter | |
408 | requests additional NDEF encapsulation to be included). This data needs | |
409 | to be written to an NFC tag with an external program. Once written, the | |
410 | NFC configuration token can be used to touch an NFC interface on a | |
411 | station to provision the credentials needed to access the network. |