]>
Commit | Line | Data |
---|---|---|
ad08c363 JM |
1 | hostapd and Wi-Fi Protected Setup (WPS) |
2 | ======================================= | |
3 | ||
4 | This document describes how the WPS implementation in hostapd can be | |
5 | configured and how an external component on an AP (e.g., web UI) is | |
6 | used to enable enrollment of client devices. | |
7 | ||
8 | ||
9 | Introduction to WPS | |
10 | ------------------- | |
11 | ||
12 | Wi-Fi Protected Setup (WPS) is a mechanism for easy configuration of a | |
13 | wireless network. It allows automated generation of random keys (WPA | |
14 | passphrase/PSK) and configuration of an access point and client | |
15 | devices. WPS includes number of methods for setting up connections | |
16 | with PIN method and push-button configuration (PBC) being the most | |
17 | commonly deployed options. | |
18 | ||
19 | While WPS can enable more home networks to use encryption in the | |
20 | wireless network, it should be noted that the use of the PIN and | |
21 | especially PBC mechanisms for authenticating the initial key setup is | |
22 | not very secure. As such, use of WPS may not be suitable for | |
23 | environments that require secure network access without chance for | |
24 | allowing outsiders to gain access during the setup phase. | |
25 | ||
26 | WPS uses following terms to describe the entities participating in the | |
27 | network setup: | |
28 | - access point: the WLAN access point | |
29 | - Registrar: a device that control a network and can authorize | |
30 | addition of new devices); this may be either in the AP ("internal | |
31 | Registrar") or in an external device, e.g., a laptop, ("external | |
32 | Registrar") | |
33 | - Enrollee: a device that is being authorized to use the network | |
34 | ||
35 | It should also be noted that the AP and a client device may change | |
36 | roles (i.e., AP acts as an Enrollee and client device as a Registrar) | |
37 | when WPS is used to configure the access point. | |
38 | ||
39 | ||
40 | More information about WPS is available from Wi-Fi Alliance: | |
41 | http://www.wi-fi.org/wifi-protected-setup | |
42 | ||
43 | ||
44 | hostapd implementation | |
45 | ---------------------- | |
46 | ||
47 | hostapd includes an optional WPS component that can be used as an | |
48 | internal WPS Registrar to manage addition of new WPS enabled clients | |
49 | to the network. In addition, WPS Enrollee functionality in hostapd can | |
50 | be used to allow external WPS Registrars to configure the access | |
c5e1522f JM |
51 | point, e.g., for initial network setup. In addition, hostapd can proxy a |
52 | WPS registration between a wireless Enrollee and an external Registrar | |
53 | (e.g., Microsoft Vista or Atheros JumpStart) with UPnP. | |
ad08c363 JM |
54 | |
55 | ||
56 | hostapd configuration | |
57 | --------------------- | |
58 | ||
59 | WPS is an optional component that needs to be enabled in hostapd build | |
60 | configuration (.config). Here is an example configuration that | |
01b32d5e | 61 | includes WPS support and uses nl80211 driver interface: |
ad08c363 | 62 | |
01b32d5e | 63 | CONFIG_DRIVER_NL80211=y |
ad08c363 | 64 | CONFIG_WPS=y |
c5e1522f | 65 | CONFIG_WPS_UPNP=y |
ad08c363 | 66 | |
51ca03f4 JM |
67 | Following parameter can be used to enable support for NFC config method: |
68 | ||
69 | CONFIG_WPS_NFC=y | |
70 | ||
ad08c363 JM |
71 | |
72 | Following section shows an example runtime configuration | |
73 | (hostapd.conf) that enables WPS: | |
74 | ||
75 | # Configure the driver and network interface | |
01b32d5e JM |
76 | driver=nl80211 |
77 | interface=wlan0 | |
ad08c363 JM |
78 | |
79 | # WPA2-Personal configuration for the AP | |
80 | ssid=wps-test | |
81 | wpa=2 | |
82 | wpa_key_mgmt=WPA-PSK | |
83 | wpa_pairwise=CCMP | |
84 | # Default WPA passphrase for legacy (non-WPS) clients | |
85 | wpa_passphrase=12345678 | |
86 | # Enable random per-device PSK generation for WPS clients | |
87 | # Please note that the file has to exists for hostapd to start (i.e., create an | |
88 | # empty file as a starting point). | |
89 | wpa_psk_file=/etc/hostapd.psk | |
90 | ||
91 | # Enable control interface for PBC/PIN entry | |
92 | ctrl_interface=/var/run/hostapd | |
93 | ||
94 | # Enable internal EAP server for EAP-WSC (part of Wi-Fi Protected Setup) | |
95 | eap_server=1 | |
96 | ||
97 | # WPS configuration (AP configured, do not allow external WPS Registrars) | |
98 | wps_state=2 | |
99 | ap_setup_locked=1 | |
79da74a2 | 100 | # If UUID is not configured, it will be generated based on local MAC address. |
ad08c363 JM |
101 | uuid=87654321-9abc-def0-1234-56789abc0000 |
102 | wps_pin_requests=/var/run/hostapd.pin-req | |
103 | device_name=Wireless AP | |
104 | manufacturer=Company | |
105 | model_name=WAP | |
106 | model_number=123 | |
107 | serial_number=12345 | |
108 | device_type=6-0050F204-1 | |
109 | os_version=01020300 | |
110 | config_methods=label display push_button keypad | |
111 | ||
c5e1522f JM |
112 | # if external Registrars are allowed, UPnP support could be added: |
113 | #upnp_iface=br0 | |
114 | #friendly_name=WPS Access Point | |
115 | ||
ad08c363 JM |
116 | |
117 | External operations | |
118 | ------------------- | |
119 | ||
120 | WPS requires either a device PIN code (usually, 8-digit number) or a | |
121 | pushbutton event (for PBC) to allow a new WPS Enrollee to join the | |
122 | network. hostapd uses the control interface as an input channel for | |
123 | these events. | |
124 | ||
3981cb3c JM |
125 | The PIN value used in the commands must be processed by an UI to |
126 | remove non-digit characters and potentially, to verify the checksum | |
127 | digit. "hostapd_cli wps_check_pin <PIN>" can be used to do such | |
128 | processing. It returns FAIL if the PIN is invalid, or FAIL-CHECKSUM if | |
129 | the checksum digit is incorrect, or the processed PIN (non-digit | |
130 | characters removed) if the PIN is valid. | |
131 | ||
ad08c363 JM |
132 | When a client device (WPS Enrollee) connects to hostapd (WPS |
133 | Registrar) in order to start PIN mode negotiation for WPS, an | |
134 | identifier (Enrollee UUID) is sent. hostapd will need to be configured | |
135 | with a device password (PIN) for this Enrollee. This is an operation | |
136 | that requires user interaction (assuming there are no pre-configured | |
137 | PINs on the AP for a set of Enrollee). | |
138 | ||
139 | The PIN request with information about the device is appended to the | |
140 | wps_pin_requests file (/var/run/hostapd.pin-req in this example). In | |
141 | addition, hostapd control interface event is sent as a notification of | |
142 | a new device. The AP could use, e.g., a web UI for showing active | |
143 | Enrollees to the user and request a PIN for an Enrollee. | |
144 | ||
145 | The PIN request file has one line for every Enrollee that connected to | |
146 | the AP, but for which there was no PIN. Following information is | |
147 | provided for each Enrollee (separated with tabulators): | |
148 | - timestamp (seconds from 1970-01-01) | |
149 | - Enrollee UUID | |
150 | - MAC address | |
151 | - Device name | |
152 | - Manufacturer | |
153 | - Model Name | |
154 | - Model Number | |
155 | - Serial Number | |
156 | - Device category | |
157 | ||
158 | Example line in the /var/run/hostapd.pin-req file: | |
159 | 1200188391 53b63a98-d29e-4457-a2ed-094d7e6a669c Intel(R) Centrino(R) Intel Corporation Intel(R) Centrino(R) - - 1-0050F204-1 | |
160 | ||
695e2b48 JM |
161 | Control interface data: |
162 | WPS-PIN-NEEDED [UUID-E|MAC Address|Device Name|Manufacturer|Model Name|Model Number|Serial Number|Device Category] | |
163 | For example: | |
164 | <2>WPS-PIN-NEEDED [53b63a98-d29e-4457-a2ed-094d7e6a669c|02:12:34:56:78:9a|Device|Manuf|Model|Model Number|Serial Number|1-0050F204-1] | |
ad08c363 JM |
165 | |
166 | When the user enters a PIN for a pending Enrollee, e.g., on the web | |
167 | UI), hostapd needs to be notified of the new PIN over the control | |
168 | interface. This can be done either by using the UNIX domain socket | |
169 | -based control interface directly (src/common/wpa_ctrl.c provides | |
170 | helper functions for using the interface) or by calling hostapd_cli. | |
171 | ||
172 | Example command to add a PIN (12345670) for an Enrollee: | |
173 | ||
174 | hostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c 12345670 | |
175 | ||
08bec361 | 176 | If the UUID-E is not available (e.g., Enrollee waits for the Registrar |
077a781f JM |
177 | to be selected before connecting), wildcard UUID may be used to allow |
178 | the PIN to be used once with any UUID: | |
08bec361 JM |
179 | |
180 | hostapd_cli wps_pin any 12345670 | |
181 | ||
077a781f JM |
182 | To reduce likelihood of PIN being used with other devices or of |
183 | forgetting an active PIN available for potential attackers, expiration | |
31fcea93 JM |
184 | time in seconds can be set for the new PIN (value 0 indicates no |
185 | expiration): | |
077a781f JM |
186 | |
187 | hostapd_cli wps_pin any 12345670 300 | |
188 | ||
31fcea93 JM |
189 | If the MAC address of the enrollee is known, it should be configured |
190 | to allow the AP to advertise list of authorized enrollees: | |
191 | ||
192 | hostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c \ | |
193 | 12345670 300 00:11:22:33:44:55 | |
194 | ||
08bec361 | 195 | |
ad08c363 JM |
196 | After this, the Enrollee can connect to the AP again and complete WPS |
197 | negotiation. At that point, a new, random WPA PSK is generated for the | |
198 | client device and the client can then use that key to connect to the | |
199 | AP to access the network. | |
200 | ||
201 | ||
202 | If the AP includes a pushbutton, WPS PBC mode can be used. It is | |
203 | enabled by pushing a button on both the AP and the client at about the | |
204 | same time (2 minute window). hostapd needs to be notified about the AP | |
205 | button pushed event over the control interface, e.g., by calling | |
206 | hostapd_cli: | |
207 | ||
208 | hostapd_cli wps_pbc | |
209 | ||
210 | At this point, the client has two minutes to complete WPS negotiation | |
211 | which will generate a new WPA PSK in the same way as the PIN method | |
212 | described above. | |
695e2b48 JM |
213 | |
214 | ||
5a1cc30f JM |
215 | When an external Registrar is used, the AP can act as an Enrollee and |
216 | use its AP PIN. A static AP PIN (e.g., one one a label in the AP | |
217 | device) can be configured in hostapd.conf (ap_pin parameter). A more | |
218 | secure option is to use hostapd_cli wps_ap_pin command to enable the | |
219 | AP PIN only based on user action (and even better security by using a | |
220 | random AP PIN for each session, i.e., by using "wps_ap_pin random" | |
221 | command with a timeout value). Following commands are available for | |
222 | managing the dynamic AP PIN operations: | |
223 | ||
224 | hostapd_cli wps_ap_pin disable | |
225 | - disable AP PIN (i.e., do not allow external Registrars to use it to | |
226 | learn the current AP settings or to reconfigure the AP) | |
227 | ||
228 | hostapd_cli wps_ap_pin random [timeout] | |
229 | - generate a random AP PIN and enable it | |
230 | - if the optional timeout parameter is given, the AP PIN will be enabled | |
231 | for the specified number of seconds | |
232 | ||
233 | hostapd_cli wps_ap_pin get | |
234 | - fetch the current AP PIN | |
235 | ||
236 | hostapd_cli wps_ap_pin set <PIN> [timeout] | |
237 | - set the AP PIN and enable it | |
238 | - if the optional timeout parameter is given, the AP PIN will be enabled | |
239 | for the specified number of seconds | |
240 | ||
403b96fe JM |
241 | hostapd_cli get_config |
242 | - display the current configuration | |
243 | ||
450eddcf JM |
244 | hostapd_cli wps_config <new SSID> <auth> <encr> <new key> |
245 | examples: | |
246 | hostapd_cli wps_config testing WPA2PSK CCMP 12345678 | |
247 | hostapd_cli wps_config "no security" OPEN NONE "" | |
248 | ||
249 | <auth> must be one of the following: OPEN WPAPSK WPA2PSK | |
250 | <encr> must be one of the following: NONE WEP TKIP CCMP | |
251 | ||
5a1cc30f | 252 | |
695e2b48 JM |
253 | Credential generation and configuration changes |
254 | ----------------------------------------------- | |
255 | ||
256 | By default, hostapd generates credentials for Enrollees and processing | |
257 | AP configuration updates internally. However, it is possible to | |
258 | control these operations from external programs, if desired. | |
259 | ||
260 | The internal credential generation can be disabled with | |
261 | skip_cred_build=1 option in the configuration. extra_cred option will | |
262 | then need to be used to provide pre-configured Credential attribute(s) | |
263 | for hostapd to use. The exact data from this binary file will be sent, | |
264 | i.e., it will have to include valid WPS attributes. extra_cred can | |
265 | also be used to add additional networks if the Registrar is used to | |
266 | configure credentials for multiple networks. | |
267 | ||
268 | Processing of received configuration updates can be disabled with | |
269 | wps_cred_processing=1 option. When this is used, an external program | |
270 | is responsible for creating hostapd configuration files and processing | |
271 | configuration updates based on messages received from hostapd over | |
272 | control interface. This will also include the initial configuration on | |
273 | first successful registration if the AP is initially set in | |
274 | unconfigured state. | |
275 | ||
276 | Following control interface messages are sent out for external programs: | |
277 | ||
278 | WPS-REG-SUCCESS <Enrollee MAC address <UUID-E> | |
279 | For example: | |
280 | <2>WPS-REG-SUCCESS 02:66:a0:ee:17:27 2b7093f1-d6fb-5108-adbb-bea66bb87333 | |
281 | ||
61fbd3df | 282 | This can be used to trigger change from unconfigured to configured |
695e2b48 JM |
283 | state (random configuration based on the first successful WPS |
284 | registration). In addition, this can be used to update AP UI about the | |
285 | status of WPS registration progress. | |
286 | ||
287 | ||
288 | WPS-NEW-AP-SETTINGS <hexdump of AP Setup attributes> | |
289 | For example: | |
290 | <2>WPS-NEW-AP-SETTINGS 10260001011045000c6a6b6d2d7770732d74657374100300020020100f00020008102700403065346230343536633236366665306433396164313535346131663462663731323433376163666462376633393965353466316631623032306164343438623510200006024231cede15101e000844 | |
291 | ||
292 | This can be used to update the externally stored AP configuration and | |
293 | then update hostapd configuration (followed by restarting of hostapd). | |
51ca03f4 JM |
294 | |
295 | ||
296 | WPS with NFC | |
297 | ------------ | |
298 | ||
299 | WPS can be used with NFC-based configuration method. An NFC tag | |
300 | containing a password token from the Enrollee can be used to | |
301 | authenticate the connection instead of the PIN. In addition, an NFC tag | |
302 | with a configuration token can be used to transfer AP settings without | |
303 | going through the WPS protocol. | |
304 | ||
305 | When the AP acts as an Enrollee, a local NFC tag with a password token | |
306 | can be used by touching the NFC interface of an external Registrar. The | |
307 | wps_nfc_token command is used to manage use of the NFC password token | |
308 | from the AP. "wps_nfc_token enable" enables the use of the AP's NFC | |
309 | password token (in place of AP PIN) and "wps_nfc_token disable" disables | |
310 | the NFC password token. | |
311 | ||
312 | The NFC password token that is either pre-configured in the | |
313 | configuration file (wps_nfc_dev_pw_id, wps_nfc_dh_pubkey, | |
314 | wps_nfc_dh_privkey, wps_nfc_dev_pw) or generated dynamically with | |
315 | "wps_nfc_token <WPS|NDEF>" command. The nfc_pw_token tool from | |
316 | wpa_supplicant can be used to generate NFC password tokens during | |
317 | manufacturing (each AP needs to have its own random keys). | |
318 | ||
319 | The "wps_nfc_config_token <WPS/NDEF>" command can be used to build an | |
320 | NFC configuration token. The output value from this command is a hexdump | |
321 | of the current AP configuration (WPS parameter requests this to include | |
322 | only the WPS attributes; NDEF parameter requests additional NDEF | |
323 | encapsulation to be included). This data needs to be written to an NFC | |
324 | tag with an external program. Once written, the NFC configuration token | |
325 | can be used to touch an NFC interface on a station to provision the | |
326 | credentials needed to access the network. | |
327 | ||
328 | When the NFC device on the AP reads an NFC tag with a MIME media type | |
329 | "application/vnd.wfa.wsc", the NDEF message payload (with or without | |
330 | NDEF encapsulation) can be delivered to hostapd using the | |
331 | following hostapd_cli command: | |
332 | ||
333 | wps_nfc_tag_read <hexdump of payload> | |
334 | ||
335 | If the NFC tag contains a password token, the token is added to the | |
336 | internal Registrar. This allows station Enrollee from which the password | |
337 | token was received to run through WPS protocol to provision the | |
338 | credential. | |
7bfe2777 JM |
339 | |
340 | "nfc_get_handover_sel <NDEF> <WPS>" command can be used to build the | |
341 | contents of a Handover Select Message for connection handover when this | |
342 | does not depend on the contents of the Handover Request Message. The | |
343 | first argument selects the format of the output data and the second | |
344 | argument selects which type of connection handover is requested (WPS = | |
345 | Wi-Fi handover as specified in WSC 2.0). | |
346 | ||
347 | "nfc_report_handover <INIT/RESP> WPS <carrier from handover request> | |
348 | <carrier from handover select>" is used to report completed NFC | |
349 | connection handover. The first parameter indicates whether the local | |
350 | device initiated or responded to the connection handover and the carrier | |
351 | records are the selected carrier from the handover request and select | |
352 | messages as a hexdump. |