xref: /freebsd/usr.sbin/wpa/wpa_supplicant/wpa_supplicant.conf.5 (revision 0e97acdf58fe27b09c4824a474b0344daf997c5f)
1.\" Copyright (c) 2005 Sam Leffler <sam@errno.com>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd April 10, 2010
28.Dt WPA_SUPPLICANT.CONF 5
29.Os
30.Sh NAME
31.Nm wpa_supplicant.conf
32.Nd configuration file for
33.Xr wpa_supplicant 8
34.Sh DESCRIPTION
35The
36.Xr wpa_supplicant 8
37utility is an implementation of the WPA Supplicant component,
38i.e., the part that runs in the client stations.
39It implements WPA key negotiation with a WPA Authenticator
40and EAP authentication with Authentication Server using
41configuration information stored in a text file.
42.Pp
43The configuration file consists of optional global parameter
44settings and one or more network blocks, e.g.\&
45one for each used SSID.
46The
47.Xr wpa_supplicant 8
48utility
49will automatically select the best network based on the order of
50the network blocks in the configuration file, network security level
51(WPA/WPA2 is preferred), and signal strength.
52Comments are indicated with the
53.Ql #
54character; all text to the
55end of the line will be ignored.
56.Sh GLOBAL PARAMETERS
57Default parameters used by
58.Xr wpa_supplicant 8
59may be overridden by specifying
60.Pp
61.Dl parameter=value
62.Pp
63in the configuration file (note no spaces are allowed).
64Values with embedded spaces must be enclosed in quote marks.
65.Pp
66The following parameters are recognized:
67.Bl -tag -width indent
68.It Va ctrl_interface
69The pathname of the directory in which
70.Xr wpa_supplicant 8
71creates
72.Ux
73domain socket files for communication
74with frontend programs such as
75.Xr wpa_cli 8 .
76.It Va ctrl_interface_group
77A group name or group ID to use in setting protection on the
78control interface file.
79This can be set to allow non-root users to access the
80control interface files.
81If no group is specified, the group ID of the control interface
82is not modified and will, typically, be the
83group ID of the directory in which the socket is created.
84.It Va eapol_version
85The IEEE 802.1x/EAPOL protocol version to use; either 1 (default) or 2.
86The
87.Xr wpa_supplicant 8
88utility
89is implemented according to IEEE 802-1X-REV-d8 which defines
90EAPOL version to be 2.
91However, some access points do not work when presented with
92this version so by default
93.Xr wpa_supplicant 8
94will announce that it is using EAPOL version 1.
95If version 2 must be announced for correct operation with an
96access point, this value may be set to 2.
97.It Va ap_scan
98Access point scanning and selection control; one of 0, 1 (default), or 2.
99Only setting 1 should be used with the
100.Xr wlan 4
101module; the other settings are for use on other operating systems.
102.It Va fast_reauth
103EAP fast re-authentication; either 1 (default) or 0.
104Control fast re-authentication support in EAP methods that support it.
105.El
106.Sh NETWORK BLOCKS
107Each potential network/access point should have a
108.Dq "network block"
109that describes how to identify it and how to set up security.
110When multiple network blocks are listed in a configuration file,
111the highest priority one is selected for use or, if multiple networks
112with the same priority are identified, the first one listed in the
113configuration file is used.
114.Pp
115A network block description is of the form:
116.Bd -literal -offset indent
117network={
118	parameter=value
119	...
120}
121.Ed
122.Pp
123(note the leading
124.Qq Li "network={"
125may have no spaces).
126The block specification contains one or more parameters
127from the following list:
128.Bl -tag -width indent
129.It Va ssid No (required)
130Network name (as announced by the access point).
131An
132.Tn ASCII
133or hex string enclosed in quotation marks.
134.It Va scan_ssid
135SSID scan technique; 0 (default) or 1.
136Technique 0 scans for the SSID using a broadcast Probe Request
137frame while 1 uses a directed Probe Request frame.
138Access points that cloak themselves by not broadcasting their SSID
139require technique 1, but beware that this scheme can cause scanning
140to take longer to complete.
141.It Va bssid
142Network BSSID (typically the MAC address of the access point).
143.It Va priority
144The priority of a network when selecting among multiple networks;
145a higher value means a network is more desirable.
146By default networks have priority 0.
147When multiple networks with the same priority are considered
148for selection, other information such as security policy and
149signal strength are used to select one.
150.It Va mode
151IEEE 802.11 operation mode; either 0 (infrastructure, default) or 1 (IBSS).
152Note that IBSS (adhoc) mode can only be used with
153.Va key_mgmt
154set to
155.Li NONE
156(plaintext and static WEP), or
157.Va key_mgmt
158set to
159.Li WPA-NONE
160(fixed group key TKIP/CCMP).
161In addition,
162.Va ap_scan
163has to be set to 2 for IBSS.
164.Li WPA-NONE
165requires
166.Va proto
167set to WPA,
168.Va key_mgmt
169set to WPA-NONE,
170.Va pairwise
171set to NONE,
172.Va group
173set to either
174CCMP or TKIP (but not both), and
175.Va psk
176must also be set.
177.It Va proto
178List of acceptable protocols; one or more of:
179.Li WPA
180(IEEE 802.11i/D3.0)
181and
182.Li RSN
183(IEEE 802.11i).
184.Li WPA2
185is another name for
186.Li RSN .
187If not set this defaults to
188.Qq Li "WPA RSN" .
189.It Va key_mgmt
190List of acceptable key management protocols; one or more of:
191.Li WPA-PSK
192(WPA pre-shared key),
193.Li WPA-EAP
194(WPA using EAP authentication),
195.Li IEEE8021X
196(IEEE 802.1x using EAP authentication and,
197optionally, dynamically generated WEP keys),
198.Li NONE
199(plaintext or static WEP keys).
200If not set this defaults to
201.Qq Li "WPA-PSK WPA-EAP" .
202.It Va auth_alg
203List of allowed IEEE 802.11 authentication algorithms; one or more of:
204.Li OPEN
205(Open System authentication, required for WPA/WPA2),
206.Li SHARED
207(Shared Key authentication),
208.Li LEAP
209(LEAP/Network EAP).
210If not set automatic selection is used (Open System with LEAP
211enabled if LEAP is allowed as one of the EAP methods).
212.It Va pairwise
213List of acceptable pairwise (unicast) ciphers for WPA; one or more of:
214.Li CCMP
215(AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
216.Li TKIP
217(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
218.Li NONE
219(deprecated).
220If not set this defaults to
221.Qq Li "CCMP TKIP" .
222.It Va group
223List of acceptable group (multicast) ciphers for WPA; one or more of:
224.Li CCMP
225(AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
226.Li TKIP
227(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
228.Li WEP104
229(WEP with 104-bit key),
230.Li WEP40
231(WEP with 40-bit key).
232If not set this defaults to
233.Qq Li "CCMP TKIP WEP104 WEP40" .
234.It Va psk
235WPA preshared key used in WPA-PSK mode.
236The key is specified as 64 hex digits or as
237an 8-63 character
238.Tn ASCII
239passphrase.
240.Tn ASCII
241passphrases are dynamically converted to a 256-bit key at runtime
242using the network SSID, or they can be statically converted at
243configuration time using
244the
245.Xr wpa_passphrase 8
246utility.
247.It Va eapol_flags
248Dynamic WEP key usage for non-WPA mode, specified as a bit field.
249Bit 0 (1) forces dynamically generated unicast WEP keys to be used.
250Bit 1 (2) forces dynamically generated broadcast WEP keys to be used.
251By default this is set to 3 (use both).
252.It Va eap
253List of acceptable EAP methods; one or more of:
254.Li MD5
255(EAP-MD5, cannot be used with WPA,
256used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
257.Li MSCHAPV2
258(EAP-MSCHAPV2, cannot be used with WPA;
259used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
260.Li OTP
261(EAP-OTP, cannot be used with WPA;
262used only as a Phase 2 metod with EAP-PEAP or EAP-TTLS),
263.Li GTC
264(EAP-GTC, cannot be used with WPA;
265used only as a Phase 2 metod with EAP-PEAP or EAP-TTLS),
266.Li TLS
267(EAP-TLS, client and server certificate),
268.Li PEAP
269(EAP-PEAP, with tunneled EAP authentication),
270.Li TTLS
271(EAP-TTLS, with tunneled EAP or PAP/CHAP/MSCHAP/MSCHAPV2 authentication).
272If not set this defaults to all available methods compiled in to
273.Xr wpa_supplicant 8 .
274Note that by default
275.Xr wpa_supplicant 8
276is compiled with EAP support; see
277.Xr make.conf 5
278for the
279.Va NO_WPA_SUPPLICANT_EAPOL
280configuration variable that can be used to disable EAP support.
281.It Va identity
282Identity string for EAP.
283.It Va anonymous_identity
284Anonymous identity string for EAP (to be used as the unencrypted identity
285with EAP types that support different tunneled identities; e.g.\& EAP-TTLS).
286.It Va mixed_cell
287Configure whether networks that allow both plaintext and encryption
288are allowed when selecting a BSS from the scan results.
289By default this is set to 0 (disabled).
290.It Va password
291Password string for EAP.
292.It Va ca_cert
293Pathname to CA certificate file.
294This file can have one or more trusted CA certificates.
295If
296.Va ca_cert
297is not included, server certificates will not be verified (not recommended).
298.It Va client_cert
299Pathname to client certificate file (PEM/DER).
300.It Va private_key
301Pathname to a client private key file (PEM/DER/PFX).
302When a PKCS#12/PFX file is used, then
303.Va client_cert
304should not be specified as both the private key and certificate will be
305read from PKCS#12 file.
306.It Va private_key_passwd
307Password for any private key file.
308.It Va dh_file
309Pathname to a file holding DH/DSA parameters (in PEM format).
310This file holds parameters for an ephemeral DH key exchange.
311In most cases, the default RSA authentication does not use this configuration.
312However, it is possible to set up RSA to use an ephemeral DH key exchange.
313In addition, ciphers with
314DSA keys always use ephemeral DH keys.
315This can be used to achieve forward secrecy.
316If the
317.Va dh_file
318is in DSA parameters format, it will be automatically converted
319into DH parameters.
320.It Va subject_match
321Substring to be matched against the subject of the
322authentication server certificate.
323If this string is set, the server
324certificate is only accepted if it contains this string in the subject.
325The subject string is in following format:
326.Pp
327.Dl "/C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@example.com"
328.It Va phase1
329Phase1 (outer authentication, i.e., TLS tunnel) parameters
330(string with field-value pairs, e.g.,
331.Qq Li peapver=0
332or
333.Qq Li "peapver=1 peaplabel=1" ) .
334.Bl -inset
335.It Li peapver
336can be used to force which PEAP version (0 or 1) is used.
337.It Li peaplabel=1
338can be used to force new label,
339.Dq "client PEAP encryption" ,
340to be used during key derivation when PEAPv1 or newer.
341Most existing PEAPv1 implementations seem to be using the old label,
342.Dq Li "client EAP encryption" ,
343and
344.Xr wpa_supplicant 8
345is now using that as the
346default value.
347Some servers, e.g.,
348.Tn Radiator ,
349may require
350.Li peaplabel=1
351configuration to interoperate with PEAPv1; see
352.Pa eap_testing.txt
353for more details.
354.It Li peap_outer_success=0
355can be used to terminate PEAP authentication on
356tunneled EAP-Success.
357This is required with some RADIUS servers that
358implement
359.Pa draft-josefsson-pppext-eap-tls-eap-05.txt
360(e.g.,
361.Tn Lucent NavisRadius v4.4.0
362with PEAP in
363.Dq "IETF Draft 5"
364mode).
365.It Li include_tls_length=1
366can be used to force
367.Xr wpa_supplicant 8
368to include
369TLS Message Length field in all TLS messages even if they are not
370fragmented.
371.It Li sim_min_num_chal=3
372can be used to configure EAP-SIM to require three
373challenges (by default, it accepts 2 or 3).
374.It Li fast_provisioning=1
375option enables in-line provisioning of EAP-FAST
376credentials (PAC).
377.El
378.It Va phase2
379phase2: Phase2 (inner authentication with TLS tunnel) parameters
380(string with field-value pairs, e.g.,
381.Qq Li "auth=MSCHAPV2"
382for EAP-PEAP or
383.Qq Li "autheap=MSCHAPV2 autheap=MD5"
384for EAP-TTLS).
385.It Va ca_cert2
386Like
387.Va ca_cert
388but for EAP inner Phase 2.
389.It Va client_cert2
390Like
391.Va client_cert
392but for EAP inner Phase 2.
393.It Va private_key2
394Like
395.Va private_key
396but for EAP inner Phase 2.
397.It Va private_key2_passwd
398Like
399.Va private_key_passwd
400but for EAP inner Phase 2.
401.It Va dh_file2
402Like
403.Va dh_file
404but for EAP inner Phase 2.
405.It Va subject_match2
406Like
407.Va subject_match
408but for EAP inner Phase 2.
409.It Va eappsk
41016-byte pre-shared key in hex format for use with EAP-PSK.
411.It Va nai
412User NAI for use with EAP-PSK.
413.It Va server_nai
414Authentication Server NAI for use with EAP-PSK.
415.It Va pac_file
416Pathname to the file to use for PAC entries with EAP-FAST.
417The
418.Xr wpa_supplicant 8
419utility
420must be able to create this file and write updates to it when
421PAC is being provisioned or refreshed.
422.It Va eap_workaround
423Enable/disable EAP workarounds for various interoperability issues
424with misbehaving authentication servers.
425By default these workarounds are enabled.
426Strict EAP conformance can be configured by setting this to 0.
427.It Va wep_tx_keyidx
428which key to use for transmission of packets.
429.It Va wep_keyN key
430An
431.Tn ASCII
432string enclosed in quotation marks to encode the WEP key.
433Without quotes this is a hex string of the actual key.
434WEP is considered insecure and should be avoided.
435The exact translation from an ASCII key to a hex key varies.
436Use hex keys where possible.
437.El
438.Sh CERTIFICATES
439Some EAP authentication methods require use of certificates.
440EAP-TLS uses both server- and client-side certificates,
441whereas EAP-PEAP and EAP-TTLS only require a server-side certificate.
442When a client certificate is used, a matching private key file must
443also be included in configuration.
444If the private key uses a passphrase, this
445has to be configured in the
446.Nm
447file as
448.Va private_key_passwd .
449.Pp
450The
451.Xr wpa_supplicant 8
452utility
453supports X.509 certificates in PEM and DER formats.
454User certificate and private key can be included in the same file.
455.Pp
456If the user certificate and private key is received in PKCS#12/PFX
457format, they need to be converted to a suitable PEM/DER format for
458use by
459.Xr wpa_supplicant 8 .
460This can be done using the
461.Xr openssl 1
462program, e.g.\& with the following commands:
463.Bd -literal
464# convert client certificate and private key to PEM format
465openssl pkcs12 -in example.pfx -out user.pem -clcerts
466# convert CA certificate (if included in PFX file) to PEM format
467openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
468.Ed
469.Sh FILES
470.Bl -tag -width ".Pa /usr/share/examples/etc/wpa_supplicant.conf" -compact
471.It Pa /etc/wpa_supplicant.conf
472.It Pa /usr/share/examples/etc/wpa_supplicant.conf
473.El
474.Sh EXAMPLES
475WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS
476as a work network:
477.Bd -literal
478# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
479ctrl_interface=/var/run/wpa_supplicant
480ctrl_interface_group=wheel
481#
482# home network; allow all valid ciphers
483network={
484        ssid="home"
485        scan_ssid=1
486        key_mgmt=WPA-PSK
487        psk="very secret passphrase"
488}
489#
490# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
491network={
492        ssid="work"
493        scan_ssid=1
494        key_mgmt=WPA-EAP
495        pairwise=CCMP TKIP
496        group=CCMP TKIP
497        eap=TLS
498        identity="user@example.com"
499        ca_cert="/etc/cert/ca.pem"
500        client_cert="/etc/cert/user.pem"
501        private_key="/etc/cert/user.prv"
502        private_key_passwd="password"
503}
504.Ed
505.Pp
506WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
507(e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series):
508.Bd -literal
509ctrl_interface=/var/run/wpa_supplicant
510ctrl_interface_group=wheel
511network={
512        ssid="example"
513        scan_ssid=1
514        key_mgmt=WPA-EAP
515        eap=PEAP
516        identity="user@example.com"
517        password="foobar"
518        ca_cert="/etc/cert/ca.pem"
519        phase1="peaplabel=0"
520        phase2="auth=MSCHAPV2"
521}
522.Ed
523.Pp
524EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
525unencrypted use.
526Real identity is sent only within an encrypted TLS tunnel.
527.Bd -literal
528ctrl_interface=/var/run/wpa_supplicant
529ctrl_interface_group=wheel
530network={
531        ssid="example"
532        scan_ssid=1
533        key_mgmt=WPA-EAP
534        eap=TTLS
535        identity="user@example.com"
536        anonymous_identity="anonymous@example.com"
537        password="foobar"
538        ca_cert="/etc/cert/ca.pem"
539        phase2="auth=MD5"
540}
541.Ed
542.Pp
543Traditional WEP configuration with 104 bit key specified in hexadecimal.
544Note the WEP key is not quoted.
545.Bd -literal
546ctrl_interface=/var/run/wpa_supplicant
547ctrl_interface_group=wheel
548network={
549        ssid="example"
550        scan_ssid=1
551        key_mgmt=NONE
552        wep_tx_keyidx=0
553	# hex keys denoted without quotes
554        wep_key0=42FEEDDEAFBABEDEAFBEEFAA55
555	# ASCII keys denoted with quotes.
556	wep_key1="FreeBSDr0cks!"
557}
558.Ed
559.Sh SEE ALSO
560.Xr wpa_cli 8 ,
561.Xr wpa_passphrase 8 ,
562.Xr wpa_supplicant 8
563.Sh HISTORY
564The
565.Nm
566manual page and
567.Xr wpa_supplicant 8
568functionality first appeared in
569.Fx 6.0 .
570.Sh AUTHORS
571This manual page is derived from the
572.Pa README
573and
574.Pa wpa_supplicant.conf
575files in the
576.Nm wpa_supplicant
577distribution provided by
578.An Jouni Malinen Aq Mt j@w1.fi .
579