usr.sbin/wpa/wpa_supplicant/wpa_supplicant.conf.5

   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
  35 The
  36 .Xr wpa_supplicant 8
  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.
  42 .Pp
  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.
  46 The
  47 .Xr wpa_supplicant 8
  48 utility
  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
  53 .Ql #
  54 character; all text to the
  55 end of the line will be ignored.
  56 .Sh GLOBAL PARAMETERS
  57 Default parameters used by
  58 .Xr wpa_supplicant 8
  59 may be overridden by specifying
  60 .Pp
  61 .Dl parameter=value
  62 .Pp
  63 in the configuration file (note no spaces are allowed).
  64 Values with embedded spaces must be enclosed in quote marks.
  65 .Pp
  66 The following parameters are recognized:
  67 .Bl -tag -width indent
  68 .It Va ctrl_interface
  69 The pathname of the directory in which
  70 .Xr wpa_supplicant 8
  71 creates
  72 .Ux
  73 domain socket files for communication
  74 with frontend programs such as
  75 .Xr wpa_cli 8 .
  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.
  84 .It Va eapol_version
  85 The IEEE 802.1x/EAPOL protocol version to use; either 1 (default) or 2.
  86 The
  87 .Xr wpa_supplicant 8
  88 utility
  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
  93 .Xr wpa_supplicant 8
  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.
  97 .It Va ap_scan
  98 Access point scanning and selection control; one of 0, 1 (default), or 2.
  99 Only setting 1 should be used with the
 100 .Xr wlan 4
 101 module; the other settings are for use on other operating systems.
 102 .It Va fast_reauth
 103 EAP fast re-authentication; either 1 (default) or 0.
 104 Control fast re-authentication support in EAP methods that support it.
 105 .El
 106 .Sh NETWORK BLOCKS
 107 Each potential network/access point should have a
 108 .Dq "network block"
 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.
 114 .Pp
 115 A network block description is of the form:
 116 .Bd -literal -offset indent
 117 network={
 118         parameter=value
 119         ...
 120 }
 121 .Ed
 122 .Pp
 123 (note the leading
 124 .Qq Li "network={"
 125 may have no spaces).
 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).
 131 An
 132 .Tn ASCII
 133 or hex string enclosed in quotation marks.
 134 .It Va scan_ssid
 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.
 141 .It Va bssid
 142 Network BSSID (typically the MAC address of the access point).
 143 .It Va priority
 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.
 150 .It Va mode
 151 IEEE 802.11 operation mode; either 0 (infrastructure, default) or 1 (IBSS).
 152 Note that IBSS (adhoc) mode can only be used with
 153 .Va key_mgmt
 154 set to
 155 .Li NONE
 156 (plaintext and static WEP), or
 157 .Va key_mgmt
 158 set to
 159 .Li WPA-NONE
 160 (fixed group key TKIP/CCMP).
 161 In addition,
 162 .Va ap_scan
 163 has to be set to 2 for IBSS.
 164 .Li WPA-NONE
 165 requires
 166 .Va proto
 167 set to WPA,
 168 .Va key_mgmt
 169 set to WPA-NONE,
 170 .Va pairwise
 171 set to NONE,
 172 .Va group
 173 set to either
 174 CCMP or TKIP (but not both), and
 175 .Va psk
 176 must also be set.
 177 .It Va proto
 178 List of acceptable protocols; one or more of:
 179 .Li WPA
 180 (IEEE 802.11i/D3.0)
 181 and
 182 .Li RSN
 183 (IEEE 802.11i).
 184 .Li WPA2
 185 is another name for
 186 .Li RSN .
 187 If not set this defaults to
 188 .Qq Li "WPA RSN" .
 189 .It Va key_mgmt
 190 List 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,
 197 optionally, dynamically generated WEP keys),
 198 .Li NONE
 199 (plaintext or static WEP keys).
 200 If not set this defaults to
 201 .Qq Li "WPA-PSK WPA-EAP" .
 202 .It Va auth_alg
 203 List 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).
 210 If not set automatic selection is used (Open System with LEAP
 211 enabled if LEAP is allowed as one of the EAP methods).
 212 .It Va pairwise
 213 List 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).
 220 If not set this defaults to
 221 .Qq Li "CCMP TKIP" .
 222 .It Va group
 223 List 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).
 232 If not set this defaults to
 233 .Qq Li "CCMP TKIP WEP104 WEP40" .
 234 .It Va psk
 235 WPA preshared key used in WPA-PSK mode.
 236 The key is specified as 64 hex digits or as
 237 an 8-63 character
 238 .Tn ASCII
 239 passphrase.
 240 .Tn ASCII
 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
 244 the
 245 .Xr wpa_passphrase 8
 246 utility.
 247 .It Va eapol_flags
 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).
 252 .It Va eap
 253 List of acceptable EAP methods; one or more of:
 254 .Li MD5
 255 (EAP-MD5, cannot be used with WPA,
 256 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
 257 .Li MSCHAPV2
 258 (EAP-MSCHAPV2, cannot be used with WPA;
 259 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
 260 .Li OTP
 261 (EAP-OTP, cannot be used with WPA;
 262 used only as a Phase 2 metod with EAP-PEAP or EAP-TTLS),
 263 .Li GTC
 264 (EAP-GTC, cannot be used with WPA;
 265 used 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).
 272 If not set this defaults to all available methods compiled in to
 273 .Xr wpa_supplicant 8 .
 274 Note that by default
 275 .Xr wpa_supplicant 8
 276 is compiled with EAP support; see
 277 .Xr make.conf 5
 278 for the
 279 .Va NO_WPA_SUPPLICANT_EAPOL
 280 configuration variable that can be used to disable EAP support.
 281 .It Va identity
 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).
 286 .It Va mixed_cell
 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).
 290 .It Va password
 291 Password string for EAP.
 292 .It Va ca_cert
 293 Pathname to CA certificate file.
 294 This file can have one or more trusted CA certificates.
 295 If
 296 .Va ca_cert
 297 is not included, server certificates will not be verified (not recommended).
 298 .It Va client_cert
 299 Pathname to client certificate file (PEM/DER).
 300 .It Va private_key
 301 Pathname to a client private key file (PEM/DER/PFX).
 302 When a PKCS#12/PFX file is used, then
 303 .Va client_cert
 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.
 308 .It Va dh_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.
 316 If the
 317 .Va dh_file
 318 is in DSA parameters format, it will be automatically converted
 319 into DH parameters.
 320 .It Va subject_match
 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:
 326 .Pp
 327 .Dl "/C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@example.com"
 328 .It Va phase1
 329 Phase1 (outer authentication, i.e., TLS tunnel) parameters
 330 (string with field-value pairs, e.g.,
 331 .Qq Li peapver=0
 332 or
 333 .Qq Li "peapver=1 peaplabel=1" ) .
 334 .Bl -inset
 335 .It Li peapver
 336 can be used to force which PEAP version (0 or 1) is used.
 337 .It Li peaplabel=1
 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" ,
 343 and
 344 .Xr wpa_supplicant 8
 345 is now using that as the
 346 default value.
 347 Some servers, e.g.,
 348 .Tn Radiator ,
 349 may require
 350 .Li peaplabel=1
 351 configuration to interoperate with PEAPv1; see
 352 .Pa eap_testing.txt
 353 for more details.
 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
 358 implement
 359 .Pa draft-josefsson-pppext-eap-tls-eap-05.txt
 360 (e.g.,
 361 .Tn Lucent NavisRadius v4.4.0
 362 with PEAP in
 363 .Dq "IETF Draft 5"
 364 mode).
 365 .It Li include_tls_length=1
 366 can be used to force
 367 .Xr wpa_supplicant 8
 368 to include
 369 TLS Message Length field in all TLS messages even if they are not
 370 fragmented.
 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
 376 credentials (PAC).
 377 .El
 378 .It Va phase2
 379 phase2: Phase2 (inner authentication with TLS tunnel) parameters
 380 (string with field-value pairs, e.g.,
 381 .Qq Li "auth=MSCHAPV2"
 382 for EAP-PEAP or
 383 .Qq Li "autheap=MSCHAPV2 autheap=MD5"
 384 for EAP-TTLS).
 385 .It Va ca_cert2
 386 Like
 387 .Va ca_cert
 388 but for EAP inner Phase 2.
 389 .It Va client_cert2
 390 Like
 391 .Va client_cert
 392 but for EAP inner Phase 2.
 393 .It Va private_key2
 394 Like
 395 .Va private_key
 396 but for EAP inner Phase 2.
 397 .It Va private_key2_passwd
 398 Like
 399 .Va private_key_passwd
 400 but for EAP inner Phase 2.
 401 .It Va dh_file2
 402 Like
 403 .Va dh_file
 404 but for EAP inner Phase 2.
 405 .It Va subject_match2
 406 Like
 407 .Va subject_match
 408 but for EAP inner Phase 2.
 409 .It Va eappsk
 410 16-byte pre-shared key in hex format for use with EAP-PSK.
 411 .It Va nai
 412 User NAI for use with EAP-PSK.
 413 .It Va server_nai
 414 Authentication Server NAI for use with EAP-PSK.
 415 .It Va pac_file
 416 Pathname to the file to use for PAC entries with EAP-FAST.
 417 The
 418 .Xr wpa_supplicant 8
 419 utility
 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.
 427 .It Va wep_tx_keyidx
 428 which key to use for transmission of packets.
 429 .It Va wep_keyN key
 430 An
 431 .Tn ASCII
 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.
 437 .El
 438 .Sh CERTIFICATES
 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
 446 .Nm
 447 file as
 448 .Va private_key_passwd .
 449 .Pp
 450 The
 451 .Xr wpa_supplicant 8
 452 utility
 453 supports X.509 certificates in PEM and DER formats.
 454 User certificate and private key can be included in the same file.
 455 .Pp
 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
 458 use by
 459 .Xr wpa_supplicant 8 .
 460 This can be done using the
 461 .Xr openssl 1
 462 program, e.g.\& with the following commands:
 463 .Bd -literal
 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
 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
 475 WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS
 476 as a work network:
 477 .Bd -literal
 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
 481 #
 482 # home network; allow all valid ciphers
 483 network={
 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
 491 network={
 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
 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):
 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=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
 524 EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
 525 unencrypted use.
 526 Real identity is sent only within an encrypted TLS tunnel.
 527 .Bd -literal
 528 ctrl_interface=/var/run/wpa_supplicant
 529 ctrl_interface_group=wheel
 530 network={
 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
 543 Traditional WEP configuration with 104 bit key specified in hexadecimal.
 544 Note the WEP key is not quoted.
 545 .Bd -literal
 546 ctrl_interface=/var/run/wpa_supplicant
 547 ctrl_interface_group=wheel
 548 network={
 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
 564 The
 565 .Nm
 566 manual page and
 567 .Xr wpa_supplicant 8
 568 functionality first appeared in
 569 .Fx 6.0 .
 570 .Sh AUTHORS
 571 This manual page is derived from the
 572 .Pa README
 573 and
 574 .Pa wpa_supplicant.conf
 575 files in the
 576 .Nm wpa_supplicant
 577 distribution provided by
 578 .An Jouni Malinen Aq j@w1.fi .