| 1 |
hostapd - user space IEEE 802.11 AP and IEEE 802.1X/WPA/WPA2/EAP |
| 2 |
Authenticator and RADIUS authentication server |
| 3 |
================================================================ |
| 4 |
|
| 5 |
Copyright (c) 2002-2022, Jouni Malinen <[email protected]> and contributors |
| 6 |
All Rights Reserved. |
| 7 |
|
| 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. |
| 13 |
|
| 14 |
|
| 15 |
|
| 16 |
License |
| 17 |
------- |
| 18 |
|
| 19 |
This software may be distributed, used, and modified under the terms of |
| 20 |
BSD license: |
| 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. |
| 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 |
|
| 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 |
|
| 188 |
Authentication Server |
| 189 |
--------------------- |
| 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 |
| 194 |
Authenticator. |
| 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 |
| 235 |
802.11 standard was approved in June 2004 and this amendment was |
| 236 |
published in July 2004. |
| 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 |
| 243 |
by Wi-Fi Alliance. |
| 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 |