Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
WPA_SUPPLICANT.CONF(5)	  FreeBSD File Formats Manual	WPA_SUPPLICANT.CONF(5)

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 imple-
     ments 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, net-
     work security level (WPA/WPA2 is preferred), and signal strength.	Com-
     ments 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 speci-
     fying

	   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 con-
	     trol 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.  Only setting 1 should be	used with the wlan(4)
	     module; the other settings	are for	use on other operating sys-
	     tems.

     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 specifica-
     tion 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 them-
	     selves by not broadcasting	their SSID require technique 1,	but
	     beware that this scheme can cause scanning	to take	longer to com-
	     plete.

     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 authentica-
	     tion), 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 dynamically converted to a	256-bit	key at runtime
	     using the network SSID, or	they can be statically converted at
	     configuration time	using 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
	     metod with	EAP-PEAP or EAP-TTLS), GTC (EAP-GTC, cannot be used
	     with WPA; used only as a Phase 2 metod 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;	see make.conf(5) for the
	     NO_WPA_SUPPLICANT_EAPOL configuration variable that can be	used
	     to	disable	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 identi-
	     ties; e.g.	EAP-TTLS).

     mixed_cell
	     Configure whether networks	that allow both	plaintext and encryp-
	     tion are allowed when selecting a BSS from	the scan results.  By
	     default this is set to 0 (disabled).

     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 cer-
	     tificates 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 speci-
	     fied 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 con-
	     figuration.  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	for-
	     ward 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 certifi-
	     cate 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 config-
	     ured 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 configura-
     tion.  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	for-
     mat, 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 tun-
     nel.

     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 FreeBSD 6.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>.

FreeBSD	10.1			 July 8, 2007			  FreeBSD 10.1

NAME | DESCRIPTION | GLOBAL PARAMETERS | NETWORK BLOCKS | CERTIFICATES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=wpa_supplicant.conf&sektion=5&manpath=FreeBSD+7.0-RELEASE>

home | help