diff options
Diffstat (limited to 'contrib/wpa_supplicant/README')
| -rw-r--r-- | contrib/wpa_supplicant/README | 858 |
1 files changed, 0 insertions, 858 deletions
diff --git a/contrib/wpa_supplicant/README b/contrib/wpa_supplicant/README deleted file mode 100644 index bab25d586725..000000000000 --- a/contrib/wpa_supplicant/README +++ /dev/null @@ -1,858 +0,0 @@ -WPA Supplicant -============== - -Copyright (c) 2003-2005, Jouni Malinen <jkmaline@cc.hut.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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - -(this copy of the license is in COPYING file) - - -Alternatively, this software may be distributed 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 - * 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 - Alternatively, an external program, e.g., Xsupplicant, can be used for EAP - authentication. -- key management for CCMP, TKIP, WEP104, WEP40 -- RSN/WPA2 (IEEE 802.11i) - * pre-authentication - * PMKSA caching - - - -Requirements ------------- - -Current hardware/software requirements: -- Linux kernel 2.4.x or 2.6.x with Linux Wireless Extensions v15 or newer -- FreeBSD 6-CURRENT -- Microsoft Windows with WinPcap (at least WinXP, may work with other versions) -- drivers: - 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. - - BSD net80211 layer (e.g., Atheros driver) - At the moment, this is for FreeBSD 6-CURRENT branch. - - 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.txt 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_DNET_PCAP=y into -.config. They may also be selected automatically for other operating -systems. - - -Optional libraries for EAP-TLS, EAP-PEAP, and EAP-TTLS: -- openssl (tested with 0.9.7c and 0.9.7d, assumed to work with most - relatively recent versions; this is likely to be available with most - distributions, http://www.openssl.org/) - -This library is only needed when EAP-TLS, EAP-PEAP, or EAP-TTLS -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 this amendment is likely -to be 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). - -Some wireless LAN vendors are already providing support for CCMP in -their WPA products. There is no "official" interoperability -certification for CCMP and/or mixed modes using both TKIP and CCMP, so -some interoperability issues can be expected even though many -combinations seem to be working with equipment from different vendors. -Certification for WPA2 is likely to start during the second half of -2004. - - - -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 or external Xsupplicant - 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 example configuration -and list of available option. - -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. - -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_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 option can be used to replace the native Linux packet socket -interface with libpcap/libdnet. - -CONFIG_DNET_PCAP=y - -Following options can be added to .config to select which driver -interfaces are included. Prism54.org driver is not yet complete and -Hermes driver interface needs to be downloaded from Agere (see above). -Most Linux driver need to include CONFIG_WIRELESS_EXTENSION. - -CONFIG_WIRELESS_EXTENSION=y -CONFIG_DRIVER_HOSTAP=y -CONFIG_DRIVER_PRISM54=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_PRISM54=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_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 [-BddehLqqvw] -i<ifname> -c<config file> [-D<driver>] \ - [-N -i<ifname> -c<conf> [-D<driver>] ...] - -options: - -B = run daemon in the background - -d = increase debugging verbosity (-dd even more) - -K = include keys (passwords, etc.) in debug output - -t = include timestamp in debug messages - -e = use external IEEE 802.1X Supplicant (e.g., xsupplicant) - (this disables the internal Supplicant) - -h = show this help text - -L = show license (GPL and BSD) - -q = decrease debugging verbosity (-qq even less) - -v = show version - -w = wait for interface to be added, if needed - -N = start describing new interface - -drivers: - hostap = Host AP driver (Intersil Prism2/2.5/3) [default] - (this can also be used with Linuxant DriverLoader) - prism54 = Prism54.org driver (Intersil Prism GT/Duette/Indigo) - not yet fully implemented - 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 - 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 - - -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 prefered), 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" -} - - - -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 configuring 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 - otp <network id> <password> = configure one-time-password for an SSID - terminate = terminate wpa_supplicant - quit = exit wpa_cli - - - -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. - - - -Optional integration with Xsupplicant -------------------------------------- - -wpa_supplicant has an integrated IEEE 802.1X Supplicant that supports -most commonly used EAP methods. In addition, wpa_supplicant has an -experimental interface for integrating it with Xsupplicant -(http://www.open1x.org/) for the WPA with EAP authentication. - -When using WPA-EAP, both wpa_supplicant and Xsupplicant must be -configured with the network security policy. See Xsupplicant documents -for information about its configuration. Please also note, that a new -command line option -W (enable WPA) must be used when starting -xsupplicant. - -Example configuration for xsupplicant: - -network_list = all -default_netname = jkm - -jkm -{ - type = wireless - allow_types = eap_peap - identity = <BEGIN_ID>jkm<END_ID> - eap-peap { - random_file = /dev/urandom - root_cert = /home/jkm/CA.pem - chunk_size = 1398 - allow_types = eap_mschapv2 - eap-mschapv2 { - username = <BEGIN_UNAME>jkm<END_UNAME> - password = <BEGIN_PASS>jkm<END_PASS> - } - } -} - - -Example configuration for wpa_supplicant: - -network={ - ssid="jkm" - key_mgmt=WPA-EAP -} - - -Both wpa_supplicant and xsupplicant need to be started. Please remember -to add '-W' option for xsupplicant in order to provide keying material -for wpa_supplicant and '-e' option for wpa_supplicant to disable internal -IEEE 802.1X implementation. - -wpa_supplicant -iwlan0 -cwpa_supplicant.conf -e -xsupplicant -iwlan0 -cxsupplicant.conf -W |