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