xref: /freebsd/usr.sbin/wpa/wpa_supplicant/wpa_supplicant.conf.5 (revision bdd1243df58e60e85101c09001d9812a789b6bc4)
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 March 16, 2022
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 frame.
137Technique 1 uses directed Probe Request frames, sent to each configured SSID.
138Access points that cloak themselves by not broadcasting their SSID require
139technique 1.
140Beware that this technique can cause scanning to take longer to complete,
141and exposes the list of configured network SSIDs to eavesdroppers.
142.It Va bssid
143Network BSSID (typically the MAC address of the access point).
144.It Va priority
145The priority of a network when selecting among multiple networks;
146a higher value means a network is more desirable.
147By default networks have priority 0.
148When multiple networks with the same priority are considered
149for selection, other information such as security policy and
150signal strength are used to select one.
151.It Va mode
152IEEE 802.11 operation mode; either 0 (infrastructure, default) or 1 (IBSS).
153Note that IBSS (adhoc) mode can only be used with
154.Va key_mgmt
155set to
156.Li NONE
157(plaintext and static WEP), or
158.Va key_mgmt
159set to
160.Li WPA-NONE
161(fixed group key TKIP/CCMP).
162In addition,
163.Va ap_scan
164has to be set to 2 for IBSS.
165.Li WPA-NONE
166requires
167.Va proto
168set to WPA,
169.Va key_mgmt
170set to WPA-NONE,
171.Va pairwise
172set to NONE,
173.Va group
174set to either
175CCMP or TKIP (but not both), and
176.Va psk
177must also be set.
178.It Va proto
179List of acceptable protocols; one or more of:
180.Li WPA
181(IEEE 802.11i/D3.0)
182and
183.Li RSN
184(IEEE 802.11i).
185.Li WPA2
186is another name for
187.Li RSN .
188If not set this defaults to
189.Qq Li "WPA RSN" .
190.It Va key_mgmt
191List of acceptable key management protocols; one or more of:
192.Li WPA-PSK
193(WPA pre-shared key),
194.Li WPA-EAP
195(WPA using EAP authentication),
196.Li IEEE8021X
197(IEEE 802.1x using EAP authentication and,
198optionally, dynamically generated WEP keys),
199.Li NONE
200(plaintext or static WEP keys).
201If not set this defaults to
202.Qq Li "WPA-PSK WPA-EAP" .
203.It Va auth_alg
204List of allowed IEEE 802.11 authentication algorithms; one or more of:
205.Li OPEN
206(Open System authentication, required for WPA/WPA2),
207.Li SHARED
208(Shared Key authentication),
209.Li LEAP
210(LEAP/Network EAP).
211If not set automatic selection is used (Open System with LEAP
212enabled if LEAP is allowed as one of the EAP methods).
213.It Va pairwise
214List of acceptable pairwise (unicast) ciphers for WPA; one or more of:
215.Li CCMP
216(AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
217.Li TKIP
218(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
219.Li NONE
220(deprecated).
221If not set this defaults to
222.Qq Li "CCMP TKIP" .
223.It Va group
224List of acceptable group (multicast) ciphers for WPA; one or more of:
225.Li CCMP
226(AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
227.Li TKIP
228(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
229.Li WEP104
230(WEP with 104-bit key),
231.Li WEP40
232(WEP with 40-bit key).
233If not set this defaults to
234.Qq Li "CCMP TKIP WEP104 WEP40" .
235.It Va psk
236WPA preshared key used in WPA-PSK mode.
237The key is specified as 64 hex digits or as
238an 8-63 character
239.Tn ASCII
240passphrase.
241.Tn ASCII
242passphrases are dynamically converted to a 256-bit key at runtime
243using the network SSID, or they can be statically converted at
244configuration time using
245the
246.Xr wpa_passphrase 8
247utility.
248.It Va eapol_flags
249Dynamic WEP key usage for non-WPA mode, specified as a bit field.
250Bit 0 (1) forces dynamically generated unicast WEP keys to be used.
251Bit 1 (2) forces dynamically generated broadcast WEP keys to be used.
252By default this is set to 3 (use both).
253.It Va eap
254List of acceptable EAP methods; one or more of:
255.Li MD5
256(EAP-MD5, cannot be used with WPA,
257used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
258.Li MSCHAPV2
259(EAP-MSCHAPV2, cannot be used with WPA;
260used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
261.Li OTP
262(EAP-OTP, cannot be used with WPA;
263used only as a Phase 2 metod with EAP-PEAP or EAP-TTLS),
264.Li GTC
265(EAP-GTC, cannot be used with WPA;
266used only as a Phase 2 metod with EAP-PEAP or EAP-TTLS),
267.Li TLS
268(EAP-TLS, client and server certificate),
269.Li PEAP
270(EAP-PEAP, with tunneled EAP authentication),
271.Li TTLS
272(EAP-TTLS, with tunneled EAP or PAP/CHAP/MSCHAP/MSCHAPV2 authentication).
273If not set this defaults to all available methods compiled in to
274.Xr wpa_supplicant 8 .
275Note that by default
276.Xr wpa_supplicant 8
277is compiled with EAP support; see
278.Xr make.conf 5
279for the
280.Va NO_WPA_SUPPLICANT_EAPOL
281configuration variable that can be used to disable EAP support.
282.It Va identity
283Identity string for EAP.
284.It Va anonymous_identity
285Anonymous identity string for EAP (to be used as the unencrypted identity
286with EAP types that support different tunneled identities; e.g.\& EAP-TTLS).
287.It Va mixed_cell
288Configure whether networks that allow both plaintext and encryption
289are allowed when selecting a BSS from the scan results.
290By default this is set to 0 (disabled).
291.It Va password
292Password string for EAP.
293.It Va ca_cert
294Pathname to CA certificate file.
295This file can have one or more trusted CA certificates.
296If
297.Va ca_cert
298is not included, server certificates will not be verified (not recommended).
299.It Va client_cert
300Pathname to client certificate file (PEM/DER).
301.It Va private_key
302Pathname to a client private key file (PEM/DER/PFX).
303When a PKCS#12/PFX file is used, then
304.Va client_cert
305should not be specified as both the private key and certificate will be
306read from PKCS#12 file.
307.It Va private_key_passwd
308Password for any private key file.
309.It Va dh_file
310Pathname to a file holding DH/DSA parameters (in PEM format).
311This file holds parameters for an ephemeral DH key exchange.
312In most cases, the default RSA authentication does not use this configuration.
313However, it is possible to set up RSA to use an ephemeral DH key exchange.
314In addition, ciphers with
315DSA keys always use ephemeral DH keys.
316This can be used to achieve forward secrecy.
317If the
318.Va dh_file
319is in DSA parameters format, it will be automatically converted
320into DH parameters.
321.It Va subject_match
322Substring to be matched against the subject of the
323authentication server certificate.
324If this string is set, the server
325certificate is only accepted if it contains this string in the subject.
326The subject string is in following format:
327.Pp
328.Dl "/C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@example.com"
329.It Va phase1
330Phase1 (outer authentication, i.e., TLS tunnel) parameters
331(string with field-value pairs, e.g.,
332.Qq Li peapver=0
333or
334.Qq Li "peapver=1 peaplabel=1" ) .
335.Bl -inset
336.It Li peapver
337can be used to force which PEAP version (0 or 1) is used.
338.It Li peaplabel=1
339can be used to force new label,
340.Dq "client PEAP encryption" ,
341to be used during key derivation when PEAPv1 or newer.
342Most existing PEAPv1 implementations seem to be using the old label,
343.Dq Li "client EAP encryption" ,
344and
345.Xr wpa_supplicant 8
346is now using that as the
347default value.
348Some servers, e.g.,
349.Tn Radiator ,
350may require
351.Li peaplabel=1
352configuration to interoperate with PEAPv1; see
353.Pa eap_testing.txt
354for more details.
355.It Li peap_outer_success=0
356can be used to terminate PEAP authentication on
357tunneled EAP-Success.
358This is required with some RADIUS servers that
359implement
360.Pa draft-josefsson-pppext-eap-tls-eap-05.txt
361(e.g.,
362.Tn Lucent NavisRadius v4.4.0
363with PEAP in
364.Dq "IETF Draft 5"
365mode).
366.It Li include_tls_length=1
367can be used to force
368.Xr wpa_supplicant 8
369to include
370TLS Message Length field in all TLS messages even if they are not
371fragmented.
372.It Li sim_min_num_chal=3
373can be used to configure EAP-SIM to require three
374challenges (by default, it accepts 2 or 3).
375.It Li fast_provisioning=1
376option enables in-line provisioning of EAP-FAST
377credentials (PAC).
378.El
379.It Va phase2
380phase2: Phase2 (inner authentication with TLS tunnel) parameters
381(string with field-value pairs, e.g.,
382.Qq Li "auth=MSCHAPV2"
383for EAP-PEAP or
384.Qq Li "autheap=MSCHAPV2 autheap=MD5"
385for EAP-TTLS).
386.It Va ca_cert2
387Like
388.Va ca_cert
389but for EAP inner Phase 2.
390.It Va client_cert2
391Like
392.Va client_cert
393but for EAP inner Phase 2.
394.It Va private_key2
395Like
396.Va private_key
397but for EAP inner Phase 2.
398.It Va private_key2_passwd
399Like
400.Va private_key_passwd
401but for EAP inner Phase 2.
402.It Va dh_file2
403Like
404.Va dh_file
405but for EAP inner Phase 2.
406.It Va subject_match2
407Like
408.Va subject_match
409but for EAP inner Phase 2.
410.It Va eappsk
41116-byte pre-shared key in hex format for use with EAP-PSK.
412.It Va nai
413User NAI for use with EAP-PSK.
414.It Va server_nai
415Authentication Server NAI for use with EAP-PSK.
416.It Va pac_file
417Pathname to the file to use for PAC entries with EAP-FAST.
418The
419.Xr wpa_supplicant 8
420utility
421must be able to create this file and write updates to it when
422PAC is being provisioned or refreshed.
423.It Va eap_workaround
424Enable/disable EAP workarounds for various interoperability issues
425with misbehaving authentication servers.
426By default these workarounds are enabled.
427Strict EAP conformance can be configured by setting this to 0.
428.It Va wep_tx_keyidx
429which key to use for transmission of packets.
430.It Va wep_keyN key
431An
432.Tn ASCII
433string enclosed in quotation marks to encode the WEP key.
434Without quotes this is a hex string of the actual key.
435WEP is considered insecure and should be avoided.
436The exact translation from an ASCII key to a hex key varies.
437Use hex keys where possible.
438.El
439.Sh CERTIFICATES
440Some EAP authentication methods require use of certificates.
441EAP-TLS uses both server- and client-side certificates,
442whereas EAP-PEAP and EAP-TTLS only require a server-side certificate.
443When a client certificate is used, a matching private key file must
444also be included in configuration.
445If the private key uses a passphrase, this
446has to be configured in the
447.Nm
448file as
449.Va private_key_passwd .
450.Pp
451The
452.Xr wpa_supplicant 8
453utility
454supports X.509 certificates in PEM and DER formats.
455User certificate and private key can be included in the same file.
456.Pp
457If the user certificate and private key is received in PKCS#12/PFX
458format, they need to be converted to a suitable PEM/DER format for
459use by
460.Xr wpa_supplicant 8 .
461This can be done using the
462.Xr openssl 1
463program, e.g.\& with the following commands:
464.Bd -literal
465# convert client certificate and private key to PEM format
466openssl pkcs12 -in example.pfx -out user.pem -clcerts
467# convert CA certificate (if included in PFX file) to PEM format
468openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
469.Ed
470.Sh FILES
471.Bl -tag -width ".Pa /usr/share/examples/etc/wpa_supplicant.conf" -compact
472.It Pa /etc/wpa_supplicant.conf
473.It Pa /usr/share/examples/etc/wpa_supplicant.conf
474.El
475.Sh EXAMPLES
476WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS
477as a work network:
478.Bd -literal
479# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
480ctrl_interface=/var/run/wpa_supplicant
481ctrl_interface_group=wheel
482#
483# home network; allow all valid ciphers
484network={
485        ssid="home"
486        scan_ssid=1
487        key_mgmt=WPA-PSK
488        psk="very secret passphrase"
489}
490#
491# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
492network={
493        ssid="work"
494        scan_ssid=1
495        key_mgmt=WPA-EAP
496        pairwise=CCMP TKIP
497        group=CCMP TKIP
498        eap=TLS
499        identity="user@example.com"
500        ca_cert="/etc/cert/ca.pem"
501        client_cert="/etc/cert/user.pem"
502        private_key="/etc/cert/user.prv"
503        private_key_passwd="password"
504}
505.Ed
506.Pp
507WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
508(e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series):
509.Bd -literal
510ctrl_interface=/var/run/wpa_supplicant
511ctrl_interface_group=wheel
512network={
513        ssid="example"
514        scan_ssid=1
515        key_mgmt=WPA-EAP
516        eap=PEAP
517        identity="user@example.com"
518        password="foobar"
519        ca_cert="/etc/cert/ca.pem"
520        phase1="peaplabel=0"
521        phase2="auth=MSCHAPV2"
522}
523.Ed
524.Pp
525EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
526unencrypted use.
527Real identity is sent only within an encrypted TLS tunnel.
528.Bd -literal
529ctrl_interface=/var/run/wpa_supplicant
530ctrl_interface_group=wheel
531network={
532        ssid="example"
533        scan_ssid=1
534        key_mgmt=WPA-EAP
535        eap=TTLS
536        identity="user@example.com"
537        anonymous_identity="anonymous@example.com"
538        password="foobar"
539        ca_cert="/etc/cert/ca.pem"
540        phase2="auth=MD5"
541}
542.Ed
543.Pp
544Traditional WEP configuration with 104 bit key specified in hexadecimal.
545Note the WEP key is not quoted.
546.Bd -literal
547ctrl_interface=/var/run/wpa_supplicant
548ctrl_interface_group=wheel
549network={
550        ssid="example"
551        scan_ssid=1
552        key_mgmt=NONE
553        wep_tx_keyidx=0
554	# hex keys denoted without quotes
555        wep_key0=42FEEDDEAFBABEDEAFBEEFAA55
556	# ASCII keys denoted with quotes.
557	wep_key1="FreeBSDr0cks!"
558}
559.Ed
560.Pp
561Minimal eduroam configuration.
562.Bd -literal
563ctrl_interface=/var/run/wpa_supplicant
564ctrl_interface_group=wheel
565network={
566        ssid="eduroam"
567        scan_ssid=1
568        key_mgmt=WPA-EAP
569        eap=TTLS
570        identity="user@example.org"
571        password="foobar"
572        phase2="auth=MSCHAPV2"
573}
574.Ed
575.Sh SEE ALSO
576.Xr wpa_cli 8 ,
577.Xr wpa_passphrase 8 ,
578.Xr wpa_supplicant 8
579.Sh HISTORY
580The
581.Nm
582manual page and
583.Xr wpa_supplicant 8
584functionality first appeared in
585.Fx 6.0 .
586.Sh AUTHORS
587This manual page is derived from the
588.Pa README
589and
590.Pa wpa_supplicant.conf
591files in the
592.Nm wpa_supplicant
593distribution provided by
594.An Jouni Malinen Aq Mt j@w1.fi .
595