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 36The 37.Xr wpa_supplicant 8 38utility is an implementation of the WPA Supplicant component, 39i.e., the part that runs in the client stations. 40It implements WPA key negotiation with a WPA Authenticator 41and EAP authentication with Authentication Server using 42configuration information stored in a text file. 43.Pp 44The configuration file consists of optional global parameter 45settings and one or more network blocks, e.g.\& 46one for each used SSID. 47The 48.Xr wpa_supplicant 8 49utility 50will automatically select the best network based on the order of 51the network blocks in the configuration file, network security level 52(WPA/WPA2 is preferred), and signal strength. 53Comments are indicated with the 54.Ql # 55character; all text to the 56end of the line will be ignored. 57.Sh GLOBAL PARAMETERS 58Default parameters used by 59.Xr wpa_supplicant 8 60may be overridden by specifying 61.Pp 62.Dl parameter=value 63.Pp 64in the configuration file (note no spaces are allowed). 65Values with embedded spaces must be enclosed in quote marks. 66.Pp 67The following parameters are recognized: 68.Bl -tag -width indent 69.It Va ctrl_interface 70The pathname of the directory in which 71.Xr wpa_supplicant 8 72creates 73.Ux 74domain socket files for communication 75with frontend programs such as 76.Xr wpa_cli 8 . 77.It Va ctrl_interface_group 78A group name or group ID to use in setting protection on the 79control interface file. 80This can be set to allow non-root users to access the 81control interface files. 82If no group is specified, the group ID of the control interface 83is not modified and will, typically, be the 84group ID of the directory in which the socket is created. 85.It Va eapol_version 86The IEEE 802.1x/EAPOL protocol version to use; either 1 (default) or 2. 87The 88.Xr wpa_supplicant 8 89utility 90is implemented according to IEEE 802-1X-REV-d8 which defines 91EAPOL version to be 2. 92However, some access points do not work when presented with 93this version so by default 94.Xr wpa_supplicant 8 95will announce that it is using EAPOL version 1. 96If version 2 must be announced for correct operation with an 97access point, this value may be set to 2. 98.It Va ap_scan 99Access point scanning and selection control; one of 0, 1 (default), or 2. 100Only setting 1 should be used with the 101.Xr wlan 4 102module; the other settings are for use on other operating systems. 103.It Va fast_reauth 104EAP fast re-authentication; either 1 (default) or 0. 105Control fast re-authentication support in EAP methods that support it. 106.El 107.Sh NETWORK BLOCKS 108Each potential network/access point should have a 109.Dq "network block" 110that describes how to identify it and how to set up security. 111When multiple network blocks are listed in a configuration file, 112the highest priority one is selected for use or, if multiple networks 113with the same priority are identified, the first one listed in the 114configuration file is used. 115.Pp 116A network block description is of the form: 117.Bd -literal -offset indent 118network={ 119 parameter=value 120 ... 121} 122.Ed 123.Pp 124(note the leading 125.Qq Li "network={" 126may have no spaces). 127The block specification contains one or more parameters 128from the following list: 129.Bl -tag -width indent 130.It Va ssid No (required) 131Network name (as announced by the access point). 132An 133.Tn ASCII 134or hex string enclosed in quotation marks. 135.It Va scan_ssid 136SSID scan technique; 0 (default) or 1. 137Technique 0 scans for the SSID using a broadcast Probe Request 138frame while 1 uses a directed Probe Request frame. 139Access points that cloak themselves by not broadcasting their SSID 140require technique 1, but beware that this scheme can cause scanning 141to take longer to complete. 142.It Va bssid 143Network BSSID (typically the MAC address of the access point). 144.It Va priority 145The priority of a network when selecting among multiple networks; 146a higher value means a network is more desirable. 147By default networks have priority 0. 148When multiple networks with the same priority are considered 149for selection, other information such as security policy and 150signal strength are used to select one. 151.It Va mode 152IEEE 802.11 operation mode; either 0 (infrastructure, default) or 1 (IBSS). 153Note that IBSS (adhoc) mode can only be used with 154.Va key_mgmt 155set to 156.Li NONE 157(plaintext and static WEP). 158.It Va proto 159List of acceptable protocols; one or more of: 160.Li WPA 161(IEEE 802.11i/D3.0) 162and 163.Li RSN 164(IEEE 802.11i). 165.Li WPA2 166is another name for 167.Li RSN . 168If not set this defaults to 169.Qq Li "WPA RSN" . 170.It Va key_mgmt 171List 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, 178optionally, dynamically generated WEP keys), 179.Li NONE 180(plaintext or static WEP keys). 181If not set this defaults to 182.Qq Li "WPA-PSK WPA-EAP" . 183.It Va auth_alg 184List 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). 191If not set automatic selection is used (Open System with LEAP 192enabled if LEAP is allowed as one of the EAP methods). 193.It Va pairwise 194List 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). 201If not set this defaults to 202.Qq Li "CCMP TKIP" . 203.It Va group 204List 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). 213If not set this defaults to 214.Qq Li "CCMP TKIP WEP104 WEP40" . 215.It Va psk 216WPA preshared key used in WPA-PSK mode. 217The key is specified as 64 hex digits or as 218an 8-63 character 219.Tn ASCII 220passphrase. 221.Tn ASCII 222passphrases are dynamically converted to a 256-bit key at runtime 223using the network SSID. 224.It Va eapol_flags 225Dynamic WEP key usage for non-WPA mode, specified as a bit field. 226Bit 0 (1) forces dynamically generated unicast WEP keys to be used. 227Bit 1 (2) forces dynamically generated broadcast WEP keys to be used. 228By default this is set to 3 (use both). 229.It Va eap 230List of acceptable EAP methods; one or more of: 231.Li MD5 232(EAP-MD5, cannot be used with WPA, 233used only as a Phase 2 method with EAP-PEAP or EAP-TTLS), 234.Li MSCHAPV2 235(EAP-MSCHAPV2, cannot be used with WPA; 236used only as a Phase 2 method with EAP-PEAP or EAP-TTLS), 237.Li OTP 238(EAP-OTP, cannot be used with WPA; 239used only as a Phase 2 method with EAP-PEAP or EAP-TTLS), 240.Li GTC 241(EAP-GTC, cannot be used with WPA; 242used 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). 249If not set this defaults to all available methods compiled in to 250.Xr wpa_supplicant 8 . 251Note that by default 252.Xr wpa_supplicant 8 253is compiled with EAP support; see 254.Xr make.conf 5 255for the 256.Va NO_WPA_SUPPLICANT_EAPOL 257configuration variable that can be used to disable EAP support. 258.It Va identity 259Identity string for EAP. 260.It Va anonymous_identity 261Anonymous identity string for EAP (to be used as the unencrypted identity 262with EAP types that support different tunneled identities; e.g.\& EAP-TTLS). 263.It Va mixed_cell 264Configure whether networks that allow both plaintext and encryption 265are allowed when selecting a BSS from the scan results. 266By default this is set to 0 (disabled). 267.It Va password 268Password string for EAP. 269.It Va ca_cert 270Pathname to CA certificate file. 271This file can have one or more trusted CA certificates. 272If 273.Va ca_cert 274is not included, server certificates will not be verified (not recommended). 275.It Va client_cert 276Pathname to client certificate file (PEM/DER). 277.It Va private_key 278Pathname to a client private key file (PEM/DER/PFX). 279When a PKCS#12/PFX file is used, then 280.Va client_cert 281should not be specified as both the private key and certificate will be 282read from PKCS#12 file. 283.It Va private_key_passwd 284Password for any private key file. 285.It Va dh_file 286Pathname to a file holding DH/DSA parameters (in PEM format). 287This file holds parameters for an ephemeral DH key exchange. 288In most cases, the default RSA authentication does not use this configuration. 289However, it is possible to set up RSA to use an ephemeral DH key exchange. 290In addition, ciphers with 291DSA keys always use ephemeral DH keys. 292This can be used to achieve forward secrecy. 293If the 294.Va dh_file 295is in DSA parameters format, it will be automatically converted 296into DH params. 297.It Va subject_match 298Substring to be matched against the subject of the 299authentication server certificate. 300If this string is set, the server 301certificate is only accepted if it contains this string in the subject. 302The 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 306Phase1 (outer authentication, i.e., TLS tunnel) parameters 307(string with field-value pairs, e.g., 308.Qq Li peapver=0 309or 310.Qq Li "peapver=1 peaplabel=1" ) . 311.Bl -inset 312.It Li peapver 313can be used to force which PEAP version (0 or 1) is used. 314.It Li peaplabel=1 315can be used to force new label, 316.Dq "client PEAP encryption" , 317to be used during key derivation when PEAPv1 or newer. 318Most existing PEAPv1 implementations seem to be using the old label, 319.Dq Li "client EAP encryption" , 320and 321.Xr wpa_supplicant 8 322is now using that as the 323default value. 324Some servers, e.g., 325.Tn Radiator , 326may require 327.Li peaplabel=1 328configuration to interoperate with PEAPv1; see 329.Pa eap_testing.txt 330for more details. 331.It Li peap_outer_success=0 332can be used to terminate PEAP authentication on 333tunneled EAP-Success. 334This is required with some RADIUS servers that 335implement 336.Pa draft-josefsson-pppext-eap-tls-eap-05.txt 337(e.g., 338.Tn Lucent NavisRadius v4.4.0 339with PEAP in 340.Dq "IETF Draft 5" 341mode). 342.It Li include_tls_length=1 343can be used to force 344.Xr wpa_supplicant 8 345to include 346TLS Message Length field in all TLS messages even if they are not 347fragmented. 348.It Li sim_min_num_chal=3 349can be used to configure EAP-SIM to require three 350challenges (by default, it accepts 2 or 3) 351.It Li fast_provisioning=1 352option enables in-line provisioning of EAP-FAST 353credentials (PAC). 354.El 355.It Va phase2 356phase2: Phase2 (inner authentication with TLS tunnel) parameters 357(string with field-value pairs, e.g., 358.Qq Li "auth=MSCHAPV2" 359for EAP-PEAP or 360.Qq Li "autheap=MSCHAPV2 autheap=MD5" 361for EAP-TTLS). 362.It Va ca_cert2 363Like 364.Va ca_cert 365but for EAP inner Phase 2. 366.It Va client_cert2 367Like 368.Va client_cert 369but for EAP inner Phase 2. 370.It Va private_key2 371Like 372.Va private_key 373but for EAP inner Phase 2. 374.It Va private_key2_passwd 375Like 376.Va private_key_passwd 377but for EAP inner Phase 2. 378.It Va dh_file2 379Like 380.Va dh_file 381but for EAP inner Phase 2. 382.It Va subject_match2 383Like 384.Va subject_match 385but for EAP inner Phase 2. 386.It Va eappsk 38716-byte pre-shared key in hex format for use with EAP-PSK. 388.It Va nai 389User NAI for use with EAP-PSK. 390.It Va server_nai 391Authentication Server NAI for use with EAP-PSK. 392.It Va pac_file 393Pathname to the file to use for PAC entries with EAP-FAST. 394The 395.Xr wpa_supplicant 8 396utility 397must be able to create this file and write updates to it when 398PAC is being provisioned or refreshed. 399.It Va eap_workaround 400Enable/disable EAP workarounds for various interoperability issues 401with misbehaving authentication servers. 402By default these workarounds are enabled. 403String EAP conformance can be configured by setting this to 0. 404.El 405.Sh CERTIFICATES 406Some EAP authentication methods require use of certificates. 407EAP-TLS uses both server- and client-side certificates, 408whereas EAP-PEAP and EAP-TTLS only require a server-side certificate. 409When a client certificate is used, a matching private key file must 410also be included in configuration. 411If the private key uses a passphrase, this 412has to be configured in the 413.Nm 414file as 415.Va private_key_passwd . 416.Pp 417The 418.Xr wpa_supplicant 8 419utility 420supports X.509 certificates in PEM and DER formats. 421User certificate and private key can be included in the same file. 422.Pp 423If the user certificate and private key is received in PKCS#12/PFX 424format, they need to be converted to a suitable PEM/DER format for 425use by 426.Xr wpa_supplicant 8 . 427This can be done using the 428.Xr openssl 1 429program, e.g.\& with the following commands: 430.Bd -literal 431# convert client certificate and private key to PEM format 432openssl pkcs12 -in example.pfx -out user.pem -clcerts 433# convert CA certificate (if included in PFX file) to PEM format 434openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys 435.Ed 436.Sh EXAMPLES 437WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS 438as a work network: 439.Bd -literal 440# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group 441ctrl_interface=/var/run/wpa_supplicant 442ctrl_interface_group=wheel 443# 444# home network; allow all valid ciphers 445network={ 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 453network={ 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 468WPA-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 471ctrl_interface=/var/run/wpa_supplicant 472ctrl_interface_group=wheel 473network={ 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 486EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the 487unencrypted use. 488Real identity is sent only within an encrypted TLS tunnel. 489.Bd -literal 490ctrl_interface=/var/run/wpa_supplicant 491ctrl_interface_group=wheel 492network={ 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 505Traditional WEP configuration with 104 bit key specified in hexadecimal. 506Note the WEP key is not quoted. 507.Bd -literal 508ctrl_interface=/var/run/wpa_supplicant 509ctrl_interface_group=wheel 510network={ 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 522The 523.Nm 524manual page and 525.Xr wpa_supplicant 8 526functionality first appeared in 527.Fx 6.0 . 528.Sh AUTHORS 529This manual page is derived from the 530.Pa README 531and 532.Pa wpa_supplicant.conf 533files in the 534.Nm wpa_supplicant 535distribution provided by 536.An Jouni Malinen Aq jkmaline@cc.hut.fi . 537