]>
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 | |
70 | wpa_supplicant: | |
71 | ||
72 | # example UUID for WPS | |
73 | uuid=12345678-9abc-def0-1234-56789abcdef0 | |
74 | ||
75 | The network configuration blocks needed for WPS are added | |
76 | automatically based on control interface commands, so they do not need | |
77 | to be added explicitly in the configuration file. | |
78 | ||
79 | ||
80 | External operations | |
81 | ------------------- | |
82 | ||
83 | WPS requires either a device PIN code (usually, 8-digit number) or a | |
84 | pushbutton event (for PBC) to allow a new WPS Enrollee to join the | |
85 | network. wpa_supplicant uses the control interface as an input channel | |
86 | for these events. | |
87 | ||
88 | If the client device has a display, a random PIN has to be generated | |
89 | for each WPS registration session. wpa_supplicant can do this with a | |
90 | control interface request, e.g., by calling wpa_cli: | |
91 | ||
92 | wpa_cli wps_pin any | |
93 | ||
94 | This will return the generated 8-digit PIN which will then need to be | |
95 | entered at the Registrar to complete WPS registration. At that point, | |
96 | the client will be enrolled with credentials needed to connect to the | |
97 | AP to access the network. | |
98 | ||
99 | ||
100 | If the client device does not have a display that could show the | |
101 | random PIN, a hardcoded PIN that is printed on a label can be | |
102 | used. wpa_supplicant is notified this with a control interface | |
103 | request, e.g., by calling wpa_cli: | |
104 | ||
105 | wpa_cli wps_pin any 12345670 | |
106 | ||
107 | This starts the WPS negotiation in the same way as above with the | |
108 | generated PIN. | |
109 | ||
110 | ||
111 | If the client design wants to support optional WPS PBC mode, this can | |
112 | be enabled by either a physical button in the client device or a | |
113 | virtual button in the user interface. The PBC operation requires that | |
114 | a button is also pressed at the AP/Registrar at about the same time (2 | |
115 | minute window). wpa_supplicant is notified of the local button event | |
116 | over the control interface, e.g., by calling wpa_cli: | |
117 | ||
118 | wpa_cli wps_pbc | |
119 | ||
120 | At this point, the AP/Registrar has two minutes to complete WPS | |
121 | negotiation which will generate a new WPA PSK in the same way as the | |
122 | PIN method described above. | |
123 | ||
124 | ||
125 | If the client wants to operation in the Registrar role to configure an | |
126 | AP, wpa_supplicant is notified over the control interface, e.g., with | |
127 | wpa_cli: | |
128 | ||
129 | wpa_cli wps_reg <AP BSSID> <AP PIN> | |
130 | (example: wpa_cli wps_reg 02:34:56:78:9a:bc 12345670) |