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
28 .Dt WPA_SUPPLICANT.CONF 5
31 .Nm wpa_supplicant.conf
32 .Nd configuration file for
37 utility is an implementation of the WPA Supplicant component,
38 i.e., the part that runs in the client stations.
39 It implements WPA key negotiation with a WPA Authenticator
40 and EAP authentication with Authentication Server using
41 configuration information stored in a text file.
43 The configuration file consists of optional global parameter
44 settings and one or more network blocks, e.g.\&
45 one for each used SSID.
49 will automatically select the best network based on the order of
50 the network blocks in the configuration file, network security level
51 (WPA/WPA2 is preferred), and signal strength.
52 Comments are indicated with the
54 character; all text to the
55 end of the line will be ignored.
57 Default parameters used by
59 may be overridden by specifying
63 in the configuration file (note no spaces are allowed).
64 Values with embedded spaces must be enclosed in quote marks.
66 The following parameters are recognized:
67 .Bl -tag -width indent
69 The pathname of the directory in which
73 domain socket files for communication
74 with frontend programs such as
76 .It Va ctrl_interface_group
77 A group name or group ID to use in setting protection on the
78 control interface file.
79 This can be set to allow non-root users to access the
80 control interface files.
81 If no group is specified, the group ID of the control interface
82 is not modified and will, typically, be the
83 group ID of the directory in which the socket is created.
85 The IEEE 802.1x/EAPOL protocol version to use; either 1 (default) or 2.
89 is implemented according to IEEE 802-1X-REV-d8 which defines
90 EAPOL version to be 2.
91 However, some access points do not work when presented with
92 this version so by default
94 will announce that it is using EAPOL version 1.
95 If version 2 must be announced for correct operation with an
96 access point, this value may be set to 2.
98 Access point scanning and selection control; one of 0, 1 (default), or 2.
99 Only setting 1 should be used with the
101 module; the other settings are for use on other operating systems.
103 EAP fast re-authentication; either 1 (default) or 0.
104 Control fast re-authentication support in EAP methods that support it.
107 Each potential network/access point should have a
109 that describes how to identify it and how to set up security.
110 When multiple network blocks are listed in a configuration file,
111 the highest priority one is selected for use or, if multiple networks
112 with the same priority are identified, the first one listed in the
113 configuration file is used.
115 A network block description is of the form:
116 .Bd -literal -offset indent
126 The block specification contains one or more parameters
127 from the following list:
128 .Bl -tag -width indent
129 .It Va ssid No (required)
130 Network name (as announced by the access point).
133 or hex string enclosed in quotation marks.
135 SSID scan technique; 0 (default) or 1.
136 Technique 0 scans for the SSID using a broadcast Probe Request
137 frame while 1 uses a directed Probe Request frame.
138 Access points that cloak themselves by not broadcasting their SSID
139 require technique 1, but beware that this scheme can cause scanning
140 to take longer to complete.
142 Network BSSID (typically the MAC address of the access point).
144 The priority of a network when selecting among multiple networks;
145 a higher value means a network is more desirable.
146 By default networks have priority 0.
147 When multiple networks with the same priority are considered
148 for selection, other information such as security policy and
149 signal strength are used to select one.
151 IEEE 802.11 operation mode; either 0 (infrastructure, default) or 1 (IBSS).
152 Note that IBSS (adhoc) mode can only be used with
156 (plaintext and static WEP), or
160 (fixed group key TKIP/CCMP).
163 has to be set to 2 for IBSS.
174 CCMP or TKIP (but not both), and
178 List of acceptable protocols; one or more of:
187 If not set this defaults to
190 List of acceptable key management protocols; one or more of:
192 (WPA pre-shared key),
194 (WPA using EAP authentication),
196 (IEEE 802.1x using EAP authentication and,
197 optionally, dynamically generated WEP keys),
199 (plaintext or static WEP keys).
200 If not set this defaults to
201 .Qq Li "WPA-PSK WPA-EAP" .
203 List of allowed IEEE 802.11 authentication algorithms; one or more of:
205 (Open System authentication, required for WPA/WPA2),
207 (Shared Key authentication),
210 If not set automatic selection is used (Open System with LEAP
211 enabled if LEAP is allowed as one of the EAP methods).
213 List of acceptable pairwise (unicast) ciphers for WPA; one or more of:
215 (AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
217 (Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
220 If not set this defaults to
223 List of acceptable group (multicast) ciphers for WPA; one or more of:
225 (AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
227 (Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
229 (WEP with 104-bit key),
231 (WEP with 40-bit key).
232 If not set this defaults to
233 .Qq Li "CCMP TKIP WEP104 WEP40" .
235 WPA preshared key used in WPA-PSK mode.
236 The key is specified as 64 hex digits or as
241 passphrases are dynamically converted to a 256-bit key at runtime
242 using the network SSID, or they can be statically converted at
243 configuration time using
248 Dynamic WEP key usage for non-WPA mode, specified as a bit field.
249 Bit 0 (1) forces dynamically generated unicast WEP keys to be used.
250 Bit 1 (2) forces dynamically generated broadcast WEP keys to be used.
251 By default this is set to 3 (use both).
253 List of acceptable EAP methods; one or more of:
255 (EAP-MD5, cannot be used with WPA,
256 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
258 (EAP-MSCHAPV2, cannot be used with WPA;
259 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
261 (EAP-OTP, cannot be used with WPA;
262 used only as a Phase 2 metod with EAP-PEAP or EAP-TTLS),
264 (EAP-GTC, cannot be used with WPA;
265 used only as a Phase 2 metod with EAP-PEAP or EAP-TTLS),
267 (EAP-TLS, client and server certificate),
269 (EAP-PEAP, with tunneled EAP authentication),
271 (EAP-TTLS, with tunneled EAP or PAP/CHAP/MSCHAP/MSCHAPV2 authentication).
272 If not set this defaults to all available methods compiled in to
273 .Xr wpa_supplicant 8 .
276 is compiled with EAP support; see
279 .Va NO_WPA_SUPPLICANT_EAPOL
280 configuration variable that can be used to disable EAP support.
282 Identity string for EAP.
283 .It Va anonymous_identity
284 Anonymous identity string for EAP (to be used as the unencrypted identity
285 with EAP types that support different tunneled identities; e.g.\& EAP-TTLS).
287 Configure whether networks that allow both plaintext and encryption
288 are allowed when selecting a BSS from the scan results.
289 By default this is set to 0 (disabled).
291 Password string for EAP.
293 Pathname to CA certificate file.
294 This file can have one or more trusted CA certificates.
297 is not included, server certificates will not be verified (not recommended).
299 Pathname to client certificate file (PEM/DER).
301 Pathname to a client private key file (PEM/DER/PFX).
302 When a PKCS#12/PFX file is used, then
304 should not be specified as both the private key and certificate will be
305 read from PKCS#12 file.
306 .It Va private_key_passwd
307 Password for any private key file.
309 Pathname to a file holding DH/DSA parameters (in PEM format).
310 This file holds parameters for an ephemeral DH key exchange.
311 In most cases, the default RSA authentication does not use this configuration.
312 However, it is possible to set up RSA to use an ephemeral DH key exchange.
313 In addition, ciphers with
314 DSA keys always use ephemeral DH keys.
315 This can be used to achieve forward secrecy.
318 is in DSA parameters format, it will be automatically converted
321 Substring to be matched against the subject of the
322 authentication server certificate.
323 If this string is set, the server
324 certificate is only accepted if it contains this string in the subject.
325 The subject string is in following format:
327 .Dl "/C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@example.com"
329 Phase1 (outer authentication, i.e., TLS tunnel) parameters
330 (string with field-value pairs, e.g.,
333 .Qq Li "peapver=1 peaplabel=1" ) .
336 can be used to force which PEAP version (0 or 1) is used.
338 can be used to force new label,
339 .Dq "client PEAP encryption" ,
340 to be used during key derivation when PEAPv1 or newer.
341 Most existing PEAPv1 implementations seem to be using the old label,
342 .Dq Li "client EAP encryption" ,
345 is now using that as the
351 configuration to interoperate with PEAPv1; see
354 .It Li peap_outer_success=0
355 can be used to terminate PEAP authentication on
356 tunneled EAP-Success.
357 This is required with some RADIUS servers that
359 .Pa draft-josefsson-pppext-eap-tls-eap-05.txt
361 .Tn Lucent NavisRadius v4.4.0
365 .It Li include_tls_length=1
369 TLS Message Length field in all TLS messages even if they are not
371 .It Li sim_min_num_chal=3
372 can be used to configure EAP-SIM to require three
373 challenges (by default, it accepts 2 or 3).
374 .It Li fast_provisioning=1
375 option enables in-line provisioning of EAP-FAST
379 phase2: Phase2 (inner authentication with TLS tunnel) parameters
380 (string with field-value pairs, e.g.,
381 .Qq Li "auth=MSCHAPV2"
383 .Qq Li "autheap=MSCHAPV2 autheap=MD5"
388 but for EAP inner Phase 2.
392 but for EAP inner Phase 2.
396 but for EAP inner Phase 2.
397 .It Va private_key2_passwd
399 .Va private_key_passwd
400 but for EAP inner Phase 2.
404 but for EAP inner Phase 2.
405 .It Va subject_match2
408 but for EAP inner Phase 2.
410 16-byte pre-shared key in hex format for use with EAP-PSK.
412 User NAI for use with EAP-PSK.
414 Authentication Server NAI for use with EAP-PSK.
416 Pathname to the file to use for PAC entries with EAP-FAST.
420 must be able to create this file and write updates to it when
421 PAC is being provisioned or refreshed.
422 .It Va eap_workaround
423 Enable/disable EAP workarounds for various interoperability issues
424 with misbehaving authentication servers.
425 By default these workarounds are enabled.
426 Strict EAP conformance can be configured by setting this to 0.
428 which key to use for transmission of packets.
432 string enclosed in quotation marks to encode the WEP key.
433 Without quotes this is a hex string of the actual key.
434 WEP is considered insecure and should be avoided.
435 The exact translation from an ASCII key to a hex key varies.
436 Use hex keys where possible.
439 Some EAP authentication methods require use of certificates.
440 EAP-TLS uses both server- and client-side certificates,
441 whereas EAP-PEAP and EAP-TTLS only require a server-side certificate.
442 When a client certificate is used, a matching private key file must
443 also be included in configuration.
444 If the private key uses a passphrase, this
445 has to be configured in the
448 .Va private_key_passwd .
453 supports X.509 certificates in PEM and DER formats.
454 User certificate and private key can be included in the same file.
456 If the user certificate and private key is received in PKCS#12/PFX
457 format, they need to be converted to a suitable PEM/DER format for
459 .Xr wpa_supplicant 8 .
460 This can be done using the
462 program, e.g.\& with the following commands:
464 # convert client certificate and private key to PEM format
465 openssl pkcs12 -in example.pfx -out user.pem -clcerts
466 # convert CA certificate (if included in PFX file) to PEM format
467 openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
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
475 WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS
478 # allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
479 ctrl_interface=/var/run/wpa_supplicant
480 ctrl_interface_group=wheel
482 # home network; allow all valid ciphers
487 psk="very secret passphrase"
490 # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
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"
506 WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel
507 (e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series):
509 ctrl_interface=/var/run/wpa_supplicant
510 ctrl_interface_group=wheel
516 identity="user@example.com"
518 ca_cert="/etc/cert/ca.pem"
520 phase2="auth=MSCHAPV2"
524 EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
526 Real identity is sent only within an encrypted TLS tunnel.
528 ctrl_interface=/var/run/wpa_supplicant
529 ctrl_interface_group=wheel
535 identity="user@example.com"
536 anonymous_identity="anonymous@example.com"
538 ca_cert="/etc/cert/ca.pem"
543 Traditional WEP configuration with 104 bit key specified in hexadecimal.
544 Note the WEP key is not quoted.
546 ctrl_interface=/var/run/wpa_supplicant
547 ctrl_interface_group=wheel
553 # hex keys denoted without quotes
554 wep_key0=42FEEDDEAFBABEDEAFBEEFAA55
555 # ASCII keys denoted with quotes.
556 wep_key1="FreeBSDr0cks!"
561 .Xr wpa_passphrase 8 ,
568 functionality first appeared in
571 This manual page is derived from the
574 .Pa wpa_supplicant.conf
577 distribution provided by
578 .An Jouni Malinen Aq j@w1.fi .