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