]>
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 | |
61 | includes WPS support and uses madwifi driver interface: | |
62 | ||
63 | CONFIG_DRIVER_MADWIFI=y | |
64 | CFLAGS += -I/usr/src/madwifi-0.9.3 | |
ad08c363 | 65 | CONFIG_WPS=y |
53587ec1 | 66 | CONFIG_WPS2=y |
c5e1522f | 67 | CONFIG_WPS_UPNP=y |
ad08c363 JM |
68 | |
69 | ||
70 | Following section shows an example runtime configuration | |
71 | (hostapd.conf) that enables WPS: | |
72 | ||
73 | # Configure the driver and network interface | |
74 | driver=madwifi | |
75 | interface=ath0 | |
76 | ||
77 | # WPA2-Personal configuration for the AP | |
78 | ssid=wps-test | |
79 | wpa=2 | |
80 | wpa_key_mgmt=WPA-PSK | |
81 | wpa_pairwise=CCMP | |
82 | # Default WPA passphrase for legacy (non-WPS) clients | |
83 | wpa_passphrase=12345678 | |
84 | # Enable random per-device PSK generation for WPS clients | |
85 | # Please note that the file has to exists for hostapd to start (i.e., create an | |
86 | # empty file as a starting point). | |
87 | wpa_psk_file=/etc/hostapd.psk | |
88 | ||
89 | # Enable control interface for PBC/PIN entry | |
90 | ctrl_interface=/var/run/hostapd | |
91 | ||
92 | # Enable internal EAP server for EAP-WSC (part of Wi-Fi Protected Setup) | |
93 | eap_server=1 | |
94 | ||
95 | # WPS configuration (AP configured, do not allow external WPS Registrars) | |
96 | wps_state=2 | |
97 | ap_setup_locked=1 | |
79da74a2 | 98 | # If UUID is not configured, it will be generated based on local MAC address. |
ad08c363 JM |
99 | uuid=87654321-9abc-def0-1234-56789abc0000 |
100 | wps_pin_requests=/var/run/hostapd.pin-req | |
101 | device_name=Wireless AP | |
102 | manufacturer=Company | |
103 | model_name=WAP | |
104 | model_number=123 | |
105 | serial_number=12345 | |
106 | device_type=6-0050F204-1 | |
107 | os_version=01020300 | |
108 | config_methods=label display push_button keypad | |
109 | ||
c5e1522f JM |
110 | # if external Registrars are allowed, UPnP support could be added: |
111 | #upnp_iface=br0 | |
112 | #friendly_name=WPS Access Point | |
113 | ||
ad08c363 JM |
114 | |
115 | External operations | |
116 | ------------------- | |
117 | ||
118 | WPS requires either a device PIN code (usually, 8-digit number) or a | |
119 | pushbutton event (for PBC) to allow a new WPS Enrollee to join the | |
120 | network. hostapd uses the control interface as an input channel for | |
121 | these events. | |
122 | ||
3981cb3c JM |
123 | The PIN value used in the commands must be processed by an UI to |
124 | remove non-digit characters and potentially, to verify the checksum | |
125 | digit. "hostapd_cli wps_check_pin <PIN>" can be used to do such | |
126 | processing. It returns FAIL if the PIN is invalid, or FAIL-CHECKSUM if | |
127 | the checksum digit is incorrect, or the processed PIN (non-digit | |
128 | characters removed) if the PIN is valid. | |
129 | ||
ad08c363 JM |
130 | When a client device (WPS Enrollee) connects to hostapd (WPS |
131 | Registrar) in order to start PIN mode negotiation for WPS, an | |
132 | identifier (Enrollee UUID) is sent. hostapd will need to be configured | |
133 | with a device password (PIN) for this Enrollee. This is an operation | |
134 | that requires user interaction (assuming there are no pre-configured | |
135 | PINs on the AP for a set of Enrollee). | |
136 | ||
137 | The PIN request with information about the device is appended to the | |
138 | wps_pin_requests file (/var/run/hostapd.pin-req in this example). In | |
139 | addition, hostapd control interface event is sent as a notification of | |
140 | a new device. The AP could use, e.g., a web UI for showing active | |
141 | Enrollees to the user and request a PIN for an Enrollee. | |
142 | ||
143 | The PIN request file has one line for every Enrollee that connected to | |
144 | the AP, but for which there was no PIN. Following information is | |
145 | provided for each Enrollee (separated with tabulators): | |
146 | - timestamp (seconds from 1970-01-01) | |
147 | - Enrollee UUID | |
148 | - MAC address | |
149 | - Device name | |
150 | - Manufacturer | |
151 | - Model Name | |
152 | - Model Number | |
153 | - Serial Number | |
154 | - Device category | |
155 | ||
156 | Example line in the /var/run/hostapd.pin-req file: | |
157 | 1200188391 53b63a98-d29e-4457-a2ed-094d7e6a669c Intel(R) Centrino(R) Intel Corporation Intel(R) Centrino(R) - - 1-0050F204-1 | |
158 | ||
695e2b48 JM |
159 | Control interface data: |
160 | WPS-PIN-NEEDED [UUID-E|MAC Address|Device Name|Manufacturer|Model Name|Model Number|Serial Number|Device Category] | |
161 | For example: | |
162 | <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 |
163 | |
164 | When the user enters a PIN for a pending Enrollee, e.g., on the web | |
165 | UI), hostapd needs to be notified of the new PIN over the control | |
166 | interface. This can be done either by using the UNIX domain socket | |
167 | -based control interface directly (src/common/wpa_ctrl.c provides | |
168 | helper functions for using the interface) or by calling hostapd_cli. | |
169 | ||
170 | Example command to add a PIN (12345670) for an Enrollee: | |
171 | ||
172 | hostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c 12345670 | |
173 | ||
08bec361 | 174 | If the UUID-E is not available (e.g., Enrollee waits for the Registrar |
077a781f JM |
175 | to be selected before connecting), wildcard UUID may be used to allow |
176 | the PIN to be used once with any UUID: | |
08bec361 JM |
177 | |
178 | hostapd_cli wps_pin any 12345670 | |
179 | ||
077a781f JM |
180 | To reduce likelihood of PIN being used with other devices or of |
181 | forgetting an active PIN available for potential attackers, expiration | |
31fcea93 JM |
182 | time in seconds can be set for the new PIN (value 0 indicates no |
183 | expiration): | |
077a781f JM |
184 | |
185 | hostapd_cli wps_pin any 12345670 300 | |
186 | ||
31fcea93 JM |
187 | If the MAC address of the enrollee is known, it should be configured |
188 | to allow the AP to advertise list of authorized enrollees: | |
189 | ||
190 | hostapd_cli wps_pin 53b63a98-d29e-4457-a2ed-094d7e6a669c \ | |
191 | 12345670 300 00:11:22:33:44:55 | |
192 | ||
08bec361 | 193 | |
ad08c363 JM |
194 | After this, the Enrollee can connect to the AP again and complete WPS |
195 | negotiation. At that point, a new, random WPA PSK is generated for the | |
196 | client device and the client can then use that key to connect to the | |
197 | AP to access the network. | |
198 | ||
199 | ||
200 | If the AP includes a pushbutton, WPS PBC mode can be used. It is | |
201 | enabled by pushing a button on both the AP and the client at about the | |
202 | same time (2 minute window). hostapd needs to be notified about the AP | |
203 | button pushed event over the control interface, e.g., by calling | |
204 | hostapd_cli: | |
205 | ||
206 | hostapd_cli wps_pbc | |
207 | ||
208 | At this point, the client has two minutes to complete WPS negotiation | |
209 | which will generate a new WPA PSK in the same way as the PIN method | |
210 | described above. | |
695e2b48 JM |
211 | |
212 | ||
5a1cc30f JM |
213 | When an external Registrar is used, the AP can act as an Enrollee and |
214 | use its AP PIN. A static AP PIN (e.g., one one a label in the AP | |
215 | device) can be configured in hostapd.conf (ap_pin parameter). A more | |
216 | secure option is to use hostapd_cli wps_ap_pin command to enable the | |
217 | AP PIN only based on user action (and even better security by using a | |
218 | random AP PIN for each session, i.e., by using "wps_ap_pin random" | |
219 | command with a timeout value). Following commands are available for | |
220 | managing the dynamic AP PIN operations: | |
221 | ||
222 | hostapd_cli wps_ap_pin disable | |
223 | - disable AP PIN (i.e., do not allow external Registrars to use it to | |
224 | learn the current AP settings or to reconfigure the AP) | |
225 | ||
226 | hostapd_cli wps_ap_pin random [timeout] | |
227 | - generate a random AP PIN and enable it | |
228 | - if the optional timeout parameter is given, the AP PIN will be enabled | |
229 | for the specified number of seconds | |
230 | ||
231 | hostapd_cli wps_ap_pin get | |
232 | - fetch the current AP PIN | |
233 | ||
234 | hostapd_cli wps_ap_pin set <PIN> [timeout] | |
235 | - set the AP PIN and enable it | |
236 | - if the optional timeout parameter is given, the AP PIN will be enabled | |
237 | for the specified number of seconds | |
238 | ||
403b96fe JM |
239 | hostapd_cli get_config |
240 | - display the current configuration | |
241 | ||
450eddcf JM |
242 | hostapd_cli wps_config <new SSID> <auth> <encr> <new key> |
243 | examples: | |
244 | hostapd_cli wps_config testing WPA2PSK CCMP 12345678 | |
245 | hostapd_cli wps_config "no security" OPEN NONE "" | |
246 | ||
247 | <auth> must be one of the following: OPEN WPAPSK WPA2PSK | |
248 | <encr> must be one of the following: NONE WEP TKIP CCMP | |
249 | ||
5a1cc30f | 250 | |
695e2b48 JM |
251 | Credential generation and configuration changes |
252 | ----------------------------------------------- | |
253 | ||
254 | By default, hostapd generates credentials for Enrollees and processing | |
255 | AP configuration updates internally. However, it is possible to | |
256 | control these operations from external programs, if desired. | |
257 | ||
258 | The internal credential generation can be disabled with | |
259 | skip_cred_build=1 option in the configuration. extra_cred option will | |
260 | then need to be used to provide pre-configured Credential attribute(s) | |
261 | for hostapd to use. The exact data from this binary file will be sent, | |
262 | i.e., it will have to include valid WPS attributes. extra_cred can | |
263 | also be used to add additional networks if the Registrar is used to | |
264 | configure credentials for multiple networks. | |
265 | ||
266 | Processing of received configuration updates can be disabled with | |
267 | wps_cred_processing=1 option. When this is used, an external program | |
268 | is responsible for creating hostapd configuration files and processing | |
269 | configuration updates based on messages received from hostapd over | |
270 | control interface. This will also include the initial configuration on | |
271 | first successful registration if the AP is initially set in | |
272 | unconfigured state. | |
273 | ||
274 | Following control interface messages are sent out for external programs: | |
275 | ||
276 | WPS-REG-SUCCESS <Enrollee MAC address <UUID-E> | |
277 | For example: | |
278 | <2>WPS-REG-SUCCESS 02:66:a0:ee:17:27 2b7093f1-d6fb-5108-adbb-bea66bb87333 | |
279 | ||
61fbd3df | 280 | This can be used to trigger change from unconfigured to configured |
695e2b48 JM |
281 | state (random configuration based on the first successful WPS |
282 | registration). In addition, this can be used to update AP UI about the | |
283 | status of WPS registration progress. | |
284 | ||
285 | ||
286 | WPS-NEW-AP-SETTINGS <hexdump of AP Setup attributes> | |
287 | For example: | |
288 | <2>WPS-NEW-AP-SETTINGS 10260001011045000c6a6b6d2d7770732d74657374100300020020100f00020008102700403065346230343536633236366665306433396164313535346131663462663731323433376163666462376633393965353466316631623032306164343438623510200006024231cede15101e000844 | |
289 | ||
290 | This can be used to update the externally stored AP configuration and | |
291 | then update hostapd configuration (followed by restarting of hostapd). |