X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=wpa_supplicant%2FREADME;h=11ab01a9c17101a84e71e4da7e6fd0f95606842d;hb=9c21b2bf45e35ba169d9123941c46cf3b2896d9c;hp=4d02f8f8b2c074f827f716e6f0047d02b93d79a6;hpb=b6c8df695cb236c66a41ac1fe954698cc4286444;p=mech_eap.git diff --git a/wpa_supplicant/README b/wpa_supplicant/README index 4d02f8f..11ab01a 100644 --- a/wpa_supplicant/README +++ b/wpa_supplicant/README @@ -1,37 +1,22 @@ WPA Supplicant ============== -Copyright (c) 2003-2011, Jouni Malinen and contributors +Copyright (c) 2003-2016, Jouni Malinen 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. +This program is licensed under the BSD license (the one with +advertisement clause removed). + +If you are submitting changes to the project, please see CONTRIBUTIONS +file for more instructions. 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: +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 @@ -87,11 +72,13 @@ Supported WPA/IEEE 802.11i features: * EAP-TTLS/CHAP * EAP-SIM * EAP-AKA + * EAP-AKA' * EAP-PSK * EAP-PAX * EAP-SAKE * EAP-IKEv2 * EAP-GPSK + * EAP-pwd * LEAP (note: requires special support from the driver for IEEE 802.11 authentication) (following methods are supported, but since they do not generate keying @@ -130,13 +117,15 @@ Current hardware/software requirements: - 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 + Linux drivers that support cfg80211/nl80211. 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. + note that Linux drivers are moving to use generic wireless configuration + interface driver_nl80211 (-Dnl80211 on wpa_supplicant command line) + should be the default option to start with before falling back to driver + specific interface. + + Linux drivers that support WPA/WPA2 configuration with the generic + Linux wireless extensions (WE-18 or newer). Obsoleted by nl80211. 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 @@ -176,18 +165,12 @@ systems. In case of Windows builds, WinPcap is used by default 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 +- OpenSSL (tested with 1.0.1 and 1.0.2 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 @@ -321,7 +304,7 @@ 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. +TLSv1 implementation can be used for TLS functionality. CONFIG_IEEE8021X_EAPOL=y CONFIG_EAP_MD5=y @@ -333,15 +316,17 @@ CONFIG_EAP_GTC=y CONFIG_EAP_OTP=y CONFIG_EAP_SIM=y CONFIG_EAP_AKA=y +CONFIG_EAP_AKA_PRIME=y CONFIG_EAP_PSK=y CONFIG_EAP_SAKE=y CONFIG_EAP_GPSK=y CONFIG_EAP_PAX=y CONFIG_EAP_LEAP=y CONFIG_EAP_IKEV2=y +CONFIG_EAP_PWD=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 +authentication algorithm (for EAP-SIM/EAP-AKA/EAP-AKA'). This requires pcsc-lite (http://www.linuxnet.com/) for smart card access. CONFIG_PCSC=y @@ -422,10 +407,11 @@ Command line options -------------------- usage: - wpa_supplicant [-BddfhKLqqtuvwW] [-P] [-g] \ + wpa_supplicant [-BddfhKLqqtuvW] [-P] [-g] \ + [-G] \ -i -c [-C] [-D] [-p] \ - [-b [-N -i -c [-C] [-D] \ - [-p] [-b] ...] + [-b [-MN -i -c [-C] [-D] \ + [-p] [-b] [-m] ... options: -b = optional bridge interface name @@ -437,20 +423,23 @@ options: -D = driver name (can be multiple drivers: nl80211,wext) -f = Log output to default log location (normally /tmp) -g = global ctrl_interface + -G = global ctrl_interface group -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) + -L = show license (BSD) -p = driver parameters -P = PID file -q = decrease debugging verbosity (-qq even less) -u = enable DBus control interface -v = show version - -w = wait for interface to be added, if needed -W = wait for a control interface monitor before starting + -M = start describing matching interface -N = start describing new interface + -m = Configuration file for the P2P Device drivers: + nl80211 = Linux nl80211/cfg80211 wext = Linux wireless extensions (generic) wired = wpa_supplicant wired Ethernet driver roboswitch = wpa_supplicant Broadcom switch driver @@ -488,11 +477,27 @@ wpa_supplicant \ -c wpa2.conf -i wlan1 -D wext +If the interfaces on which wpa_supplicant is to run are not known or do +not exist, wpa_supplicant can match an interface when it arrives. Each +matched interface is separated with -M argument and the -i argument now +allows for pattern matching. + +As an example, the following command would start wpa_supplicant for a +specific wired interface called lan0, any interface starting with wlan +and lastly any other interface. Each match has its own configuration +file, and for the wired interface a specific driver has also been given. + +wpa_supplicant \ + -M -c wpa_wired.conf -ilan0 -D wired \ + -M -c wpa1.conf -iwlan* \ + -M -c wpa2.conf + + 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 -Dwext -iwlan0 -bbr0 +wpa_supplicant -cw.conf -Dnl80211 -iwlan0 -bbr0 Configuration file @@ -509,7 +514,7 @@ 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 +network based on the order of network blocks in the configuration file, network security level (WPA/WPA2 is preferred), and signal strength. @@ -801,7 +806,7 @@ 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 +default interface (-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 @@ -884,10 +889,10 @@ 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 +# Add a new interface (wlan0, no configuration file, driver=nl80211, and # enable control interface) wpa_cli -g/var/run/wpa_supplicant-global interface_add wlan0 \ - "" wext /var/run/wpa_supplicant + "" nl80211 /var/run/wpa_supplicant # Configure a network using the newly added network interface: wpa_cli -iwlan0 add_network @@ -948,7 +953,7 @@ Example configuration: chmod 0750 /var/run/wpa_priv - start wpa_priv as root (e.g., from system startup scripts) with the enabled interfaces configured on the command line: - wpa_priv -B -P /var/run/wpa_priv.pid wext:ath0 + wpa_priv -B -P /var/run/wpa_priv.pid nl80211:wlan0 - run wpa_supplicant as non-root with a user that is in wpapriv group: wpa_supplicant -i ath0 -c wpa_supplicant.conf @@ -959,3 +964,105 @@ can be started when an interface is added (hotplug/udev/etc. scripts). wpa_priv can control multiple interface with one process, but it is also possible to run multiple wpa_priv processes at the same time, if desired. + + +Linux capabilities instead of privileged process +------------------------------------------------ + +wpa_supplicant performs operations that need special permissions, e.g., +to control the network connection. Traditionally this has been achieved +by running wpa_supplicant as a privileged process with effective user id +0 (root). Linux capabilities can be used to provide restricted set of +capabilities to match the functions needed by wpa_supplicant. The +minimum set of capabilities needed for the operations is CAP_NET_ADMIN +and CAP_NET_RAW. + +setcap(8) can be used to set file capabilities. For example: + +sudo setcap cap_net_raw,cap_net_admin+ep wpa_supplicant + +Please note that this would give anyone being able to run that +wpa_supplicant binary access to the additional capabilities. This can +further be limited by file owner/group and mode bits. For example: + +sudo chown wpas wpa_supplicant +sudo chmod 0100 wpa_supplicant + +This combination of setcap, chown, and chmod commands would allow wpas +user to execute wpa_supplicant with additional network admin/raw +capabilities. + +Common way style of creating a control interface socket in +/var/run/wpa_supplicant could not be done by this user, but this +directory could be created before starting the wpa_supplicant and set to +suitable mode to allow wpa_supplicant to create sockets +there. Alternatively, other directory or abstract socket namespace could +be used for the control interface. + + +External requests for radio control +----------------------------------- + +External programs can request wpa_supplicant to not start offchannel +operations during other tasks that may need exclusive control of the +radio. The RADIO_WORK control interface command can be used for this. + +"RADIO_WORK add [freq=] [timeout=]" command can be +used to reserve a slot for radio access. If freq is specified, other +radio work items on the same channel may be completed in +parallel. Otherwise, all other radio work items are blocked during +execution. Timeout is set to 10 seconds by default to avoid blocking +wpa_supplicant operations for excessive time. If a longer (or shorter) +safety timeout is needed, that can be specified with the optional +timeout parameter. This command returns an identifier for the radio work +item. + +Once the radio work item has been started, "EXT-RADIO-WORK-START " +event message is indicated that the external processing can start. Once +the operation has been completed, "RADIO_WORK done " is used to +indicate that to wpa_supplicant. This allows other radio works to be +performed. If this command is forgotten (e.g., due to the external +program terminating), wpa_supplicant will time out the radio work item +and send "EXT-RADIO-WORK-TIMEOUT " event to indicate that this has +happened. "RADIO_WORK done " can also be used to cancel items that +have not yet been started. + +For example, in wpa_cli interactive mode: + +> radio_work add test +1 +<3>EXT-RADIO-WORK-START 1 +> radio_work show +ext:test@wlan0:0:1:2.487797 +> radio_work done 1 +OK +> radio_work show + + +> radio_work done 3 +OK +> radio_work show +ext:test freq=2412 timeout=30@wlan0:2412:1:28.583483 +<3>EXT-RADIO-WORK-TIMEOUT 2 + + +> radio_work add test2 freq=2412 timeout=60 +5 +<3>EXT-RADIO-WORK-START 5 +> radio_work add test3 +6 +> radio_work add test4 +7 +> radio_work show +ext:test2 freq=2412 timeout=60@wlan0:2412:1:9.751844 +ext:test3@wlan0:0:0:5.071812 +ext:test4@wlan0:0:0:3.143870 +> radio_work done 6 +OK +> radio_work show +ext:test2 freq=2412 timeout=60@wlan0:2412:1:16.287869 +ext:test4@wlan0:0:0:9.679895 +> radio_work done 5 +OK +<3>EXT-RADIO-WORK-START 7 +<3>EXT-RADIO-WORK-TIMEOUT 7