NAME
wpa_supplicant.conf —
configuration
file for
wpa_supplicant(8)
DESCRIPTION
The
wpa_supplicant(8)
utility 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 using
configuration information stored in a text file.
The configuration file consists of optional global parameter settings and one or
more network blocks, e.g. one for each used SSID. The
wpa_supplicant(8)
utility will automatically select the best network based on the order of the
network blocks in the configuration file, network security level (WPA/WPA2 is
preferred), and signal strength. Comments are indicated with the
‘
#
’ character; all text to the end of the
line will be ignored.
GLOBAL PARAMETERS
Default parameters used by
wpa_supplicant(8) may be
overridden by specifying
parameter=value
in the configuration file (note no spaces are allowed). Values with embedded
spaces must be enclosed in quote marks.
The following parameters are recognized:
-
-
- ctrl_interface
- The pathname of the directory in which
wpa_supplicant(8)
creates UNIX domain socket files for communication
with frontend programs such as
wpa_cli(8).
-
-
- ctrl_interface_group
- A group name or group ID to use in setting protection on
the control interface file. This can be set to allow non-root users to
access the control interface files. If no group is specified, the group ID
of the control interface is not modified and will, typically, be the group
ID of the directory in which the socket is created.
-
-
- eapol_version
- The IEEE 802.1x/EAPOL protocol version to use; either 1
(default) or 2. The
wpa_supplicant(8)
utility is implemented according to IEEE 802-1X-REV-d8 which defines EAPOL
version to be 2. However, some access points do not work when presented
with this version so by default
wpa_supplicant(8)
will announce that it is using EAPOL version 1. If version 2 must be
announced for correct operation with an access point, this value may be
set to 2.
-
-
- ap_scan
- Access point scanning and selection control; one of 0, 1
(default), or 2.
-
-
- fast_reauth
- EAP fast re-authentication; either 1 (default) or 0.
Control fast re-authentication support in EAP methods that support
it.
NETWORK BLOCKS
Each potential network/access point should have a “network block”
that describes how to identify it and how to set up security. When multiple
network blocks are listed in a configuration file, the highest priority one is
selected for use or, if multiple networks with the same priority are
identified, the first one listed in the configuration file is used.
A network block description is of the form:
network={
parameter=value
...
}
(note the leading “
network={
” may have no
spaces). The block specification contains one or more parameters from the
following list:
-
-
- ssid
(required)
- Network name (as announced by the access point). An ASCII
or hex string enclosed in quotation marks.
-
-
- scan_ssid
- SSID scan technique; 0 (default) or 1. Technique 0 scans
for the SSID using a broadcast Probe Request frame while 1 uses a directed
Probe Request frame. Access points that cloak themselves by not
broadcasting their SSID require technique 1, but beware that this scheme
can cause scanning to take longer to complete.
-
-
- bssid
- Network BSSID (typically the MAC address of the access
point).
-
-
- priority
- The priority of a network when selecting among multiple
networks; a higher value means a network is more desirable. By default
networks have priority 0. When multiple networks with the same priority
are considered for selection, other information such as security policy
and signal strength are used to select one.
-
-
- mode
- IEEE 802.11 operation mode; either 0 (infrastructure,
default) or 1 (IBSS). Note that IBSS (adhoc) mode can only be used with
key_mgmt set to
NONE
(plaintext and static WEP).
-
-
- proto
- List of acceptable protocols; one or more of:
WPA
(IEEE 802.11i/D3.0) and
RSN
(IEEE 802.11i). WPA2
is another name for RSN
. If not set this defaults
to “WPA RSN
”.
-
-
- key_mgmt
- List of acceptable key management protocols; one or more
of:
WPA-PSK
(WPA pre-shared key),
WPA-EAP
(WPA using EAP authentication),
IEEE8021X
(IEEE 802.1x using EAP authentication
and, optionally, dynamically generated WEP keys),
NONE
(plaintext or static WEP keys). If not set
this defaults to “WPA-PSK
WPA-EAP
”.
-
-
- auth_alg
- List of allowed IEEE 802.11 authentication algorithms; one
or more of:
OPEN
(Open System authentication,
required for WPA/WPA2), SHARED
(Shared Key
authentication), LEAP
(LEAP/Network EAP). If not
set automatic selection is used (Open System with LEAP enabled if LEAP is
allowed as one of the EAP methods).
-
-
- pairwise
- List of acceptable pairwise (unicast) ciphers for WPA; one
or more of:
CCMP
(AES in Counter mode with
CBC-MAC, RFC 3610, IEEE 802.11i/D7.0), TKIP
(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
NONE
(deprecated). If not set this defaults to
“CCMP TKIP
”.
-
-
- group
- List of acceptable group (multicast) ciphers for WPA; one
or more of:
CCMP
(AES in Counter mode with
CBC-MAC, RFC 3610, IEEE 802.11i/D7.0), TKIP
(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
WEP104
(WEP with 104-bit key),
WEP40
(WEP with 40-bit key). If not set this
defaults to “CCMP TKIP WEP104
WEP40
”.
-
-
- psk
- WPA preshared key used in WPA-PSK mode. The key is
specified as 64 hex digits or as an 8-63 character ASCII passphrase. ASCII
passphrases are converted to a 256-bit key using the network SSID by the
wpa_passphrase(8)
utility.
-
-
- eapol_flags
- Dynamic WEP key usage for non-WPA mode, specified as a bit
field. Bit 0 (1) forces dynamically generated unicast WEP keys to be used.
Bit 1 (2) forces dynamically generated broadcast WEP keys to be used. By
default this is set to 3 (use both).
-
-
- eap
- List of acceptable EAP methods; one or more of:
MD5
(EAP-MD5, cannot be used with WPA, used only
as a Phase 2 method with EAP-PEAP or EAP-TTLS),
MSCHAPV2
(EAP-MSCHAPV2, cannot be used with WPA;
used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
OTP
(EAP-OTP, cannot be used with WPA; used only
as a Phase 2 method with EAP-PEAP or EAP-TTLS),
GTC
(EAP-GTC, cannot be used with WPA; used only
as a Phase 2 method with EAP-PEAP or EAP-TTLS),
TLS
(EAP-TLS, client and server certificate),
PEAP
(EAP-PEAP, with tunneled EAP authentication),
TTLS
(EAP-TTLS, with tunneled EAP or
PAP/CHAP/MSCHAP/MSCHAPV2 authentication). If not set this defaults to all
available methods compiled in to
wpa_supplicant(8).
Note that by default
wpa_supplicant(8) is
compiled with EAP support.
-
-
- identity
- Identity string for EAP.
-
-
- anonymous_identity
- Anonymous identity string for EAP (to be used as the
unencrypted identity with EAP types that support different tunneled
identities; e.g. EAP-TTLS).
-
-
- password
- Password string for EAP.
-
-
- ca_cert
- Pathname to CA certificate file. This file can have one or
more trusted CA certificates. If ca_cert is not
included, server certificates will not be verified (not recommended).
-
-
- client_cert
- Pathname to client certificate file (PEM/DER).
-
-
- private_key
- Pathname to a client private key file (PEM/DER/PFX). When a
PKCS#12/PFX file is used, then client_cert should
not be specified as both the private key and certificate will be read from
PKCS#12 file.
-
-
- private_key_passwd
- Password for any private key file.
-
-
- dh_file
- Pathname to a file holding DH/DSA parameters (in PEM
format). This file holds parameters for an ephemeral DH key exchange. In
most cases, the default RSA authentication does not use this
configuration. However, it is possible to set up RSA to use an ephemeral
DH key exchange. In addition, ciphers with DSA keys always use ephemeral
DH keys. This can be used to achieve forward secrecy. If the
dh_file is in DSA parameters format, it will be
automatically converted into DH params.
-
-
- subject_match
- Substring to be matched against the subject of the
authentication server certificate. If this string is set, the server
certificate is only accepted if it contains this string in the subject.
The subject string is in following format:
/C=US/ST=CA/L=San Francisco/CN=Test
AS/emailAddress=as@example.com
-
-
- phase1
- Phase1 (outer authentication, i.e., TLS tunnel) parameters
(string with field-value pairs, e.g.,
“
peapver=0
” or
“peapver=1 peaplabel=1
”).
peapver
- can be used to force which PEAP version (0 or 1) is
used.
peaplabel=1
- can be used to force new label, “client PEAP
encryption”, to be used during key derivation when PEAPv1 or
newer. Most existing PEAPv1 implementations seem to be using the old
label, “
client EAP encryption
”,
and
wpa_supplicant(8)
is now using that as the default value. Some servers, e.g., Radiator,
may require peaplabel=1
configuration to
interoperate with PEAPv1; see eap_testing.txt for
more details.
peap_outer_success=0
- can be used to terminate PEAP authentication on
tunneled EAP-Success. This is required with some RADIUS servers that
implement draft-josefsson-pppext-eap-tls-eap-05.txt
(e.g., Lucent NavisRadius v4.4.0 with PEAP in “IETF Draft
5” mode).
include_tls_length=1
- can be used to force
wpa_supplicant(8)
to include TLS Message Length field in all TLS messages even if they
are not fragmented.
sim_min_num_chal=3
- can be used to configure EAP-SIM to require three
challenges (by default, it accepts 2 or 3)
fast_provisioning=1
- option enables in-line provisioning of EAP-FAST
credentials (PAC).
-
-
- phase2
- phase2: Phase2 (inner authentication with TLS tunnel)
parameters (string with field-value pairs, e.g.,
“
auth=MSCHAPV2
” for EAP-PEAP or
“autheap=MSCHAPV2 autheap=MD5
” for
EAP-TTLS).
-
-
- ca_cert2
- Like ca_cert but for EAP inner Phase
2.
-
-
- client_cert2
- Like client_cert but for EAP inner
Phase 2.
-
-
- private_key2
- Like private_key but for EAP inner
Phase 2.
-
-
- private_key2_passwd
- Like private_key_passwd but for EAP
inner Phase 2.
-
-
- dh_file2
- Like dh_file but for EAP inner Phase
2.
-
-
- subject_match2
- Like subject_match but for EAP inner
Phase 2.
-
-
- eappsk
- 16-byte pre-shared key in hex format for use with
EAP-PSK.
-
-
- nai
- User NAI for use with EAP-PSK.
-
-
- server_nai
- Authentication Server NAI for use with EAP-PSK.
-
-
- pac_file
- Pathname to the file to use for PAC entries with EAP-FAST.
The
wpa_supplicant(8)
utility must be able to create this file and write updates to it when PAC
is being provisioned or refreshed.
-
-
- eap_workaround
- Enable/disable EAP workarounds for various interoperability
issues with misbehaving authentication servers. By default these
workarounds are enabled. String EAP conformance can be configured by
setting this to 0.
CERTIFICATES
Some EAP authentication methods require use of certificates. EAP-TLS uses both
server- and client-side certificates, whereas EAP-PEAP and EAP-TTLS only
require a server-side certificate. When a client certificate is used, a
matching private key file must also be included in configuration. If the
private key uses a passphrase, this has to be configured in the
wpa_supplicant.conf file as
private_key_passwd.
The
wpa_supplicant(8)
utility 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 a suitable PEM/DER format for use by
wpa_supplicant(8). This
can be done using the
openssl(1) program, e.g. with
the 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
EXAMPLES
WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS as a 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"
}
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"
}
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"
}
Traditional WEP configuration with 104 bit key specified in hexadecimal. Note
the WEP key is not quoted.
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
network={
ssid="example"
scan_ssid=1
key_mgmt=NONE
wep_tx_keyidx=0
wep_key0=42FEEDDEAFBABEDEAFBEEFAA55
}
SEE ALSO
wpa_cli(8),
wpa_passphrase(8),
wpa_supplicant(8)
HISTORY
The
wpa_supplicant.conf manual page and
wpa_supplicant(8)
functionality first appeared in
NetBSD 4.0.
AUTHORS
This manual page is derived from the
README and
wpa_supplicant.conf files in the
wpa_supplicant distribution provided by
Jouni Malinen
<
jkmaline@cc.hut.fi>.