diff options
Diffstat (limited to 'contrib/wpa_supplicant/README')
| -rw-r--r-- | contrib/wpa_supplicant/README | 970 |
1 files changed, 0 insertions, 970 deletions
diff --git a/contrib/wpa_supplicant/README b/contrib/wpa_supplicant/README deleted file mode 100644 index 0b3c585..0000000 --- a/contrib/wpa_supplicant/README +++ /dev/null @@ -1,970 +0,0 @@ -WPA Supplicant -============== - -Copyright (c) 2003-2008, Jouni Malinen <j@w1.fi> and contributors -All Rights Reserved. - -This program is dual-licensed under both the GPL version 2 and BSD -license. Either license may be used at your option. - - - -License -------- - -GPL v2: - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License version 2 as -published by the Free Software Foundation. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program; if not, write to the Free Software -Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - -(this copy of the license is in COPYING file) - - -Alternatively, this software may be distributed, used, and modified -under the terms of BSD license: - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -3. Neither the name(s) of the above-listed copyright holder(s) nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - - -Features --------- - -Supported WPA/IEEE 802.11i features: -- WPA-PSK ("WPA-Personal") -- WPA with EAP (e.g., with RADIUS authentication server) ("WPA-Enterprise") - Following authentication methods are supported with an integrate IEEE 802.1X - Supplicant: - * EAP-TLS - * EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1) - * EAP-PEAP/TLS (both PEAPv0 and PEAPv1) - * EAP-PEAP/GTC (both PEAPv0 and PEAPv1) - * EAP-PEAP/OTP (both PEAPv0 and PEAPv1) - * EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1) - * EAP-TTLS/EAP-MD5-Challenge - * EAP-TTLS/EAP-GTC - * EAP-TTLS/EAP-OTP - * EAP-TTLS/EAP-MSCHAPv2 - * EAP-TTLS/EAP-TLS - * EAP-TTLS/MSCHAPv2 - * EAP-TTLS/MSCHAP - * EAP-TTLS/PAP - * EAP-TTLS/CHAP - * EAP-SIM - * EAP-AKA - * EAP-PSK - * EAP-PAX - * EAP-SAKE - * EAP-GPSK - * LEAP (note: requires special support from the driver for IEEE 802.11 - authentication) - (following methods are supported, but since they do not generate keying - material, they cannot be used with WPA or IEEE 802.1X WEP keying) - * EAP-MD5-Challenge - * EAP-MSCHAPv2 - * EAP-GTC - * EAP-OTP -- key management for CCMP, TKIP, WEP104, WEP40 -- RSN/WPA2 (IEEE 802.11i) - * pre-authentication - * PMKSA caching - -Supported TLS/crypto libraries: -- OpenSSL (default) -- GnuTLS - -Internal TLS/crypto implementation (optional): -- can be used in place of an external TLS/crypto library -- TLSv1 -- X.509 certificate processing -- PKCS #1 -- ASN.1 -- RSA -- bignum -- minimal size (ca. 50 kB binary, parts of which are already needed for WPA; - TLSv1/X.509/ASN.1/RSA/bignum parts are about 25 kB on x86) - - -Requirements ------------- - -Current hardware/software requirements: -- Linux kernel 2.4.x or 2.6.x with Linux Wireless Extensions v15 or newer -- FreeBSD 6-CURRENT -- NetBSD-current -- Microsoft Windows with WinPcap (at least WinXP, may work with other versions) -- drivers: - Linux drivers that support WPA/WPA2 configuration with the generic - Linux wireless extensions (WE-18 or newer). Even though there are - number of driver specific interface included in wpa_supplicant, please - note that Linux drivers are moving to use generic wireless extensions - and driver_wext (-Dwext on wpa_supplicant command line) should be the - default option to start with before falling back to driver specific - interface. - - Host AP driver for Prism2/2.5/3 (development snapshot/v0.2.x) - (http://hostap.epitest.fi/) - Driver need to be set in Managed mode ('iwconfig wlan0 mode managed'). - Please note that station firmware version needs to be 1.7.0 or newer - to work in WPA mode. - - Linuxant DriverLoader (http://www.linuxant.com/driverloader/) - with Windows NDIS driver for your wlan card supporting WPA. - - Agere Systems Inc. Linux Driver - (http://www.agere.com/support/drivers/) - Please note that the driver interface file (driver_hermes.c) and - hardware specific include files are not included in the - wpa_supplicant distribution. You will need to copy these from the - source package of the Agere driver. - - madwifi driver for cards based on Atheros chip set (ar521x) - (http://sourceforge.net/projects/madwifi/) - Please note that you will need to modify the wpa_supplicant .config - file to use the correct path for the madwifi driver root directory - (CFLAGS += -I../madwifi/wpa line in example defconfig). - - ATMEL AT76C5XXx driver for USB and PCMCIA cards - (http://atmelwlandriver.sourceforge.net/). - - Linux ndiswrapper (http://ndiswrapper.sourceforge.net/) with - Windows NDIS driver. - - Broadcom wl.o driver - This is a generic Linux driver for Broadcom IEEE 802.11a/g cards. - However, it is proprietary driver that is not publicly available - except for couple of exceptions, mainly Broadcom-based APs/wireless - routers that use Linux. The driver binary can be downloaded, e.g., - from Linksys support site (http://www.linksys.com/support/gpl.asp) - for Linksys WRT54G. The GPL tarball includes cross-compiler and - the needed header file, wlioctl.h, for compiling wpa_supplicant. - This driver support in wpa_supplicant is expected to work also with - other devices based on Broadcom driver (assuming the driver includes - client mode support). - - Intel ipw2100 driver - (http://sourceforge.net/projects/ipw2100/) - - Intel ipw2200 driver - (http://sourceforge.net/projects/ipw2200/) - - In theory, any driver that supports Linux wireless extensions can be - used with IEEE 802.1X (i.e., not WPA) when using ap_scan=0 option in - configuration file. - - Wired Ethernet drivers (with ap_scan=0) - - BSD net80211 layer (e.g., Atheros driver) - At the moment, this is for FreeBSD 6-CURRENT branch and NetBSD-current. - - Windows NDIS - The current Windows port requires WinPcap (http://winpcap.polito.it/). - See README-Windows.txt for more information. - -wpa_supplicant was designed to be portable for different drivers and -operating systems. Hopefully, support for more wlan cards and OSes will be -added in the future. See developer's documentation -(http://hostap.epitest.fi/wpa_supplicant/devel/) for more information about the -design of wpa_supplicant and porting to other drivers. One main goal -is to add full WPA/WPA2 support to Linux wireless extensions to allow -new drivers to be supported without having to implement new -driver-specific interface code in wpa_supplicant. - -Optional libraries for layer2 packet processing: -- libpcap (tested with 0.7.2, most relatively recent versions assumed to work, - this is likely to be available with most distributions, - http://tcpdump.org/) -- libdnet (tested with v1.4, most versions assumed to work, - http://libdnet.sourceforge.net/) - -These libraries are _not_ used in the default Linux build. Instead, -internal Linux specific implementation is used. libpcap/libdnet are -more portable and they can be used by adding CONFIG_L2_PACKET=pcap into -.config. They may also be selected automatically for other operating -systems. In case of Windows builds, WinPcap is used by default -(CONFIG_L2_PACKET=winpcap). - - -Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS: -- OpenSSL (tested with 0.9.7c and 0.9.7d, and 0.9.8 versions; assumed to - work with most relatively recent versions; this is likely to be - available with most distributions, http://www.openssl.org/) -- GnuTLS -- internal TLSv1 implementation - -TLS options for EAP-FAST: -- OpenSSL 0.9.8d _with_ openssl-0.9.8d-tls-extensions.patch applied - (i.e., the default OpenSSL package does not include support for - extensions needed for EAP-FAST) -- internal TLSv1 implementation - -One of these libraries is needed when EAP-TLS, EAP-PEAP, EAP-TTLS, or -EAP-FAST support is enabled. WPA-PSK mode does not require this or EAPOL/EAP -implementation. A configuration file, .config, for compilation is -needed to enable IEEE 802.1X/EAPOL and EAP methods. Note that EAP-MD5, -EAP-GTC, EAP-OTP, and EAP-MSCHAPV2 cannot be used alone with WPA, so -they should only be enabled if testing the EAPOL/EAP state -machines. However, there can be used as inner authentication -algorithms with EAP-PEAP and EAP-TTLS. - -See Building and installing section below for more detailed -information about the wpa_supplicant build time configuration. - - - -WPA ---- - -The original security mechanism of IEEE 802.11 standard was not -designed to be strong and has proven to be insufficient for most -networks that require some kind of security. Task group I (Security) -of IEEE 802.11 working group (http://www.ieee802.org/11/) has worked -to address the flaws of the base standard and has in practice -completed its work in May 2004. The IEEE 802.11i amendment to the IEEE -802.11 standard was approved in June 2004 and published in July 2004. - -Wi-Fi Alliance (http://www.wi-fi.org/) used a draft version of the -IEEE 802.11i work (draft 3.0) to define a subset of the security -enhancements that can be implemented with existing wlan hardware. This -is called Wi-Fi Protected Access<TM> (WPA). This has now become a -mandatory component of interoperability testing and certification done -by Wi-Fi Alliance. Wi-Fi provides information about WPA at its web -site (http://www.wi-fi.org/OpenSection/protected_access.asp). - -IEEE 802.11 standard defined wired equivalent privacy (WEP) algorithm -for protecting wireless networks. WEP uses RC4 with 40-bit keys, -24-bit initialization vector (IV), and CRC32 to protect against packet -forgery. All these choices have proven to be insufficient: key space is -too small against current attacks, RC4 key scheduling is insufficient -(beginning of the pseudorandom stream should be skipped), IV space is -too small and IV reuse makes attacks easier, there is no replay -protection, and non-keyed authentication does not protect against bit -flipping packet data. - -WPA is an intermediate solution for the security issues. It uses -Temporal Key Integrity Protocol (TKIP) to replace WEP. TKIP is a -compromise on strong security and possibility to use existing -hardware. It still uses RC4 for the encryption like WEP, but with -per-packet RC4 keys. In addition, it implements replay protection, -keyed packet authentication mechanism (Michael MIC). - -Keys can be managed using two different mechanisms. WPA can either use -an external authentication server (e.g., RADIUS) and EAP just like -IEEE 802.1X is using or pre-shared keys without need for additional -servers. Wi-Fi calls these "WPA-Enterprise" and "WPA-Personal", -respectively. Both mechanisms will generate a master session key for -the Authenticator (AP) and Supplicant (client station). - -WPA implements a new key handshake (4-Way Handshake and Group Key -Handshake) for generating and exchanging data encryption keys between -the Authenticator and Supplicant. This handshake is also used to -verify that both Authenticator and Supplicant know the master session -key. These handshakes are identical regardless of the selected key -management mechanism (only the method for generating master session -key changes). - - - -IEEE 802.11i / WPA2 -------------------- - -The design for parts of IEEE 802.11i that were not included in WPA has -finished (May 2004) and this amendment to IEEE 802.11 was approved in -June 2004. Wi-Fi Alliance is using the final IEEE 802.11i as a new -version of WPA called WPA2. This includes, e.g., support for more -robust encryption algorithm (CCMP: AES in Counter mode with CBC-MAC) -to replace TKIP and optimizations for handoff (reduced number of -messages in initial key handshake, pre-authentication, and PMKSA caching). - - - -wpa_supplicant --------------- - -wpa_supplicant is an implementation of the WPA Supplicant component, -i.e., the part that runs in the client stations. It implements WPA key -negotiation with a WPA Authenticator and EAP authentication with -Authentication Server. In addition, it controls the roaming and IEEE -802.11 authentication/association of the wlan driver. - -wpa_supplicant is designed to be a "daemon" program that runs in the -background and acts as the backend component controlling the wireless -connection. wpa_supplicant supports separate frontend programs and an -example text-based frontend, wpa_cli, is included with wpa_supplicant. - -Following steps are used when associating with an AP using WPA: - -- wpa_supplicant requests the kernel driver to scan neighboring BSSes -- wpa_supplicant selects a BSS based on its configuration -- wpa_supplicant requests the kernel driver to associate with the chosen - BSS -- If WPA-EAP: integrated IEEE 802.1X Supplicant completes EAP - authentication with the authentication server (proxied by the - Authenticator in the AP) -- If WPA-EAP: master key is received from the IEEE 802.1X Supplicant -- If WPA-PSK: wpa_supplicant uses PSK as the master session key -- wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake - with the Authenticator (AP) -- wpa_supplicant configures encryption keys for unicast and broadcast -- normal data packets can be transmitted and received - - - -Building and installing ------------------------ - -In order to be able to build wpa_supplicant, you will first need to -select which parts of it will be included. This is done by creating a -build time configuration file, .config, in the wpa_supplicant root -directory. Configuration options are text lines using following -format: CONFIG_<option>=y. Lines starting with # are considered -comments and are ignored. See defconfig file for an example configuration -and a list of available options and additional notes. - -The build time configuration can be used to select only the needed -features and limit the binary size and requirements for external -libraries. The main configuration parts are the selection of which -driver interfaces (e.g., hostap, madwifi, ..) and which authentication -methods (e.g., EAP-TLS, EAP-PEAP, ..) are included. - -Following build time configuration options are used to control IEEE -802.1X/EAPOL and EAP state machines and all EAP methods. Including -TLS, PEAP, or TTLS will require linking wpa_supplicant with OpenSSL -library for TLS implementation. Alternatively, GnuTLS or the internal -TLSv1 implementation can be used for TLS functionaly. - -CONFIG_IEEE8021X_EAPOL=y -CONFIG_EAP_MD5=y -CONFIG_EAP_MSCHAPV2=y -CONFIG_EAP_TLS=y -CONFIG_EAP_PEAP=y -CONFIG_EAP_TTLS=y -CONFIG_EAP_GTC=y -CONFIG_EAP_OTP=y -CONFIG_EAP_SIM=y -CONFIG_EAP_AKA=y -CONFIG_EAP_PSK=y -CONFIG_EAP_SAKE=y -CONFIG_EAP_GPSK=y -CONFIG_EAP_PAX=y -CONFIG_EAP_LEAP=y - -Following option can be used to include GSM SIM/USIM interface for GSM/UMTS -authentication algorithm (for EAP-SIM/EAP-AKA). This requires pcsc-lite -(http://www.linuxnet.com/) for smart card access. - -CONFIG_PCSC=y - -Following options can be added to .config to select which driver -interfaces are included. Hermes driver interface needs to be downloaded -from Agere (see above). CONFIG_WIRELESS_EXTENSION will be used -automatically if any of the selected drivers need it. - -CONFIG_WIRELESS_EXTENSION=y -CONFIG_DRIVER_HOSTAP=y -CONFIG_DRIVER_HERMES=y -CONFIG_DRIVER_MADWIFI=y -CONFIG_DRIVER_ATMEL=y -CONFIG_DRIVER_WEXT=y -CONFIG_DRIVER_NDISWRAPPER=y -CONFIG_DRIVER_BROADCOM=y -CONFIG_DRIVER_IPW=y -CONFIG_DRIVER_BSD=y -CONFIG_DRIVER_NDIS=y - -Following example includes all features and driver interfaces that are -included in the wpa_supplicant package: - -CONFIG_DRIVER_HOSTAP=y -CONFIG_DRIVER_HERMES=y -CONFIG_DRIVER_MADWIFI=y -CONFIG_DRIVER_ATMEL=y -CONFIG_DRIVER_WEXT=y -CONFIG_DRIVER_NDISWRAPPER=y -CONFIG_DRIVER_BROADCOM=y -CONFIG_DRIVER_IPW=y -CONFIG_DRIVER_BSD=y -CONFIG_DRIVER_NDIS=y -CONFIG_WIRELESS_EXTENSION=y -CONFIG_IEEE8021X_EAPOL=y -CONFIG_EAP_MD5=y -CONFIG_EAP_MSCHAPV2=y -CONFIG_EAP_TLS=y -CONFIG_EAP_PEAP=y -CONFIG_EAP_TTLS=y -CONFIG_EAP_GTC=y -CONFIG_EAP_OTP=y -CONFIG_EAP_SIM=y -CONFIG_EAP_AKA=y -CONFIG_EAP_PSK=y -CONFIG_EAP_SAKE=y -CONFIG_EAP_GPSK=y -CONFIG_EAP_PAX=y -CONFIG_EAP_LEAP=y -CONFIG_PCSC=y - -EAP-PEAP and EAP-TTLS will automatically include configured EAP -methods (MD5, OTP, GTC, MSCHAPV2) for inner authentication selection. - - -After you have created a configuration file, you can build -wpa_supplicant and wpa_cli with 'make' command. You may then install -the binaries to a suitable system directory, e.g., /usr/local/bin. - -Example commands: - -# build wpa_supplicant and wpa_cli -make -# install binaries (this may need root privileges) -cp wpa_cli wpa_supplicant /usr/local/bin - - -You will need to make a configuration file, e.g., -/etc/wpa_supplicant.conf, with network configuration for the networks -you are going to use. Configuration file section below includes -explanation fo the configuration file format and includes various -examples. Once the configuration is ready, you can test whether the -configuration work by first running wpa_supplicant with following -command to start it on foreground with debugging enabled: - -wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d - -Assuming everything goes fine, you can start using following command -to start wpa_supplicant on background without debugging: - -wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B - -Please note that if you included more than one driver interface in the -build time configuration (.config), you may need to specify which -interface to use by including -D<driver name> option on the command -line. See following section for more details on command line options -for wpa_supplicant. - - - -Command line options --------------------- - -usage: - wpa_supplicant [-BddfhKLqqtuvwW] [-P<pid file>] [-g<global ctrl>] \ - -i<ifname> -c<config file> [-C<ctrl>] [-D<driver>] [-p<driver_param>] \ - [-b<br_ifname> [-N -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] \ - [-p<driver_param>] [-b<br_ifname>] ...] - -options: - -b = optional bridge interface name - -B = run daemon in the background - -c = Configuration file - -C = ctrl_interface parameter (only used if -c is not) - -i = interface name - -d = increase debugging verbosity (-dd even more) - -D = driver name - -f = Log output to default log location (normally /tmp) - -g = global ctrl_interface - -K = include keys (passwords, etc.) in debug output - -t = include timestamp in debug messages - -h = show this help text - -L = show license (GPL and BSD) - -p = driver parameters - -P = PID file - -q = decrease debugging verbosity (-qq even less) - -v = show version - -w = wait for interface to be added, if needed - -W = wait for a control interface monitor before starting - -N = start describing new interface - -drivers: - hostap = Host AP driver (Intersil Prism2/2.5/3) [default] - (this can also be used with Linuxant DriverLoader) - hermes = Agere Systems Inc. driver (Hermes-I/Hermes-II) - madwifi = MADWIFI 802.11 support (Atheros, etc.) - atmel = ATMEL AT76C5XXx (USB, PCMCIA) - wext = Linux wireless extensions (generic) - ndiswrapper = Linux ndiswrapper - broadcom = Broadcom wl.o driver - ipw = Intel ipw2100/2200 driver (old; use wext with Linux 2.6.13 or newer) - wired = wpa_supplicant wired Ethernet driver - bsd = BSD 802.11 support (Atheros, etc.) - ndis = Windows NDIS driver - -In most common cases, wpa_supplicant is started with - -wpa_supplicant -Bw -c/etc/wpa_supplicant.conf -iwlan0 - -This makes the process fork into background and wait for the wlan0 -interface if it is not available at startup time. - -The easiest way to debug problems, and to get debug log for bug -reports, is to start wpa_supplicant on foreground with debugging -enabled: - -wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d - - -wpa_supplicant can control multiple interfaces (radios) either by -running one process for each interface separately or by running just -one process and list of options at command line. Each interface is -separated with -N argument. As an example, following command would -start wpa_supplicant for two interfaces: - -wpa_supplicant \ - -c wpa1.conf -i wlan0 -D hostap -N \ - -c wpa2.conf -i ath0 -D madwifi - - -If the interface is added in a Linux bridge (e.g., br0), the bridge -interface needs to be configured to wpa_supplicant in addition to the -main interface: - -wpa_supplicant -cw.conf -Dmadwifi -iath0 -bbr0 - - -Configuration file ------------------- - -wpa_supplicant is configured using a text file that lists all accepted -networks and security policies, including pre-shared keys. See -example configuration file, wpa_supplicant.conf, for detailed -information about the configuration format and supported fields. - -Changes to configuration file can be reloaded be sending SIGHUP signal -to wpa_supplicant ('killall -HUP wpa_supplicant'). Similarly, -reloading can be triggered with 'wpa_cli reconfigure' command. - -Configuration file can include one or more network blocks, e.g., one -for each used SSID. wpa_supplicant will automatically select the best -betwork based on the order of network blocks in the configuration -file, network security level (WPA/WPA2 is preferred), and signal -strength. - -Example configuration files for some common configurations: - -1) WPA-Personal (PSK) as home network and WPA-Enterprise with EAP-TLS as work - network - -# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group -ctrl_interface=/var/run/wpa_supplicant -ctrl_interface_group=wheel -# -# home network; allow all valid ciphers -network={ - ssid="home" - scan_ssid=1 - key_mgmt=WPA-PSK - psk="very secret passphrase" -} -# -# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers -network={ - ssid="work" - scan_ssid=1 - key_mgmt=WPA-EAP - pairwise=CCMP TKIP - group=CCMP TKIP - eap=TLS - identity="user@example.com" - ca_cert="/etc/cert/ca.pem" - client_cert="/etc/cert/user.pem" - private_key="/etc/cert/user.prv" - private_key_passwd="password" -} - - -2) WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel - (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series) - -ctrl_interface=/var/run/wpa_supplicant -ctrl_interface_group=wheel -network={ - ssid="example" - scan_ssid=1 - key_mgmt=WPA-EAP - eap=PEAP - identity="user@example.com" - password="foobar" - ca_cert="/etc/cert/ca.pem" - phase1="peaplabel=0" - phase2="auth=MSCHAPV2" -} - - -3) EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the - unencrypted use. Real identity is sent only within an encrypted TLS tunnel. - -ctrl_interface=/var/run/wpa_supplicant -ctrl_interface_group=wheel -network={ - ssid="example" - scan_ssid=1 - key_mgmt=WPA-EAP - eap=TTLS - identity="user@example.com" - anonymous_identity="anonymous@example.com" - password="foobar" - ca_cert="/etc/cert/ca.pem" - phase2="auth=MD5" -} - - -4) IEEE 802.1X (i.e., no WPA) with dynamic WEP keys (require both unicast and - broadcast); use EAP-TLS for authentication - -ctrl_interface=/var/run/wpa_supplicant -ctrl_interface_group=wheel -network={ - ssid="1x-test" - scan_ssid=1 - key_mgmt=IEEE8021X - eap=TLS - identity="user@example.com" - ca_cert="/etc/cert/ca.pem" - client_cert="/etc/cert/user.pem" - private_key="/etc/cert/user.prv" - private_key_passwd="password" - eapol_flags=3 -} - - -5) Catch all example that allows more or less all configuration modes. The - configuration options are used based on what security policy is used in the - selected SSID. This is mostly for testing and is not recommended for normal - use. - -ctrl_interface=/var/run/wpa_supplicant -ctrl_interface_group=wheel -network={ - ssid="example" - scan_ssid=1 - key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE - pairwise=CCMP TKIP - group=CCMP TKIP WEP104 WEP40 - psk="very secret passphrase" - eap=TTLS PEAP TLS - identity="user@example.com" - password="foobar" - ca_cert="/etc/cert/ca.pem" - client_cert="/etc/cert/user.pem" - private_key="/etc/cert/user.prv" - private_key_passwd="password" - phase1="peaplabel=0" - ca_cert2="/etc/cert/ca2.pem" - client_cert2="/etc/cer/user.pem" - private_key2="/etc/cer/user.prv" - private_key2_passwd="password" -} - - -6) Authentication for wired Ethernet. This can be used with 'wired' interface - (-Dwired on command line). - -ctrl_interface=/var/run/wpa_supplicant -ctrl_interface_group=wheel -ap_scan=0 -network={ - key_mgmt=IEEE8021X - eap=MD5 - identity="user" - password="password" - eapol_flags=0 -} - - - -Certificates ------------- - -Some EAP authentication methods require use of certificates. EAP-TLS -uses both server side and client certificates whereas EAP-PEAP and -EAP-TTLS only require the server side certificate. When client -certificate is used, a matching private key file has to also be -included in configuration. If the private key uses a passphrase, this -has to be configured in wpa_supplicant.conf ("private_key_passwd"). - -wpa_supplicant supports X.509 certificates in PEM and DER -formats. User certificate and private key can be included in the same -file. - -If the user certificate and private key is received in PKCS#12/PFX -format, they need to be converted to suitable PEM/DER format for -wpa_supplicant. This can be done, e.g., with following commands: - -# convert client certificate and private key to PEM format -openssl pkcs12 -in example.pfx -out user.pem -clcerts -# convert CA certificate (if included in PFX file) to PEM format -openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys - - - -wpa_cli -------- - -wpa_cli is a text-based frontend program for interacting with -wpa_supplicant. It is used to query current status, change -configuration, trigger events, and request interactive user input. - -wpa_cli can show the current authentication status, selected security -mode, dot11 and dot1x MIBs, etc. In addition, it can configure some -variables like EAPOL state machine parameters and trigger events like -reassociation and IEEE 802.1X logoff/logon. wpa_cli provides a user -interface to request authentication information, like username and -password, if these are not included in the configuration. This can be -used to implement, e.g., one-time-passwords or generic token card -authentication where the authentication is based on a -challenge-response that uses an external device for generating the -response. - -The control interface of wpa_supplicant can be configured to allow -non-root user access (ctrl_interface_group in the configuration -file). This makes it possible to run wpa_cli with a normal user -account. - -wpa_cli supports two modes: interactive and command line. Both modes -share the same command set and the main difference is in interactive -mode providing access to unsolicited messages (event messages, -username/password requests). - -Interactive mode is started when wpa_cli is executed without including -the command as a command line parameter. Commands are then entered on -the wpa_cli prompt. In command line mode, the same commands are -entered as command line arguments for wpa_cli. - - -Interactive authentication parameters request - -When wpa_supplicant need authentication parameters, like username and -password, which are not present in the configuration file, it sends a -request message to all attached frontend programs, e.g., wpa_cli in -interactive mode. wpa_cli shows these requests with -"CTRL-REQ-<type>-<id>:<text>" prefix. <type> is IDENTITY, PASSWORD, or -OTP (one-time-password). <id> is a unique identifier for the current -network. <text> is description of the request. In case of OTP request, -it includes the challenge from the authentication server. - -The reply to these requests can be given with 'identity', 'password', -and 'otp' commands. <id> needs to be copied from the the matching -request. 'password' and 'otp' commands can be used regardless of -whether the request was for PASSWORD or OTP. The main difference -between these two commands is that values given with 'password' are -remembered as long as wpa_supplicant is running whereas values given -with 'otp' are used only once and then forgotten, i.e., wpa_supplicant -will ask frontend for a new value for every use. This can be used to -implement one-time-password lists and generic token card -based -authentication. - -Example request for password and a matching reply: - -CTRL-REQ-PASSWORD-1:Password needed for SSID foobar -> password 1 mysecretpassword - -Example request for generic token card challenge-response: - -CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar -> otp 2 9876 - - -wpa_cli commands - - status = get current WPA/EAPOL/EAP status - mib = get MIB variables (dot1x, dot11) - help = show this usage help - interface [ifname] = show interfaces/select interface - level <debug level> = change debug level - license = show full wpa_cli license - logoff = IEEE 802.1X EAPOL state machine logoff - logon = IEEE 802.1X EAPOL state machine logon - set = set variables (shows list of variables when run without arguments) - pmksa = show PMKSA cache - reassociate = force reassociation - reconfigure = force wpa_supplicant to re-read its configuration file - preauthenticate <BSSID> = force preauthentication - identity <network id> <identity> = configure identity for an SSID - password <network id> <password> = configure password for an SSID - pin <network id> <pin> = configure pin for an SSID - otp <network id> <password> = configure one-time-password for an SSID - passphrase <network id> <passphrase> = configure private key passphrase - for an SSID - bssid <network id> <BSSID> = set preferred BSSID for an SSID - list_networks = list configured networks - select_network <network id> = select a network (disable others) - enable_network <network id> = enable a network - disable_network <network id> = disable a network - add_network = add a network - remove_network <network id> = remove a network - set_network <network id> <variable> <value> = set network variables (shows - list of variables when run without arguments) - get_network <network id> <variable> = get network variables - save_config = save the current configuration - disconnect = disconnect and wait for reassociate command before connecting - scan = request new BSS scan - scan_results = get latest scan results - get_capability <eap/pairwise/group/key_mgmt/proto/auth_alg> = get capabilies - terminate = terminate wpa_supplicant - quit = exit wpa_cli - - -wpa_cli command line options - -wpa_cli [-p<path to ctrl sockets>] [-i<ifname>] [-hvB] [-a<action file>] \ - [-P<pid file>] [-g<global ctrl>] [command..] - -h = help (show this usage text) - -v = shown version information - -a = run in daemon mode executing the action file based on events from - wpa_supplicant - -B = run a daemon in the background - default path: /var/run/wpa_supplicant - default interface: first interface found in socket path - - -Using wpa_cli to run external program on connect/disconnect ------------------------------------------------------------ - -wpa_cli can used to run external programs whenever wpa_supplicant -connects or disconnects from a network. This can be used, e.g., to -update network configuration and/or trigget DHCP client to update IP -addresses, etc. - -One wpa_cli process in "action" mode needs to be started for each -interface. For example, the following command starts wpa_cli for the -default ingterface (-i can be used to select the interface in case of -more than one interface being used at the same time): - -wpa_cli -a/sbin/wpa_action.sh -B - -The action file (-a option, /sbin/wpa_action.sh in this example) will -be executed whenever wpa_supplicant completes authentication (connect -event) or detects disconnection). The action script will be called -with two command line arguments: interface name and event (CONNECTED -or DISCONNECTED). If the action script needs to get more information -about the current network, it can use 'wpa_cli status' to query -wpa_supplicant for more information. - -Following example can be used as a simple template for an action -script: - -#!/bin/sh - -IFNAME=$1 -CMD=$2 - -if [ "$CMD" == "CONNECTED" ]; then - SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=` - # configure network, signal DHCP client, etc. -fi - -if [ "$CMD" == "DISCONNECTED" ]; then - # remove network configuration, if needed -fi - - - -Integrating with pcmcia-cs/cardmgr scripts ------------------------------------------- - -wpa_supplicant needs to be running when using a wireless network with -WPA. It can be started either from system startup scripts or from -pcmcia-cs/cardmgr scripts (when using PC Cards). WPA handshake must be -completed before data frames can be exchanged, so wpa_supplicant -should be started before DHCP client. - -Command line option '-w' can be used if wpa_supplicant is started -before the wireless LAN interface is present (e.g., before inserting -the PC Card) or is not yet up. - -For example, following small changes to pcmcia-cs scripts can be used -to enable WPA support: - -Add MODE="Managed" and WPA="y" to the network scheme in -/etc/pcmcia/wireless.opts. - -Add the following block to the end of 'start' action handler in -/etc/pcmcia/wireless: - - if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then - /usr/local/bin/wpa_supplicant -Bw -c/etc/wpa_supplicant.conf \ - -i$DEVICE - fi - -Add the following block to the end of 'stop' action handler (may need -to be separated from other actions) in /etc/pcmcia/wireless: - - if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then - killall wpa_supplicant - fi - -This will make cardmgr start wpa_supplicant when the card is plugged -in. wpa_supplicant will wait until the interface is set up--either -when a static IP address is configured or when DHCP client is -started--and will then negotiate keys with the AP. - - - -Dynamic interface add and operation without configuration files ---------------------------------------------------------------- - -wpa_supplicant can be started without any configuration files or -network interfaces. When used in this way, a global (i.e., per -wpa_supplicant process) control interface is used to add and remove -network interfaces. Each network interface can then be configured -through a per-network interface control interface. For example, -following commands show how to start wpa_supplicant without any -network interfaces and then add a network interface and configure a -network (SSID): - -# Start wpa_supplicant in the background -wpa_supplicant -g/var/run/wpa_supplicant-global -B - -# Add a new interface (wlan0, no configuration file, driver=wext, and -# enable control interface) -wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \ - "" wext /var/run/wpa_supplicant - -# Configure a network using the newly added network interface: -wpa_cli -iwlan0 add_network -wpa_cli -iwlan0 set_network 0 ssid '"test"' -wpa_cli -iwlan0 set_network 0 key_mgmt WPA-PSK -wpa_cli -iwlan0 set_network 0 psk '"12345678"' -wpa_cli -iwlan0 set_network 0 pairwise TKIP -wpa_cli -iwlan0 set_network 0 group TKIP -wpa_cli -iwlan0 set_network 0 proto WPA -wpa_cli -iwlan0 enable_network 0 - -# At this point, the new network interface should start trying to associate -# with the WPA-PSK network using SSID test. - -# Remove network interface -wpa_cli -g/var/run/wpa_supplicant-global interface_remove wlan0 |
