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