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