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