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