]>
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 | |
50 | configure an AP. The current version of wpa_supplicant does not | |
51 | support operation as an external WLAN Management Registrar for adding | |
52 | new client devices or configuring the AP over UPnP. | |
53 | ||
54 | ||
55 | wpa_supplicant configuration | |
56 | ---------------------------- | |
57 | ||
58 | WPS is an optional component that needs to be enabled in | |
59 | wpa_supplicant build configuration (.config). Here is an example | |
60 | configuration that includes WPS support and Linux wireless extensions | |
61 | -based driver interface: | |
62 | ||
63 | CONFIG_DRIVER_WEXT=y | |
64 | CONFIG_EAP=y | |
65 | CONFIG_WPS=y | |
66 | ||
67 | ||
68 | WPS needs the Universally Unique IDentifier (UUID; see RFC 4122) for | |
69 | the device. This is configured in the runtime configuration for | |
79da74a2 JM |
70 | wpa_supplicant (if not set, UUID will be generated based on local MAC |
71 | address): | |
bd034191 JM |
72 | |
73 | # example UUID for WPS | |
74 | uuid=12345678-9abc-def0-1234-56789abcdef0 | |
75 | ||
76 | The network configuration blocks needed for WPS are added | |
77 | automatically based on control interface commands, so they do not need | |
78 | to be added explicitly in the configuration file. | |
79 | ||
30f5c941 JM |
80 | WPS registration will generate new network blocks for the acquired |
81 | credentials. If these are to be stored for future use (after | |
82 | restarting wpa_supplicant), wpa_supplicant will need to be configured | |
83 | to allow configuration file updates: | |
84 | ||
85 | update_config=1 | |
86 | ||
87 | ||
bd034191 JM |
88 | |
89 | External operations | |
90 | ------------------- | |
91 | ||
92 | WPS requires either a device PIN code (usually, 8-digit number) or a | |
93 | pushbutton event (for PBC) to allow a new WPS Enrollee to join the | |
94 | network. wpa_supplicant uses the control interface as an input channel | |
95 | for these events. | |
96 | ||
97 | If the client device has a display, a random PIN has to be generated | |
98 | for each WPS registration session. wpa_supplicant can do this with a | |
99 | control interface request, e.g., by calling wpa_cli: | |
100 | ||
101 | wpa_cli wps_pin any | |
102 | ||
103 | This will return the generated 8-digit PIN which will then need to be | |
104 | entered at the Registrar to complete WPS registration. At that point, | |
105 | the client will be enrolled with credentials needed to connect to the | |
106 | AP to access the network. | |
107 | ||
108 | ||
109 | If the client device does not have a display that could show the | |
110 | random PIN, a hardcoded PIN that is printed on a label can be | |
111 | used. wpa_supplicant is notified this with a control interface | |
112 | request, e.g., by calling wpa_cli: | |
113 | ||
114 | wpa_cli wps_pin any 12345670 | |
115 | ||
116 | This starts the WPS negotiation in the same way as above with the | |
117 | generated PIN. | |
118 | ||
119 | ||
120 | If the client design wants to support optional WPS PBC mode, this can | |
121 | be enabled by either a physical button in the client device or a | |
122 | virtual button in the user interface. The PBC operation requires that | |
123 | a button is also pressed at the AP/Registrar at about the same time (2 | |
124 | minute window). wpa_supplicant is notified of the local button event | |
125 | over the control interface, e.g., by calling wpa_cli: | |
126 | ||
127 | wpa_cli wps_pbc | |
128 | ||
129 | At this point, the AP/Registrar has two minutes to complete WPS | |
130 | negotiation which will generate a new WPA PSK in the same way as the | |
131 | PIN method described above. | |
132 | ||
133 | ||
52eb293d JM |
134 | If the client wants to operate in the Registrar role to learn the |
135 | current AP configuration and optionally, to configure an AP, | |
136 | wpa_supplicant is notified over the control interface, e.g., with | |
bd034191 JM |
137 | wpa_cli: |
138 | ||
139 | wpa_cli wps_reg <AP BSSID> <AP PIN> | |
140 | (example: wpa_cli wps_reg 02:34:56:78:9a:bc 12345670) | |
eef7d7a1 | 141 | |
52eb293d JM |
142 | This is used to fetch the current AP settings instead of actually |
143 | changing them. The main difference with the wps_pin command is that | |
144 | wps_reg uses the AP PIN (e.g., from a label on the AP) instead of a | |
145 | PIN generated at the client. | |
146 | ||
147 | In order to change the AP configuration, the new configuration | |
148 | parameters are given to the wps_reg command: | |
149 | ||
150 | wpa_cli wps_reg <AP BSSID> <AP PIN> <new SSID> <auth> <encr> <new key> | |
151 | examples: | |
152 | wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 testing WPA2PSK CCMP 12345678 | |
153 | wpa_cli wps_reg 02:34:56:78:9a:bc 12345670 clear OPEN NONE "" | |
154 | ||
155 | <auth> must be one of the following: OPEN WPAPSK WPA2PSK | |
156 | <encr> must be one of the following: NONE WEP TKIP CCMP | |
4625a47f | 157 | |
eef7d7a1 JM |
158 | |
159 | Scanning | |
160 | -------- | |
161 | ||
162 | Scan results ('wpa_cli scan_results' or 'wpa_cli bss <idx>') include a | |
163 | flags field that is used to indicate whether the BSS support WPS. If | |
164 | the AP support WPS, but has not recently activated a Registrar, [WPS] | |
165 | flag will be included. If PIN method has been recently selected, | |
166 | [WPS-PIN] is shown instead. Similarly, [WPS-PBC] is shown if PBC mode | |
167 | is in progress. GUI programs can use these as triggers for suggesting | |
f9e4465c JM |
168 | a guided WPS configuration to the user. In addition, control interface |
169 | monitor events WPS-AP-AVAILABLE{,-PBC,-PIN} can be used to find out if | |
170 | there are WPS enabled APs in scan results without having to go through | |
171 | all the details in the GUI. These notification could be used, e.g., to | |
172 | suggest possible WPS connection to the user. | |
173 | ||
174 | ||
175 | wpa_gui | |
176 | ------- | |
177 | ||
178 | wpa_gui-qt4 directory contains a sample GUI that shows an example of | |
179 | how WPS support can be integrated into the GUI. Its main window has a | |
180 | WPS tab that guides user through WPS registration with automatic AP | |
181 | selection. In addition, it shows how WPS can be started manually by | |
182 | selecting an AP from scan results. | |
695e2b48 JM |
183 | |
184 | ||
185 | Credential processing | |
186 | --------------------- | |
187 | ||
188 | By default, wpa_supplicant processes received credentials and updates | |
189 | its configuration internally. However, it is possible to | |
190 | control these operations from external programs, if desired. | |
191 | ||
192 | This internal processing can be disabled with wps_cred_processing=1 | |
193 | option. When this is used, an external program is responsible for | |
194 | processing the credential attributes and updating wpa_supplicant | |
195 | configuration based on them. | |
196 | ||
197 | Following control interface messages are sent out for external programs: | |
198 | ||
199 | WPS-CRED-RECEIVED <hexdump of Credential attribute(s)> | |
200 | For example: | |
201 | <2>WPS-CRED-RECEIVED 100e006f10260001011045000c6a6b6d2d7770732d74657374100300020020100f000200081027004030653462303435366332363666653064333961643135353461316634626637313234333761636664623766333939653534663166316230323061643434386235102000060266a0ee1727 |