wpa_supplicant.8 (14267B)
- .\" This manpage has been automatically generated by docbook2man
- .\" from a DocBook document. This tool can be found at:
- .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
- .\" Please send any bug reports, improvements, comments, patches,
- .\" etc. to Steve Cheng <steve@ggi-project.org>.
- .TH "WPA_SUPPLICANT" "8" "1 February 2023" "" ""
- .SH NAME
- wpa_supplicant \- Wi-Fi Protected Access client and IEEE 802.1X supplicant
- .SH SYNOPSIS
- \fBwpa_supplicant\fR [ \fB-BddfhKLqqsTtuvW\fR ] [ \fB-i\fIifname\fB\fR ] [ \fB-c\fIconfig file\fB\fR ] [ \fB-D\fIdriver\fB\fR ] [ \fB-P\fIPID_file\fB\fR ] [ \fB-f\fIoutput file\fB\fR ] [ \fB-I\fIadditional config file\fB\fR ]
- .SH "OVERVIEW"
- .PP
- Wireless networks do not require physical access to the network equipment
- in the same way that wired networks do. This makes it easier for unauthorized
- users to passively monitor a network and capture all transmitted frames.
- In addition, unauthorized use of the network is much easier. In many cases,
- this can happen even without user's explicit knowledge since the wireless
- LAN adapter may have been configured to automatically join any available
- network.
- .PP
- Link-layer encryption can be used to provide a layer of security for
- wireless networks. The original wireless LAN standard, IEEE 802.11,
- included a simple encryption mechanism, WEP. However, that proved to
- be flawed in many areas and networks protected with WEP cannot be considered
- secure. IEEE 802.1X authentication and frequently changed dynamic WEP keys
- can be used to improve the network security, but even that has inherited
- security issues due to the use of WEP for encryption. Wi-Fi Protected
- Access and the IEEE 802.11i amendment to the wireless LAN standard introduce
- a much improved mechanism for securing wireless networks. IEEE 802.11i
- enabled networks that are using CCMP (an encryption mechanism based on the strong
- cryptographic algorithm AES) can finally be called secure and used for
- applications which require efficient protection against unauthorized
- access.
- .PP
- \fBwpa_supplicant\fR 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 wireless LAN driver.
- .PP
- \fBwpa_supplicant\fR is designed to be a
- "daemon" program that runs in the background and acts as the
- backend component controlling the wireless
- connection. \fBwpa_supplicant\fR supports separate
- frontend programs and an example text-based frontend,
- \fBwpa_cli\fR, is included with
- wpa_supplicant.
- .PP
- Before wpa_supplicant can do its work, the network interface
- must be available. That means that the physical device must be
- present and enabled, and the driver for the device must be
- loaded. The daemon will exit immediately if the device is not already
- available.
- .PP
- After \fBwpa_supplicant\fR has configured the
- network device, higher level configuration of the device, such as DHCP, may
- proceed. There are a variety of ways to integrate wpa_supplicant
- into a machine's networking scripts, a few of which are described
- in sections below.
- .PP
- The following steps are used when associating with an AP
- using WPA:
- .TP 0.2i
- \(bu
- \fBwpa_supplicant\fR requests the kernel
- driver to scan neighboring BSSes (Basic Service Set)
- .TP 0.2i
- \(bu
- \fBwpa_supplicant\fR selects a BSS based on
- its configuration
- .TP 0.2i
- \(bu
- \fBwpa_supplicant\fR requests the kernel
- driver to associate with the chosen BSS
- .TP 0.2i
- \(bu
- If WPA-EAP: integrated IEEE 802.1X Supplicant
- completes EAP authentication with the
- authentication server (proxied by the Authenticator in the
- AP)
- .TP 0.2i
- \(bu
- If WPA-EAP: master key is received from the IEEE 802.1X
- Supplicant
- .TP 0.2i
- \(bu
- If WPA-PSK: \fBwpa_supplicant\fR uses PSK
- as the master session key
- .TP 0.2i
- \(bu
- \fBwpa_supplicant\fR completes WPA 4-Way
- Handshake and Group Key Handshake with the Authenticator
- (AP)
- .TP 0.2i
- \(bu
- \fBwpa_supplicant\fR configures encryption
- keys for unicast and broadcast
- .TP 0.2i
- \(bu
- normal data packets can be transmitted and received
- .SH "SUPPORTED FEATURES"
- .PP
- Supported WPA/IEEE 802.11i features:
- .TP 0.2i
- \(bu
- WPA-PSK ("WPA-Personal")
- .TP 0.2i
- \(bu
- WPA with EAP (e.g., with RADIUS authentication server)
- ("WPA-Enterprise") Following authentication methods are
- supported with an integrate IEEE 802.1X Supplicant:
- .RS
- .TP 0.2i
- \(bu
- EAP-TLS
- .RE
- .RS
- .TP 0.2i
- \(bu
- EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)
- .TP 0.2i
- \(bu
- EAP-PEAP/TLS (both PEAPv0 and PEAPv1)
- .TP 0.2i
- \(bu
- EAP-PEAP/GTC (both PEAPv0 and PEAPv1)
- .TP 0.2i
- \(bu
- EAP-PEAP/OTP (both PEAPv0 and PEAPv1)
- .TP 0.2i
- \(bu
- EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)
- .TP 0.2i
- \(bu
- EAP-TTLS/EAP-MD5-Challenge
- .TP 0.2i
- \(bu
- EAP-TTLS/EAP-GTC
- .TP 0.2i
- \(bu
- EAP-TTLS/EAP-OTP
- .TP 0.2i
- \(bu
- EAP-TTLS/EAP-MSCHAPv2
- .TP 0.2i
- \(bu
- EAP-TTLS/EAP-TLS
- .TP 0.2i
- \(bu
- EAP-TTLS/MSCHAPv2
- .TP 0.2i
- \(bu
- EAP-TTLS/MSCHAP
- .TP 0.2i
- \(bu
- EAP-TTLS/PAP
- .TP 0.2i
- \(bu
- EAP-TTLS/CHAP
- .TP 0.2i
- \(bu
- EAP-SIM
- .TP 0.2i
- \(bu
- EAP-AKA
- .TP 0.2i
- \(bu
- EAP-PSK
- .TP 0.2i
- \(bu
- EAP-PAX
- .TP 0.2i
- \(bu
- LEAP (note: requires special support from
- the driver for IEEE 802.11 authentication)
- .TP 0.2i
- \(bu
- (following methods are supported, but since
- they do not generate keying material, they cannot be used
- with WPA or IEEE 802.1X WEP keying)
- .TP 0.2i
- \(bu
- EAP-MD5-Challenge
- .TP 0.2i
- \(bu
- EAP-MSCHAPv2
- .TP 0.2i
- \(bu
- EAP-GTC
- .TP 0.2i
- \(bu
- EAP-OTP
- .RE
- .TP 0.2i
- \(bu
- key management for CCMP, TKIP, WEP104, WEP40
- .TP 0.2i
- \(bu
- RSN/WPA2 (IEEE 802.11i)
- .RS
- .TP 0.2i
- \(bu
- pre-authentication
- .TP 0.2i
- \(bu
- PMKSA caching
- .RE
- .SH "AVAILABLE DRIVERS"
- .PP
- A summary of available driver backends is below. Support for each
- of the driver backends is chosen at wpa_supplicant compile time. For a
- list of supported driver backends that may be used with the -D option on
- your system, refer to the help output of wpa_supplicant
- (\fBwpa_supplicant -h\fR).
- .TP
- \fBnl80211\fR
- Uses the modern Linux nl80211/cfg80211 netlink-based
- interface (most new drivers).
- .TP
- \fBwext\fR
- Uses the legacy Linux wireless extensions ioctl-based
- interface (older hardware/drivers).
- .TP
- \fBwired\fR
- wpa_supplicant wired Ethernet driver
- .TP
- \fBmacsec_linux\fR
- MACsec Ethernet driver for Linux
- .TP
- \fBroboswitch\fR
- wpa_supplicant Broadcom switch driver
- .TP
- \fBnone\fR
- no driver (RADIUS server/WPS ER only)
- .TP
- \fBbsd\fR
- BSD 802.11 support (Atheros, etc.).
- .TP
- \fBndis\fR
- Windows NDIS driver.
- .SH "COMMAND LINE OPTIONS"
- .PP
- Most command line options have global scope. Some are given per
- interface, and are only valid if at least one \fB-i\fR option
- is specified, otherwise they're ignored. Option groups for different
- interfaces must be separated by \fB-N\fR option.
- .TP
- \fB-b br_ifname\fR
- Optional bridge interface name. (Per interface)
- .TP
- \fB-B\fR
- Run daemon in the background.
- .TP
- \fB-c filename\fR
- Path to configuration file. (Per interface)
- .TP
- \fB-C ctrl_interface\fR
- Path to ctrl_interface socket (Per interface. Only used if
- \fB-c\fR is not).
- .TP
- \fB-i ifname\fR
- Interface to listen on. Multiple instances of this option can
- be present, one per interface, separated by \fB-N\fR
- option (see below).
- .TP
- \fB-I filename\fR
- Path to additional configuration file.
- .TP
- \fB-d\fR
- Increase debugging verbosity (\fB-dd\fR even
- more).
- .TP
- \fB-D driver\fR
- Driver to use (can be multiple drivers: nl80211,wext).
- (Per interface, see the available options below.)
- .TP
- \fB-e entropy file\fR
- File for \fBwpa_supplicant\fR to use to
- maintain its internal entropy store in over restarts.
- .TP
- \fB-f output file\fR
- Log output to specified file instead of stdout. (This
- is only available if \fBwpa_supplicant\fR was
- built with the CONFIG_DEBUG_FILE
- option.)
- .TP
- \fB-g global ctrl_interface\fR
- Path to global ctrl_interface socket. If specified, interface
- definitions may be omitted.
- .TP
- \fB-K\fR
- Include keys (passwords, etc.) in debug output.
- .TP
- \fB-h\fR
- Help. Show a usage message.
- .TP
- \fB-L\fR
- Show license (BSD).
- .TP
- \fB-o override driver\fR
- Override the driver parameter for new
- interfaces.
- .TP
- \fB-O override ctrl_interface\fR
- Override the ctrl_interface parameter for new
- interfaces.
- .TP
- \fB-p\fR
- Driver parameters. (Per interface)
- .TP
- \fB-P PID_file\fR
- Path to PID file.
- .TP
- \fB-q\fR
- Decrease debugging verbosity (\fB-qq\fR even
- less).
- .TP
- \fB-s\fR
- Log output to syslog instead of stdout. (This is only
- available if \fBwpa_supplicant\fR was built
- with the CONFIG_DEBUG_SYSLOG
- option.)
- .TP
- \fB-T\fR
- Log output to Linux tracing in addition to any other
- destinations. (This is only available
- if \fBwpa_supplicant\fR was built with
- the CONFIG_DEBUG_LINUX_TRACING
- option.)
- .TP
- \fB-t\fR
- Include timestamp in debug messages.
- .TP
- \fB-u\fR
- Enable DBus control interface. If enabled, interface
- definitions may be omitted. (This is only available
- if \fBwpa_supplicant\fR was built with
- the CONFIG_CTRL_IFACE_DBUS_NEW option.)
- .TP
- \fB-v\fR
- Show version.
- .TP
- \fB-W\fR
- Wait for a control interface monitor before starting.
- .TP
- \fB-N\fR
- Start describing new interface.
- .SH "EXAMPLES"
- .PP
- In most common cases, \fBwpa_supplicant\fR is
- started with:
- .sp
- .RS
- .nf
- wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0
- .fi
- .RE
- .PP
- This makes the process fork into the background.
- .PP
- The easiest way to debug problems, and to get a debug log for
- bug reports, is to start \fBwpa_supplicant\fR in the
- foreground with debugging enabled:
- .sp
- .RS
- .nf
- wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d
- .fi
- .RE
- .PP
- If the specific driver wrapper is not known beforehand, it is
- possible to specify multiple comma separated driver wrappers on the command
- line. \fBwpa_supplicant\fR will use the first driver
- wrapper that is able to initialize the interface.
- .sp
- .RS
- .nf
- wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0
- .fi
- .RE
- .PP
- \fBwpa_supplicant\fR 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:
- .sp
- .RS
- .nf
- wpa_supplicant \\
- -c wpa1.conf -i wlan0 -D nl80211 -N \\
- -c wpa2.conf -i ath0 -D wext
- .fi
- .RE
- .SH "OS REQUIREMENTS"
- .PP
- Current hardware/software requirements:
- .TP 0.2i
- \(bu
- Linux kernel 2.6.30 or higher with
- nl80211/cfg80211 support
- .TP 0.2i
- \(bu
- Linux kernel 2.4.x or higher with Linux Wireless
- Extensions v15 or newer
- .TP 0.2i
- \(bu
- FreeBSD 6-CURRENT
- .TP 0.2i
- \(bu
- Microsoft Windows with WinPcap (at least WinXP, may work
- with other versions)
- .SH "SUPPORTED DRIVERS"
- .TP
- \fBLinux nl80211/cfg80211\fR
- This is the preferred driver for Linux.
- .TP
- \fBLinux wireless extensions\fR
- 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.
- .TP
- \fBWired Ethernet drivers\fR
- Use ap_scan=0.
- .TP
- \fBBSD net80211 layer (e.g., Atheros driver)\fR
- At the moment, this is for FreeBSD 6-CURRENT branch.
- .TP
- \fBWindows NDIS\fR
- The current Windows port requires WinPcap
- (http://winpcap.polito.it/). See README-Windows.txt for more
- information.
- .PP
- 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.
- .SH "ARCHITECTURE"
- .PP
- The
- \fBwpa_supplicant\fR system consists of the following
- components:
- .TP
- \fB\fIwpa_supplicant.conf\fB \fR
- the configuration file describing all networks that the
- user wants the computer to connect to.
- .TP
- \fBwpa_supplicant\fR
- the program that directly interacts with the
- network interface.
- .TP
- \fBwpa_cli\fR
- the
- client program that provides a high-level interface to the
- functionality of the daemon.
- .TP
- \fBwpa_passphrase\fR
- a utility needed to construct
- \fIwpa_supplicant.conf\fR files that include
- encrypted passwords.
- .SH "QUICK START"
- .PP
- First, make a configuration file, e.g.
- \fI/etc/wpa_supplicant.conf\fR, that describes the networks
- you are interested in. See \fBwpa_supplicant.conf\fR(5)
- for details.
- .PP
- Once the configuration is ready, you can test whether the
- configuration works by running \fBwpa_supplicant\fR
- with following command to start it on foreground with debugging
- enabled:
- .sp
- .RS
- .nf
- wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d
- .fi
- .RE
- .PP
- Assuming everything goes fine, you can start using following
- command to start \fBwpa_supplicant\fR on background
- without debugging:
- .sp
- .RS
- .nf
- wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B
- .fi
- .RE
- .PP
- 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.
- .SH "INTERFACE TO PCMCIA-CS/CARDMRG"
- .PP
- For example, the following small changes to pcmcia-cs scripts
- can be used to enable WPA support:
- .PP
- Add MODE="Managed" and WPA="y" to the network scheme in
- \fI/etc/pcmcia/wireless.opts\fR\&.
- .PP
- Add the following block to the end of \fBstart\fR
- action handler in \fI/etc/pcmcia/wireless\fR:
- .sp
- .RS
- .nf
- if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
- /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf -i$DEVICE
- fi
- .fi
- .RE
- .PP
- Add the following block to the end of \fBstop\fR
- action handler (may need to be separated from other actions) in
- \fI/etc/pcmcia/wireless\fR:
- .sp
- .RS
- .nf
- if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then
- killall wpa_supplicant
- fi
- .fi
- .RE
- .PP
- This will make \fBcardmgr\fR start
- \fBwpa_supplicant\fR when the card is plugged
- in.
- .SH "SEE ALSO"
- .PP
- \fBwpa_background\fR(8)
- \fBwpa_supplicant.conf\fR(5)
- \fBwpa_cli\fR(8)
- \fBwpa_passphrase\fR(8)
- .SH "LEGAL"
- .PP
- wpa_supplicant is copyright (c) 2003-2022,
- Jouni Malinen <j@w1.fi> and
- contributors.
- All Rights Reserved.
- .PP
- This program is licensed under the BSD license (the one with
- advertisement clause removed).