]>
Commit | Line | Data |
---|---|---|
6fc6879b JM |
1 | hostapd - user space IEEE 802.11 AP and IEEE 802.1X/WPA/WPA2/EAP |
2 | Authenticator and RADIUS authentication server | |
3 | ================================================================ | |
4 | ||
cc58a357 | 5 | Copyright (c) 2002-2019, Jouni Malinen <j@w1.fi> and contributors |
6fc6879b JM |
6 | All Rights Reserved. |
7 | ||
331f89ff JM |
8 | This program is licensed under the BSD license (the one with |
9 | advertisement clause removed). | |
10 | ||
11 | If you are submitting changes to the project, please see CONTRIBUTIONS | |
12 | file for more instructions. | |
6fc6879b JM |
13 | |
14 | ||
15 | ||
16 | License | |
17 | ------- | |
18 | ||
331f89ff JM |
19 | This software may be distributed, used, and modified under the terms of |
20 | BSD license: | |
6fc6879b JM |
21 | |
22 | Redistribution and use in source and binary forms, with or without | |
23 | modification, are permitted provided that the following conditions are | |
24 | met: | |
25 | ||
26 | 1. Redistributions of source code must retain the above copyright | |
27 | notice, this list of conditions and the following disclaimer. | |
28 | ||
29 | 2. Redistributions in binary form must reproduce the above copyright | |
30 | notice, this list of conditions and the following disclaimer in the | |
31 | documentation and/or other materials provided with the distribution. | |
32 | ||
33 | 3. Neither the name(s) of the above-listed copyright holder(s) nor the | |
34 | names of its contributors may be used to endorse or promote products | |
35 | derived from this software without specific prior written permission. | |
36 | ||
37 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
38 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
39 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
40 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
41 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
42 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
43 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
44 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
45 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
46 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
47 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
48 | ||
49 | ||
50 | ||
51 | Introduction | |
52 | ============ | |
53 | ||
54 | Originally, hostapd was an optional user space component for Host AP | |
55 | driver. It adds more features to the basic IEEE 802.11 management | |
56 | included in the kernel driver: using external RADIUS authentication | |
57 | server for MAC address based access control, IEEE 802.1X Authenticator | |
58 | and dynamic WEP keying, RADIUS accounting, WPA/WPA2 (IEEE 802.11i/RSN) | |
59 | Authenticator and dynamic TKIP/CCMP keying. | |
60 | ||
61 | The current version includes support for other drivers, an integrated | |
62 | EAP server (i.e., allow full authentication without requiring | |
63 | an external RADIUS authentication server), and RADIUS authentication | |
64 | server for EAP authentication. | |
65 | ||
66 | ||
67 | Requirements | |
68 | ------------ | |
69 | ||
70 | Current hardware/software requirements: | |
71 | - drivers: | |
72 | Host AP driver for Prism2/2.5/3. | |
2bdbace6 | 73 | (http://w1.fi/hostap-driver.html) |
6fc6879b JM |
74 | Please note that station firmware version needs to be 1.7.0 or newer |
75 | to work in WPA mode. | |
76 | ||
e6f9861a JM |
77 | mac80211-based drivers that support AP mode (with driver=nl80211). |
78 | This includes drivers for Atheros (ath9k) and Broadcom (b43) | |
79 | chipsets. | |
80 | ||
6fc6879b JM |
81 | Any wired Ethernet driver for wired IEEE 802.1X authentication |
82 | (experimental code) | |
83 | ||
2bdbace6 | 84 | FreeBSD -current |
6fc6879b JM |
85 | BSD net80211 layer (e.g., Atheros driver) |
86 | ||
87 | ||
88 | Build configuration | |
89 | ------------------- | |
90 | ||
91 | In order to be able to build hostapd, you will need to create a build | |
92 | time configuration file, .config that selects which optional | |
93 | components are included. See defconfig file for example configuration | |
94 | and list of available options. | |
95 | ||
96 | ||
97 | ||
98 | IEEE 802.1X | |
99 | =========== | |
100 | ||
101 | IEEE Std 802.1X-2001 is a standard for port-based network access | |
102 | control. In case of IEEE 802.11 networks, a "virtual port" is used | |
103 | between each associated station and the AP. IEEE 802.11 specifies | |
104 | minimal authentication mechanism for stations, whereas IEEE 802.1X | |
105 | introduces a extensible mechanism for authenticating and authorizing | |
106 | users. | |
107 | ||
108 | IEEE 802.1X uses elements called Supplicant, Authenticator, Port | |
109 | Access Entity, and Authentication Server. Supplicant is a component in | |
110 | a station and it performs the authentication with the Authentication | |
111 | Server. An access point includes an Authenticator that relays the packets | |
112 | between a Supplicant and an Authentication Server. In addition, it has a | |
113 | Port Access Entity (PAE) with Authenticator functionality for | |
114 | controlling the virtual port authorization, i.e., whether to accept | |
115 | packets from or to the station. | |
116 | ||
117 | IEEE 802.1X uses Extensible Authentication Protocol (EAP). The frames | |
118 | between a Supplicant and an Authenticator are sent using EAP over LAN | |
119 | (EAPOL) and the Authenticator relays these frames to the Authentication | |
120 | Server (and similarly, relays the messages from the Authentication | |
121 | Server to the Supplicant). The Authentication Server can be colocated with the | |
122 | Authenticator, in which case there is no need for additional protocol | |
123 | for EAP frame transmission. However, a more common configuration is to | |
124 | use an external Authentication Server and encapsulate EAP frame in the | |
125 | frames used by that server. RADIUS is suitable for this, but IEEE | |
126 | 802.1X would also allow other mechanisms. | |
127 | ||
128 | Host AP driver includes PAE functionality in the kernel driver. It | |
129 | is a relatively simple mechanism for denying normal frames going to | |
130 | or coming from an unauthorized port. PAE allows IEEE 802.1X related | |
131 | frames to be passed between the Supplicant and the Authenticator even | |
132 | on an unauthorized port. | |
133 | ||
134 | User space daemon, hostapd, includes Authenticator functionality. It | |
135 | receives 802.1X (EAPOL) frames from the Supplicant using the wlan#ap | |
136 | device that is also used with IEEE 802.11 management frames. The | |
137 | frames to the Supplicant are sent using the same device. | |
138 | ||
139 | The normal configuration of the Authenticator would use an external | |
140 | Authentication Server. hostapd supports RADIUS encapsulation of EAP | |
141 | packets, so the Authentication Server should be a RADIUS server, like | |
142 | FreeRADIUS (http://www.freeradius.org/). The Authenticator in hostapd | |
143 | relays the frames between the Supplicant and the Authentication | |
144 | Server. It also controls the PAE functionality in the kernel driver by | |
145 | controlling virtual port authorization, i.e., station-AP | |
146 | connection, based on the IEEE 802.1X state. | |
147 | ||
148 | When a station would like to use the services of an access point, it | |
149 | will first perform IEEE 802.11 authentication. This is normally done | |
150 | with open systems authentication, so there is no security. After | |
151 | this, IEEE 802.11 association is performed. If IEEE 802.1X is | |
152 | configured to be used, the virtual port for the station is set in | |
153 | Unauthorized state and only IEEE 802.1X frames are accepted at this | |
154 | point. The Authenticator will then ask the Supplicant to authenticate | |
155 | with the Authentication Server. After this is completed successfully, | |
156 | the virtual port is set to Authorized state and frames from and to the | |
157 | station are accepted. | |
158 | ||
159 | Host AP configuration for IEEE 802.1X | |
160 | ------------------------------------- | |
161 | ||
162 | The user space daemon has its own configuration file that can be used to | |
163 | define AP options. Distribution package contains an example | |
164 | configuration file (hostapd/hostapd.conf) that can be used as a basis | |
165 | for configuration. It includes examples of all supported configuration | |
166 | options and short description of each option. hostapd should be started | |
167 | with full path to the configuration file as the command line argument, | |
168 | e.g., './hostapd /etc/hostapd.conf'. If you have more that one wireless | |
169 | LAN card, you can use one hostapd process for multiple interfaces by | |
170 | giving a list of configuration files (one per interface) in the command | |
171 | line. | |
172 | ||
173 | hostapd includes a minimal co-located IEEE 802.1X server which can be | |
174 | used to test IEEE 802.1X authentication. However, it should not be | |
175 | used in normal use since it does not provide any security. This can be | |
176 | configured by setting ieee8021x and minimal_eap options in the | |
177 | configuration file. | |
178 | ||
179 | An external Authentication Server (RADIUS) is configured with | |
180 | auth_server_{addr,port,shared_secret} options. In addition, | |
181 | ieee8021x and own_ip_addr must be set for this mode. With such | |
182 | configuration, the co-located Authentication Server is not used and EAP | |
183 | frames will be relayed using EAPOL between the Supplicant and the | |
184 | Authenticator and RADIUS encapsulation between the Authenticator and | |
185 | the Authentication Server. Other than this, the functionality is similar | |
186 | to the case with the co-located Authentication Server. | |
187 | ||
2bdbace6 JM |
188 | Authentication Server |
189 | --------------------- | |
6fc6879b JM |
190 | |
191 | Any RADIUS server supporting EAP should be usable as an IEEE 802.1X | |
192 | Authentication Server with hostapd Authenticator. FreeRADIUS | |
193 | (http://www.freeradius.org/) has been successfully tested with hostapd | |
2bdbace6 | 194 | Authenticator. |
6fc6879b JM |
195 | |
196 | Automatic WEP key configuration | |
197 | ------------------------------- | |
198 | ||
199 | EAP/TLS generates a session key that can be used to send WEP keys from | |
200 | an AP to authenticated stations. The Authenticator in hostapd can be | |
201 | configured to automatically select a random default/broadcast key | |
202 | (shared by all authenticated stations) with wep_key_len_broadcast | |
203 | option (5 for 40-bit WEP or 13 for 104-bit WEP). In addition, | |
204 | wep_key_len_unicast option can be used to configure individual unicast | |
205 | keys for stations. This requires support for individual keys in the | |
206 | station driver. | |
207 | ||
208 | WEP keys can be automatically updated by configuring rekeying. This | |
209 | will improve security of the network since same WEP key will only be | |
210 | used for a limited period of time. wep_rekey_period option sets the | |
211 | interval for rekeying in seconds. | |
212 | ||
213 | ||
214 | WPA/WPA2 | |
215 | ======== | |
216 | ||
217 | Features | |
218 | -------- | |
219 | ||
220 | Supported WPA/IEEE 802.11i features: | |
221 | - WPA-PSK ("WPA-Personal") | |
222 | - WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise") | |
223 | - key management for CCMP, TKIP, WEP104, WEP40 | |
224 | - RSN/WPA2 (IEEE 802.11i), including PMKSA caching and pre-authentication | |
225 | ||
226 | WPA | |
227 | --- | |
228 | ||
229 | The original security mechanism of IEEE 802.11 standard was not | |
230 | designed to be strong and has proved to be insufficient for most | |
231 | networks that require some kind of security. Task group I (Security) | |
232 | of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked | |
233 | to address the flaws of the base standard and has in practice | |
234 | completed its work in May 2004. The IEEE 802.11i amendment to the IEEE | |
2bdbace6 JM |
235 | 802.11 standard was approved in June 2004 and this amendment was |
236 | published in July 2004. | |
6fc6879b JM |
237 | |
238 | Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the | |
239 | IEEE 802.11i work (draft 3.0) to define a subset of the security | |
240 | enhancements that can be implemented with existing wlan hardware. This | |
241 | is called Wi-Fi Protected Access<TM> (WPA). This has now become a | |
242 | mandatory component of interoperability testing and certification done | |
2bdbace6 | 243 | by Wi-Fi Alliance. |
6fc6879b JM |
244 | |
245 | IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm | |
246 | for protecting wireless networks. WEP uses RC4 with 40-bit keys, | |
247 | 24-bit initialization vector (IV), and CRC32 to protect against packet | |
248 | forgery. All these choices have proven to be insufficient: key space is | |
249 | too small against current attacks, RC4 key scheduling is insufficient | |
250 | (beginning of the pseudorandom stream should be skipped), IV space is | |
251 | too small and IV reuse makes attacks easier, there is no replay | |
252 | protection, and non-keyed authentication does not protect against bit | |
253 | flipping packet data. | |
254 | ||
255 | WPA is an intermediate solution for the security issues. It uses | |
256 | Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a | |
257 | compromise on strong security and possibility to use existing | |
258 | hardware. It still uses RC4 for the encryption like WEP, but with | |
259 | per-packet RC4 keys. In addition, it implements replay protection, | |
260 | keyed packet authentication mechanism (Michael MIC). | |
261 | ||
262 | Keys can be managed using two different mechanisms. WPA can either use | |
263 | an external authentication server (e.g., RADIUS) and EAP just like | |
264 | IEEE 802.1X is using or pre-shared keys without need for additional | |
265 | servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal", | |
266 | respectively. Both mechanisms will generate a master session key for | |
267 | the Authenticator (AP) and Supplicant (client station). | |
268 | ||
269 | WPA implements a new key handshake (4-Way Handshake and Group Key | |
270 | Handshake) for generating and exchanging data encryption keys between | |
271 | the Authenticator and Supplicant. This handshake is also used to | |
272 | verify that both Authenticator and Supplicant know the master session | |
273 | key. These handshakes are identical regardless of the selected key | |
274 | management mechanism (only the method for generating master session | |
275 | key changes). | |
276 | ||
277 | ||
278 | IEEE 802.11i / WPA2 | |
279 | ------------------- | |
280 | ||
281 | The design for parts of IEEE 802.11i that were not included in WPA has | |
282 | finished (May 2004) and this amendment to IEEE 802.11 was approved in | |
283 | June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new | |
284 | version of WPA called WPA2. This includes, e.g., support for more | |
285 | robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC) | |
286 | to replace TKIP and optimizations for handoff (reduced number of | |
287 | messages in initial key handshake, pre-authentication, and PMKSA caching). | |
288 | ||
289 | Some wireless LAN vendors are already providing support for CCMP in | |
290 | their WPA products. There is no "official" interoperability | |
291 | certification for CCMP and/or mixed modes using both TKIP and CCMP, so | |
292 | some interoperability issues can be expected even though many | |
293 | combinations seem to be working with equipment from different vendors. | |
294 | Testing for WPA2 is likely to start during the second half of 2004. | |
295 | ||
296 | hostapd configuration for WPA/WPA2 | |
297 | ---------------------------------- | |
298 | ||
299 | TODO | |
300 | ||
301 | # Enable WPA. Setting this variable configures the AP to require WPA (either | |
302 | # WPA-PSK or WPA-RADIUS/EAP based on other configuration). For WPA-PSK, either | |
303 | # wpa_psk or wpa_passphrase must be set and wpa_key_mgmt must include WPA-PSK. | |
304 | # For WPA-RADIUS/EAP, ieee8021x must be set (but without dynamic WEP keys), | |
305 | # RADIUS authentication server must be configured, and WPA-EAP must be included | |
306 | # in wpa_key_mgmt. | |
307 | # This field is a bit field that can be used to enable WPA (IEEE 802.11i/D3.0) | |
308 | # and/or WPA2 (full IEEE 802.11i/RSN): | |
309 | # bit0 = WPA | |
310 | # bit1 = IEEE 802.11i/RSN (WPA2) | |
311 | #wpa=1 | |
312 | ||
313 | # WPA pre-shared keys for WPA-PSK. This can be either entered as a 256-bit | |
314 | # secret in hex format (64 hex digits), wpa_psk, or as an ASCII passphrase | |
315 | # (8..63 characters) that will be converted to PSK. This conversion uses SSID | |
316 | # so the PSK changes when ASCII passphrase is used and the SSID is changed. | |
317 | #wpa_psk=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef | |
318 | #wpa_passphrase=secret passphrase | |
319 | ||
320 | # Set of accepted key management algorithms (WPA-PSK, WPA-EAP, or both). The | |
321 | # entries are separated with a space. | |
322 | #wpa_key_mgmt=WPA-PSK WPA-EAP | |
323 | ||
324 | # Set of accepted cipher suites (encryption algorithms) for pairwise keys | |
325 | # (unicast packets). This is a space separated list of algorithms: | |
326 | # CCMP = AES in Counter mode with CBC-MAC [RFC 3610, IEEE 802.11i] | |
327 | # TKIP = Temporal Key Integrity Protocol [IEEE 802.11i] | |
328 | # Group cipher suite (encryption algorithm for broadcast and multicast frames) | |
329 | # is automatically selected based on this configuration. If only CCMP is | |
330 | # allowed as the pairwise cipher, group cipher will also be CCMP. Otherwise, | |
331 | # TKIP will be used as the group cipher. | |
332 | #wpa_pairwise=TKIP CCMP | |
333 | ||
334 | # Time interval for rekeying GTK (broadcast/multicast encryption keys) in | |
335 | # seconds. | |
336 | #wpa_group_rekey=600 | |
337 | ||
338 | # Time interval for rekeying GMK (master key used internally to generate GTKs | |
339 | # (in seconds). | |
340 | #wpa_gmk_rekey=86400 | |
341 | ||
342 | # Enable IEEE 802.11i/RSN/WPA2 pre-authentication. This is used to speed up | |
343 | # roaming be pre-authenticating IEEE 802.1X/EAP part of the full RSN | |
344 | # authentication and key handshake before actually associating with a new AP. | |
345 | #rsn_preauth=1 | |
346 | # | |
347 | # Space separated list of interfaces from which pre-authentication frames are | |
348 | # accepted (e.g., 'eth0' or 'eth0 wlan0wds0'. This list should include all | |
349 | # interface that are used for connections to other APs. This could include | |
350 | # wired interfaces and WDS links. The normal wireless data interface towards | |
351 | # associated stations (e.g., wlan0) should not be added, since | |
352 | # pre-authentication is only used with APs other than the currently associated | |
353 | # one. | |
354 | #rsn_preauth_interfaces=eth0 |