1 .\" Copyright (c) 2005 Sam Leffler <sam@errno.com>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $FreeBSD: src/usr.sbin/wpa/wpa_supplicant/wpa_supplicant.conf.5,v 1.9 2007/07/11 16:04:08 sam Exp $
26 .\" $DragonFly: src/usr.sbin/802_11/wpa_supplicant/wpa_supplicant.conf.5,v 1.4 2007/08/07 11:25:37 sephe Exp $
29 .Dt WPA_SUPPLICANT.CONF 5
32 .Nm wpa_supplicant.conf
33 .Nd configuration file for
38 utility is an implementation of the WPA Supplicant component,
39 i.e., the part that runs in the client stations.
40 It implements WPA key negotiation with a WPA Authenticator
41 and EAP authentication with Authentication Server using
42 configuration information stored in a text file.
44 The configuration file consists of optional global parameter
45 settings and one or more network blocks, e.g.\&
46 one for each used SSID.
50 will automatically select the best network based on the order of
51 the network blocks in the configuration file, network security level
52 (WPA/WPA2 is preferred), and signal strength.
53 Comments are indicated with the
55 character; all text to the
56 end of the line will be ignored.
58 Default parameters used by
60 may be overridden by specifying
64 in the configuration file (note no spaces are allowed).
65 Values with embedded spaces must be enclosed in quote marks.
67 The following parameters are recognized:
68 .Bl -tag -width indent
70 The pathname of the directory in which
74 domain socket files for communication
75 with frontend programs such as
77 .It Va ctrl_interface_group
78 A group name or group ID to use in setting protection on the
79 control interface file.
80 This can be set to allow non-root users to access the
81 control interface files.
82 If no group is specified, the group ID of the control interface
83 is not modified and will, typically, be the
84 group ID of the directory in which the socket is created.
86 The IEEE 802.1x/EAPOL protocol version to use; either 1 (default) or 2.
90 is implemented according to IEEE 802-1X-REV-d8 which defines
91 EAPOL version to be 2.
92 However, some access points do not work when presented with
93 this version so by default
95 will announce that it is using EAPOL version 1.
96 If version 2 must be announced for correct operation with an
97 access point, this value may be set to 2.
99 Access point scanning and selection control; one of 0, 1 (default), or 2.
100 Only setting 1 should be used with the
102 module; the other settings are for use on other operating systems.
104 EAP fast re-authentication; either 1 (default) or 0.
105 Control fast re-authentication support in EAP methods that support it.
108 Each potential network/access point should have a
110 that describes how to identify it and how to set up security.
111 When multiple network blocks are listed in a configuration file,
112 the highest priority one is selected for use or, if multiple networks
113 with the same priority are identified, the first one listed in the
114 configuration file is used.
116 A network block description is of the form:
117 .Bd -literal -offset indent
127 The block specification contains one or more parameters
128 from the following list:
129 .Bl -tag -width indent
130 .It Va ssid No (required)
131 Network name (as announced by the access point).
134 or hex string enclosed in quotation marks.
136 SSID scan technique; 0 (default) or 1.
137 Technique 0 scans for the SSID using a broadcast Probe Request
138 frame while 1 uses a directed Probe Request frame.
139 Access points that cloak themselves by not broadcasting their SSID
140 require technique 1, but beware that this scheme can cause scanning
141 to take longer to complete.
143 Network BSSID (typically the MAC address of the access point).
145 The priority of a network when selecting among multiple networks;
146 a higher value means a network is more desirable.
147 By default networks have priority 0.
148 When multiple networks with the same priority are considered
149 for selection, other information such as security policy and
150 signal strength are used to select one.
152 IEEE 802.11 operation mode; either 0 (infrastructure, default) or 1 (IBSS).
153 Note that IBSS (adhoc) mode can only be used with
157 (plaintext and static WEP).
159 List of acceptable protocols; one or more of:
168 If not set this defaults to
171 List of acceptable key management protocols; one or more of:
173 (WPA pre-shared key),
175 (WPA using EAP authentication),
177 (IEEE 802.1x using EAP authentication and,
178 optionally, dynamically generated WEP keys),
180 (plaintext or static WEP keys).
181 If not set this defaults to
182 .Qq Li "WPA-PSK WPA-EAP" .
184 List of allowed IEEE 802.11 authentication algorithms; one or more of:
186 (Open System authentication, required for WPA/WPA2),
188 (Shared Key authentication),
191 If not set automatic selection is used (Open System with LEAP
192 enabled if LEAP is allowed as one of the EAP methods).
194 List of acceptable pairwise (unicast) ciphers for WPA; one or more of:
196 (AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
198 (Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
201 If not set this defaults to
204 List of acceptable group (multicast) ciphers for WPA; one or more of:
206 (AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
208 (Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
210 (WEP with 104-bit key),
212 (WEP with 40-bit key).
213 If not set this defaults to
214 .Qq Li "CCMP TKIP WEP104 WEP40" .
216 WPA preshared key used in WPA-PSK mode.
217 The key is specified as 64 hex digits or as
222 passphrases are dynamically converted to a 256-bit key at runtime
223 using the network SSID.
225 Dynamic WEP key usage for non-WPA mode, specified as a bit field.
226 Bit 0 (1) forces dynamically generated unicast WEP keys to be used.
227 Bit 1 (2) forces dynamically generated broadcast WEP keys to be used.
228 By default this is set to 3 (use both).
230 List of acceptable EAP methods; one or more of:
232 (EAP-MD5, cannot be used with WPA,
233 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
235 (EAP-MSCHAPV2, cannot be used with WPA;
236 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
238 (EAP-OTP, cannot be used with WPA;
239 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
241 (EAP-GTC, cannot be used with WPA;
242 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
244 (EAP-TLS, client and server certificate),
246 (EAP-PEAP, with tunneled EAP authentication),
248 (EAP-TTLS, with tunneled EAP or PAP/CHAP/MSCHAP/MSCHAPV2 authentication).
249 If not set this defaults to all available methods compiled in to
250 .Xr wpa_supplicant 8 .
253 is compiled with EAP support; see
256 .Va NO_WPA_SUPPLICANT_EAPOL
257 configuration variable that can be used to disable EAP support.
259 Identity string for EAP.
260 .It Va anonymous_identity
261 Anonymous identity string for EAP (to be used as the unencrypted identity
262 with EAP types that support different tunneled identities; e.g.\& EAP-TTLS).
264 Configure whether networks that allow both plaintext and encryption
265 are allowed when selecting a BSS from the scan results.
266 By default this is set to 0 (disabled).
268 Password string for EAP.
270 Pathname to CA certificate file.
271 This file can have one or more trusted CA certificates.
274 is not included, server certificates will not be verified (not recommended).
276 Pathname to client certificate file (PEM/DER).
278 Pathname to a client private key file (PEM/DER/PFX).
279 When a PKCS#12/PFX file is used, then
281 should not be specified as both the private key and certificate will be
282 read from PKCS#12 file.
283 .It Va private_key_passwd
284 Password for any private key file.
286 Pathname to a file holding DH/DSA parameters (in PEM format).
287 This file holds parameters for an ephemeral DH key exchange.
288 In most cases, the default RSA authentication does not use this configuration.
289 However, it is possible to set up RSA to use an ephemeral DH key exchange.
290 In addition, ciphers with
291 DSA keys always use ephemeral DH keys.
292 This can be used to achieve forward secrecy.
295 is in DSA parameters format, it will be automatically converted
298 Substring to be matched against the subject of the
299 authentication server certificate.
300 If this string is set, the server
301 certificate is only accepted if it contains this string in the subject.
302 The subject string is in following format:
304 .Dl "/C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@example.com"
306 Phase1 (outer authentication, i.e., TLS tunnel) parameters
307 (string with field-value pairs, e.g.,
310 .Qq Li "peapver=1 peaplabel=1" ) .
313 can be used to force which PEAP version (0 or 1) is used.
315 can be used to force new label,
316 .Dq "client PEAP encryption" ,
317 to be used during key derivation when PEAPv1 or newer.
318 Most existing PEAPv1 implementations seem to be using the old label,
319 .Dq Li "client EAP encryption" ,
322 is now using that as the
328 configuration to interoperate with PEAPv1; see
331 .It Li peap_outer_success=0
332 can be used to terminate PEAP authentication on
333 tunneled EAP-Success.
334 This is required with some RADIUS servers that
336 .Pa draft-josefsson-pppext-eap-tls-eap-05.txt
338 .Tn Lucent NavisRadius v4.4.0
342 .It Li include_tls_length=1
346 TLS Message Length field in all TLS messages even if they are not
348 .It Li sim_min_num_chal=3
349 can be used to configure EAP-SIM to require three
350 challenges (by default, it accepts 2 or 3)
351 .It Li fast_provisioning=1
352 option enables in-line provisioning of EAP-FAST
356 phase2: Phase2 (inner authentication with TLS tunnel) parameters
357 (string with field-value pairs, e.g.,
358 .Qq Li "auth=MSCHAPV2"
360 .Qq Li "autheap=MSCHAPV2 autheap=MD5"
365 but for EAP inner Phase 2.
369 but for EAP inner Phase 2.
373 but for EAP inner Phase 2.
374 .It Va private_key2_passwd
376 .Va private_key_passwd
377 but for EAP inner Phase 2.
381 but for EAP inner Phase 2.
382 .It Va subject_match2
385 but for EAP inner Phase 2.
387 16-byte pre-shared key in hex format for use with EAP-PSK.
389 User NAI for use with EAP-PSK.
391 Authentication Server NAI for use with EAP-PSK.
393 Pathname to the file to use for PAC entries with EAP-FAST.
397 must be able to create this file and write updates to it when
398 PAC is being provisioned or refreshed.
399 .It Va eap_workaround
400 Enable/disable EAP workarounds for various interoperability issues
401 with misbehaving authentication servers.
402 By default these workarounds are enabled.
403 String EAP conformance can be configured by setting this to 0.
406 Some EAP authentication methods require use of certificates.
407 EAP-TLS uses both server- and client-side certificates,
408 whereas EAP-PEAP and EAP-TTLS only require a server-side certificate.
409 When a client certificate is used, a matching private key file must
410 also be included in configuration.
411 If the private key uses a passphrase, this
412 has to be configured in the
415 .Va private_key_passwd .
420 supports X.509 certificates in PEM and DER formats.
421 User certificate and private key can be included in the same file.
423 If the user certificate and private key is received in PKCS#12/PFX
424 format, they need to be converted to a suitable PEM/DER format for
426 .Xr wpa_supplicant 8 .
427 This can be done using the
429 program, e.g.\& with the following commands:
431 # convert client certificate and private key to PEM format
432 openssl pkcs12 -in example.pfx -out user.pem -clcerts
433 # convert CA certificate (if included in PFX file) to PEM format
434 openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
437 WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS
440 # allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
441 ctrl_interface=/var/run/wpa_supplicant
442 ctrl_interface_group=wheel
444 # home network; allow all valid ciphers
449 psk="very secret passphrase"
452 # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
460 identity="user@example.com"
461 ca_cert="/etc/cert/ca.pem"
462 client_cert="/etc/cert/user.pem"
463 private_key="/etc/cert/user.prv"
464 private_key_passwd="password"
468 WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
469 (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series):
471 ctrl_interface=/var/run/wpa_supplicant
472 ctrl_interface_group=wheel
478 identity="user@example.com"
480 ca_cert="/etc/cert/ca.pem"
482 phase2="auth=MSCHAPV2"
486 EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
488 Real identity is sent only within an encrypted TLS tunnel.
490 ctrl_interface=/var/run/wpa_supplicant
491 ctrl_interface_group=wheel
497 identity="user@example.com"
498 anonymous_identity="anonymous@example.com"
500 ca_cert="/etc/cert/ca.pem"
505 Traditional WEP configuration with 104 bit key specified in hexadecimal.
506 Note the WEP key is not quoted.
508 ctrl_interface=/var/run/wpa_supplicant
509 ctrl_interface_group=wheel
515 wep_key0=42FEEDDEAFBABEDEAFBEEFAA55
526 functionality first appeared in
529 This manual page is derived from the
532 .Pa wpa_supplicant.conf
535 distribution provided by
536 .An Jouni Malinen Aq jkmaline@cc.hut.fi .