usr.sbin/802_11/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: 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 $
  27 .\"
  28 .Dd July 22, 2007
  29 .Dt WPA_SUPPLICANT.CONF 5
  30 .Os
  31 .Sh NAME
  32 .Nm wpa_supplicant.conf
  33 .Nd configuration file for
  34 .Xr wpa_supplicant 8
  35 .Sh DESCRIPTION
  36 The
  37 .Xr wpa_supplicant 8
  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.
  43 .Pp
  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.
  47 The
  48 .Xr wpa_supplicant 8
  49 utility
  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
  54 .Ql #
  55 character; all text to the
  56 end of the line will be ignored.
  57 .Sh GLOBAL PARAMETERS
  58 Default parameters used by
  59 .Xr wpa_supplicant 8
  60 may be overridden by specifying
  61 .Pp
  62 .Dl parameter=value
  63 .Pp
  64 in the configuration file (note no spaces are allowed).
  65 Values with embedded spaces must be enclosed in quote marks.
  66 .Pp
  67 The following parameters are recognized:
  68 .Bl -tag -width indent
  69 .It Va ctrl_interface
  70 The pathname of the directory in which
  71 .Xr wpa_supplicant 8
  72 creates
  73 .Ux
  74 domain socket files for communication
  75 with frontend programs such as
  76 .Xr wpa_cli 8 .
  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.
  85 .It Va eapol_version
  86 The IEEE 802.1x/EAPOL protocol version to use; either 1 (default) or 2.
  87 The
  88 .Xr wpa_supplicant 8
  89 utility
  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
  94 .Xr wpa_supplicant 8
  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.
  98 .It Va ap_scan
  99 Access point scanning and selection control; one of 0, 1 (default), or 2.
 100 Only setting 1 should be used with the
 101 .Xr wlan 4
 102 module; the other settings are for use on other operating systems.
 103 .It Va fast_reauth
 104 EAP fast re-authentication; either 1 (default) or 0.
 105 Control fast re-authentication support in EAP methods that support it.
 106 .El
 107 .Sh NETWORK BLOCKS
 108 Each potential network/access point should have a
 109 .Dq "network block"
 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.
 115 .Pp
 116 A network block description is of the form:
 117 .Bd -literal -offset indent
 118 network={
 119         parameter=value
 120         ...
 121 }
 122 .Ed
 123 .Pp
 124 (note the leading
 125 .Qq Li "network={"
 126 may have no spaces).
 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).
 132 An
 133 .Tn ASCII
 134 or hex string enclosed in quotation marks.
 135 .It Va scan_ssid
 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.
 142 .It Va bssid
 143 Network BSSID (typically the MAC address of the access point).
 144 .It Va priority
 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.
 151 .It Va mode
 152 IEEE 802.11 operation mode; either 0 (infrastructure, default) or 1 (IBSS).
 153 Note that IBSS (adhoc) mode can only be used with
 154 .Va key_mgmt
 155 set to
 156 .Li NONE
 157 (plaintext and static WEP).
 158 .It Va proto
 159 List of acceptable protocols; one or more of:
 160 .Li WPA
 161 (IEEE 802.11i/D3.0)
 162 and
 163 .Li RSN
 164 (IEEE 802.11i).
 165 .Li WPA2
 166 is another name for
 167 .Li RSN .
 168 If not set this defaults to
 169 .Qq Li "WPA RSN" .
 170 .It Va key_mgmt
 171 List of acceptable key management protocols; one or more of:
 172 .Li WPA-PSK
 173 (WPA pre-shared key),
 174 .Li WPA-EAP
 175 (WPA using EAP authentication),
 176 .Li IEEE8021X
 177 (IEEE 802.1x using EAP authentication and,
 178 optionally, dynamically generated WEP keys),
 179 .Li NONE
 180 (plaintext or static WEP keys).
 181 If not set this defaults to
 182 .Qq Li "WPA-PSK WPA-EAP" .
 183 .It Va auth_alg
 184 List of allowed IEEE 802.11 authentication algorithms; one or more of:
 185 .Li OPEN
 186 (Open System authentication, required for WPA/WPA2),
 187 .Li SHARED
 188 (Shared Key authentication),
 189 .Li LEAP
 190 (LEAP/Network EAP).
 191 If not set automatic selection is used (Open System with LEAP
 192 enabled if LEAP is allowed as one of the EAP methods).
 193 .It Va pairwise
 194 List of acceptable pairwise (unicast) ciphers for WPA; one or more of:
 195 .Li CCMP
 196 (AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
 197 .Li TKIP
 198 (Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
 199 .Li NONE
 200 (deprecated).
 201 If not set this defaults to
 202 .Qq Li "CCMP TKIP" .
 203 .It Va group
 204 List of acceptable group (multicast) ciphers for WPA; one or more of:
 205 .Li CCMP
 206 (AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0),
 207 .Li TKIP
 208 (Temporal Key Integrity Protocol, IEEE 802.11i/D7.0),
 209 .Li WEP104
 210 (WEP with 104-bit key),
 211 .Li WEP40
 212 (WEP with 40-bit key).
 213 If not set this defaults to
 214 .Qq Li "CCMP TKIP WEP104 WEP40" .
 215 .It Va psk
 216 WPA preshared key used in WPA-PSK mode.
 217 The key is specified as 64 hex digits or as
 218 an 8-63 character
 219 .Tn ASCII
 220 passphrase.
 221 .Tn ASCII
 222 passphrases are dynamically converted to a 256-bit key at runtime
 223 using the network SSID.
 224 .It Va eapol_flags
 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).
 229 .It Va eap
 230 List of acceptable EAP methods; one or more of:
 231 .Li MD5
 232 (EAP-MD5, cannot be used with WPA,
 233 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
 234 .Li MSCHAPV2
 235 (EAP-MSCHAPV2, cannot be used with WPA;
 236 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
 237 .Li OTP
 238 (EAP-OTP, cannot be used with WPA;
 239 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
 240 .Li GTC
 241 (EAP-GTC, cannot be used with WPA;
 242 used only as a Phase 2 method with EAP-PEAP or EAP-TTLS),
 243 .Li TLS
 244 (EAP-TLS, client and server certificate),
 245 .Li PEAP
 246 (EAP-PEAP, with tunneled EAP authentication),
 247 .Li TTLS
 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 .
 251 Note that by default
 252 .Xr wpa_supplicant 8
 253 is compiled with EAP support; see
 254 .Xr make.conf 5
 255 for the
 256 .Va NO_WPA_SUPPLICANT_EAPOL
 257 configuration variable that can be used to disable EAP support.
 258 .It Va identity
 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).
 263 .It Va mixed_cell
 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).
 267 .It Va password
 268 Password string for EAP.
 269 .It Va ca_cert
 270 Pathname to CA certificate file.
 271 This file can have one or more trusted CA certificates.
 272 If
 273 .Va ca_cert
 274 is not included, server certificates will not be verified (not recommended).
 275 .It Va client_cert
 276 Pathname to client certificate file (PEM/DER).
 277 .It Va private_key
 278 Pathname to a client private key file (PEM/DER/PFX).
 279 When a PKCS#12/PFX file is used, then
 280 .Va client_cert
 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.
 285 .It Va dh_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.
 293 If the
 294 .Va dh_file
 295 is in DSA parameters format, it will be automatically converted
 296 into DH params.
 297 .It Va subject_match
 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:
 303 .Pp
 304 .Dl "/C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@example.com"
 305 .It Va phase1
 306 Phase1 (outer authentication, i.e., TLS tunnel) parameters
 307 (string with field-value pairs, e.g.,
 308 .Qq Li peapver=0
 309 or
 310 .Qq Li "peapver=1 peaplabel=1" ) .
 311 .Bl -inset
 312 .It Li peapver
 313 can be used to force which PEAP version (0 or 1) is used.
 314 .It Li peaplabel=1
 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" ,
 320 and
 321 .Xr wpa_supplicant 8
 322 is now using that as the
 323 default value.
 324 Some servers, e.g.,
 325 .Tn Radiator ,
 326 may require
 327 .Li peaplabel=1
 328 configuration to interoperate with PEAPv1; see
 329 .Pa eap_testing.txt
 330 for more details.
 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
 335 implement
 336 .Pa draft-josefsson-pppext-eap-tls-eap-05.txt
 337 (e.g.,
 338 .Tn Lucent NavisRadius v4.4.0
 339 with PEAP in
 340 .Dq "IETF Draft 5"
 341 mode).
 342 .It Li include_tls_length=1
 343 can be used to force
 344 .Xr wpa_supplicant 8
 345 to include
 346 TLS Message Length field in all TLS messages even if they are not
 347 fragmented.
 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
 353 credentials (PAC).
 354 .El
 355 .It Va phase2
 356 phase2: Phase2 (inner authentication with TLS tunnel) parameters
 357 (string with field-value pairs, e.g.,
 358 .Qq Li "auth=MSCHAPV2"
 359 for EAP-PEAP or
 360 .Qq Li "autheap=MSCHAPV2 autheap=MD5"
 361 for EAP-TTLS).
 362 .It Va ca_cert2
 363 Like
 364 .Va ca_cert
 365 but for EAP inner Phase 2.
 366 .It Va client_cert2
 367 Like
 368 .Va client_cert
 369 but for EAP inner Phase 2.
 370 .It Va private_key2
 371 Like
 372 .Va private_key
 373 but for EAP inner Phase 2.
 374 .It Va private_key2_passwd
 375 Like
 376 .Va private_key_passwd
 377 but for EAP inner Phase 2.
 378 .It Va dh_file2
 379 Like
 380 .Va dh_file
 381 but for EAP inner Phase 2.
 382 .It Va subject_match2
 383 Like
 384 .Va subject_match
 385 but for EAP inner Phase 2.
 386 .It Va eappsk
 387 16-byte pre-shared key in hex format for use with EAP-PSK.
 388 .It Va nai
 389 User NAI for use with EAP-PSK.
 390 .It Va server_nai
 391 Authentication Server NAI for use with EAP-PSK.
 392 .It Va pac_file
 393 Pathname to the file to use for PAC entries with EAP-FAST.
 394 The
 395 .Xr wpa_supplicant 8
 396 utility
 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.
 404 .El
 405 .Sh CERTIFICATES
 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
 413 .Nm
 414 file as
 415 .Va private_key_passwd .
 416 .Pp
 417 The
 418 .Xr wpa_supplicant 8
 419 utility
 420 supports X.509 certificates in PEM and DER formats.
 421 User certificate and private key can be included in the same file.
 422 .Pp
 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
 425 use by
 426 .Xr wpa_supplicant 8 .
 427 This can be done using the
 428 .Xr openssl 1
 429 program, e.g.\& with the following commands:
 430 .Bd -literal
 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
 435 .Ed
 436 .Sh EXAMPLES
 437 WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS
 438 as a work network:
 439 .Bd -literal
 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
 443 #
 444 # home network; allow all valid ciphers
 445 network={
 446         ssid="home"
 447         scan_ssid=1
 448         key_mgmt=WPA-PSK
 449         psk="very secret passphrase"
 450 }
 451 #
 452 # work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
 453 network={
 454         ssid="work"
 455         scan_ssid=1
 456         key_mgmt=WPA-EAP
 457         pairwise=CCMP TKIP
 458         group=CCMP TKIP
 459         eap=TLS
 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"
 465 }
 466 .Ed
 467 .Pp
 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):
 470 .Bd -literal
 471 ctrl_interface=/var/run/wpa_supplicant
 472 ctrl_interface_group=wheel
 473 network={
 474         ssid="example"
 475         scan_ssid=1
 476         key_mgmt=WPA-EAP
 477         eap=PEAP
 478         identity="user@example.com"
 479         password="foobar"
 480         ca_cert="/etc/cert/ca.pem"
 481         phase1="peaplabel=0"
 482         phase2="auth=MSCHAPV2"
 483 }
 484 .Ed
 485 .Pp
 486 EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the
 487 unencrypted use.
 488 Real identity is sent only within an encrypted TLS tunnel.
 489 .Bd -literal
 490 ctrl_interface=/var/run/wpa_supplicant
 491 ctrl_interface_group=wheel
 492 network={
 493         ssid="example"
 494         scan_ssid=1
 495         key_mgmt=WPA-EAP
 496         eap=TTLS
 497         identity="user@example.com"
 498         anonymous_identity="anonymous@example.com"
 499         password="foobar"
 500         ca_cert="/etc/cert/ca.pem"
 501         phase2="auth=MD5"
 502 }
 503 .Ed
 504 .Pp
 505 Traditional WEP configuration with 104 bit key specified in hexadecimal.
 506 Note the WEP key is not quoted.
 507 .Bd -literal
 508 ctrl_interface=/var/run/wpa_supplicant
 509 ctrl_interface_group=wheel
 510 network={
 511         ssid="example"
 512         scan_ssid=1
 513         key_mgmt=NONE
 514         wep_tx_keyidx=0
 515         wep_key0=42FEEDDEAFBABEDEAFBEEFAA55
 516 }
 517 .Ed
 518 .Sh SEE ALSO
 519 .Xr wpa_cli 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 .