1.\" $NetBSD: wpa_supplicant.conf.5,v 1.4 2014/03/18 18:20:36 riastradh Exp $ 2.\" 3.\" Copyright (c) 2005 Sam Leffler <sam@errno.com> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" Based on: 28.\" $FreeBSD: src/usr.sbin/wpa/wpa_supplicant/wpa_supplicant.conf.5,v 1.9 2007/07/11 16:04:08 sam Exp $ 29.\" 30.Dd December 22, 2007 31.Dt WPA_SUPPLICANT.CONF 5 32.Os 33.Sh NAME 34.Nm wpa_supplicant.conf 35.Nd configuration file for 36.Xr wpa_supplicant 8 37.Sh DESCRIPTION 38The 39.Xr wpa_supplicant 8 40utility is an implementation of the WPA Supplicant component, 41i.e., the part that runs in the client stations. 42It implements WPA key negotiation with a WPA Authenticator 43and EAP authentication with Authentication Server using 44configuration information stored in a text file. 45.Pp 46The configuration file consists of optional global parameter 47settings and one or more network blocks, e.g.\& 48one for each used SSID. 49The 50.Xr wpa_supplicant 8 51utility 52will automatically select the best network based on the order of 53the network blocks in the configuration file, network security level 54(WPA/WPA2 is preferred), and signal strength. 55Comments are indicated with the 56.Ql # 57character; all text to the 58end of the line will be ignored. 59.Sh GLOBAL PARAMETERS 60Default parameters used by 61.Xr wpa_supplicant 8 62may be overridden by specifying 63.Pp 64.Dl parameter=value 65.Pp 66in the configuration file (note no spaces are allowed). 67Values with embedded spaces must be enclosed in quote marks. 68.Pp 69The following parameters are recognized: 70.Bl -tag -width indent 71.It Va ctrl_interface 72The pathname of the directory in which 73.Xr wpa_supplicant 8 74creates 75.Ux 76domain socket files for communication 77with frontend programs such as 78.Xr wpa_cli 8 . 79.It Va ctrl_interface_group 80A group name or group ID to use in setting protection on the 81control interface file. 82This can be set to allow non-root users to access the 83control interface files. 84If no group is specified, the group ID of the control interface 85is not modified and will, typically, be the 86group ID of the directory in which the socket is created. 87.It Va eapol_version 88The IEEE 802.1x/EAPOL protocol version to use; either 1 (default) or 2. 89The 90.Xr wpa_supplicant 8 91utility 92is implemented according to IEEE 802-1X-REV-d8 which defines 93EAPOL version to be 2. 94However, some access points do not work when presented with 95this version so by default 96.Xr wpa_supplicant 8 97will announce that it is using EAPOL version 1. 98If version 2 must be announced for correct operation with an 99access point, this value may be set to 2. 100.It Va ap_scan 101Access point scanning and selection control; one of 0, 1 (default), or 2. 102.\" XXX: which one is good for NetBSD? 103.\"Only setting 1 should be used with the 104.\".Xr wlan 4 105.\"module; the other settings are for use on other operating systems. 106.It Va fast_reauth 107EAP fast re-authentication; either 1 (default) or 0. 108Control fast re-authentication support in EAP methods that support it. 109.El 110.Sh NETWORK BLOCKS 111Each potential network/access point should have a 112.Dq "network block" 113that describes how to identify it and how to set up security. 114When multiple network blocks are listed in a configuration file, 115the highest priority one is selected for use or, if multiple networks 116with the same priority are identified, the first one listed in the 117configuration file is used. 118.Pp 119A network block description is of the form: 120.Bd -literal -offset indent 121network={ 122 parameter=value 123 ... 124} 125.Ed 126.Pp 127(note the leading 128.Qq Li "network={" 129may have no spaces). 130The block specification contains one or more parameters 131from the following list: 132.Bl -tag -width indent 133.It Va ssid No (required) 134Network name (as announced by the access point). 135An 136.Tn ASCII 137or hex string enclosed in quotation marks. 138.It Va scan_ssid 139SSID scan technique; 0 (default) or 1. 140Technique 0 scans for the SSID using a broadcast Probe Request 141frame while 1 uses a directed Probe Request frame. 142Access points that cloak themselves by not broadcasting their SSID 143require technique 1, but beware that this scheme can cause scanning 144to take longer to complete. 145.It Va bssid 146Network BSSID (typically the MAC address of the access point). 147.It Va priority 148The priority of a network when selecting among multiple networks; 149a higher value means a network is more desirable. 150By default networks have priority 0. 151When multiple networks with the same priority are considered 152for selection, other information such as security policy and 153signal strength are used to select one. 154.It Va mode 155IEEE 802.11 operation mode; either 0 (infrastructure, default) or 1 (IBSS). 156Note that IBSS (adhoc) mode can only be used with 157.Va key_mgmt 158set to 159.Li NONE 160(plaintext and static WEP). 161.It Va proto 162List of acceptable protocols; one or more of: 163.Li WPA 164(IEEE 802.11i/D3.0) 165and 166.Li RSN 167(IEEE 802.11i). 168.Li WPA2 169is another name for 170.Li RSN . 171If not set this defaults to 172.Qq Li "WPA RSN" . 173.It Va key_mgmt 174List of acceptable key management protocols; one or more of: 175.Li WPA-PSK 176(WPA pre-shared key), 177.Li WPA-EAP 178(WPA using EAP authentication), 179.Li IEEE8021X 180(IEEE 802.1x using EAP authentication and, 181optionally, dynamically generated WEP keys), 182.Li NONE 183(plaintext or static WEP keys). 184If not set this defaults to 185.Qq Li "WPA-PSK WPA-EAP" . 186.It Va auth_alg 187List of allowed IEEE 802.11 authentication algorithms; one or more of: 188.Li OPEN 189(Open System authentication, required for WPA/WPA2), 190.Li SHARED 191(Shared Key authentication), 192.Li LEAP 193(LEAP/Network EAP). 194If not set automatic selection is used (Open System with LEAP 195enabled if LEAP is allowed as one of the EAP methods). 196.It Va pairwise 197List of acceptable pairwise (unicast) ciphers for WPA; one or more of: 198.Li CCMP 199(AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0), 200.Li TKIP 201(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0), 202.Li NONE 203(deprecated). 204If not set this defaults to 205.Qq Li "CCMP TKIP" . 206.It Va group 207List of acceptable group (multicast) ciphers for WPA; one or more of: 208.Li CCMP 209(AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0), 210.Li TKIP 211(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0), 212.Li WEP104 213(WEP with 104-bit key), 214.Li WEP40 215(WEP with 40-bit key). 216If not set this defaults to 217.Qq Li "CCMP TKIP WEP104 WEP40" . 218.It Va psk 219WPA preshared key used in WPA-PSK mode. 220The key is specified as 64 hex digits or as 221an 8-63 character 222.Tn ASCII 223passphrase. 224.Tn ASCII 225passphrases are converted to a 256-bit key using the network SSID 226by the 227.Xr wpa_passphrase 8 228utility. 229.It Va eapol_flags 230Dynamic WEP key usage for non-WPA mode, specified as a bit field. 231Bit 0 (1) forces dynamically generated unicast WEP keys to be used. 232Bit 1 (2) forces dynamically generated broadcast WEP keys to be used. 233By default this is set to 3 (use both). 234.It Va eap 235List of acceptable EAP methods; one or more of: 236.Li MD5 237(EAP-MD5, cannot be used with WPA, 238used only as a Phase 2 method with EAP-PEAP or EAP-TTLS), 239.Li MSCHAPV2 240(EAP-MSCHAPV2, cannot be used with WPA; 241used only as a Phase 2 method with EAP-PEAP or EAP-TTLS), 242.Li OTP 243(EAP-OTP, cannot be used with WPA; 244used only as a Phase 2 method with EAP-PEAP or EAP-TTLS), 245.Li GTC 246(EAP-GTC, cannot be used with WPA; 247used only as a Phase 2 method with EAP-PEAP or EAP-TTLS), 248.Li TLS 249(EAP-TLS, client and server certificate), 250.Li PEAP 251(EAP-PEAP, with tunneled EAP authentication), 252.Li TTLS 253(EAP-TTLS, with tunneled EAP or PAP/CHAP/MSCHAP/MSCHAPV2 authentication). 254If not set this defaults to all available methods compiled in to 255.Xr wpa_supplicant 8 . 256Note that by default 257.Xr wpa_supplicant 8 258is compiled with EAP support. 259.\"; see 260.\".Xr make.conf 5 261.\"for the 262.\".Va NO_ENABLE_WPA_SUPPLICANT_EAPOL 263.\"configuration variable that can be used to disable EAP support. 264.It Va identity 265Identity string for EAP. 266.It Va anonymous_identity 267Anonymous identity string for EAP (to be used as the unencrypted identity 268with EAP types that support different tunneled identities; e.g.\& EAP-TTLS). 269.It Va password 270Password string for EAP. 271.It Va ca_cert 272Pathname to CA certificate file. 273This file can have one or more trusted CA certificates. 274If 275.Va ca_cert 276is not included, server certificates will not be verified (not recommended). 277.It Va client_cert 278Pathname to client certificate file (PEM/DER). 279.It Va private_key 280Pathname to a client private key file (PEM/DER/PFX). 281When a PKCS#12/PFX file is used, then 282.Va client_cert 283should not be specified as both the private key and certificate will be 284read from PKCS#12 file. 285.It Va private_key_passwd 286Password for any private key file. 287.It Va dh_file 288Pathname to a file holding DH/DSA parameters (in PEM format). 289This file holds parameters for an ephemeral DH key exchange. 290In most cases, the default RSA authentication does not use this configuration. 291However, it is possible to set up RSA to use an ephemeral DH key exchange. 292In addition, ciphers with 293DSA keys always use ephemeral DH keys. 294This can be used to achieve forward secrecy. 295If the 296.Va dh_file 297is in DSA parameters format, it will be automatically converted 298into DH params. 299.It Va subject_match 300Substring to be matched against the subject of the 301authentication server certificate. 302If this string is set, the server 303certificate is only accepted if it contains this string in the subject. 304The subject string is in following format: 305.Pp 306.Dl "/C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@example.com" 307.It Va phase1 308Phase1 (outer authentication, i.e., TLS tunnel) parameters 309(string with field-value pairs, e.g., 310.Qq Li peapver=0 311or 312.Qq Li "peapver=1 peaplabel=1" ) . 313.Bl -inset 314.It Li peapver 315can be used to force which PEAP version (0 or 1) is used. 316.It Li peaplabel=1 317can be used to force new label, 318.Dq "client PEAP encryption" , 319to be used during key derivation when PEAPv1 or newer. 320Most existing PEAPv1 implementations seem to be using the old label, 321.Dq Li "client EAP encryption" , 322and 323.Xr wpa_supplicant 8 324is now using that as the 325default value. 326Some servers, e.g., 327.Tn Radiator , 328may require 329.Li peaplabel=1 330configuration to interoperate with PEAPv1; see 331.Pa eap_testing.txt 332for more details. 333.It Li peap_outer_success=0 334can be used to terminate PEAP authentication on 335tunneled EAP-Success. 336This is required with some RADIUS servers that 337implement 338.Pa draft-josefsson-pppext-eap-tls-eap-05.txt 339(e.g., 340.Tn Lucent NavisRadius v4.4.0 341with PEAP in 342.Dq "IETF Draft 5" 343mode). 344.It Li include_tls_length=1 345can be used to force 346.Xr wpa_supplicant 8 347to include 348TLS Message Length field in all TLS messages even if they are not 349fragmented. 350.It Li sim_min_num_chal=3 351can be used to configure EAP-SIM to require three 352challenges (by default, it accepts 2 or 3) 353.It Li fast_provisioning=1 354option enables in-line provisioning of EAP-FAST 355credentials (PAC). 356.El 357.It Va phase2 358phase2: Phase2 (inner authentication with TLS tunnel) parameters 359(string with field-value pairs, e.g., 360.Qq Li "auth=MSCHAPV2" 361for EAP-PEAP or 362.Qq Li "autheap=MSCHAPV2 autheap=MD5" 363for EAP-TTLS). 364.It Va ca_cert2 365Like 366.Va ca_cert 367but for EAP inner Phase 2. 368.It Va client_cert2 369Like 370.Va client_cert 371but for EAP inner Phase 2. 372.It Va private_key2 373Like 374.Va private_key 375but for EAP inner Phase 2. 376.It Va private_key2_passwd 377Like 378.Va private_key_passwd 379but for EAP inner Phase 2. 380.It Va dh_file2 381Like 382.Va dh_file 383but for EAP inner Phase 2. 384.It Va subject_match2 385Like 386.Va subject_match 387but for EAP inner Phase 2. 388.It Va eappsk 38916-byte pre-shared key in hex format for use with EAP-PSK. 390.It Va nai 391User NAI for use with EAP-PSK. 392.It Va server_nai 393Authentication Server NAI for use with EAP-PSK. 394.It Va pac_file 395Pathname to the file to use for PAC entries with EAP-FAST. 396The 397.Xr wpa_supplicant 8 398utility 399must be able to create this file and write updates to it when 400PAC is being provisioned or refreshed. 401.It Va eap_workaround 402Enable/disable EAP workarounds for various interoperability issues 403with misbehaving authentication servers. 404By default these workarounds are enabled. 405String EAP conformance can be configured by setting this to 0. 406.El 407.Sh CERTIFICATES 408Some EAP authentication methods require use of certificates. 409EAP-TLS uses both server- and client-side certificates, 410whereas EAP-PEAP and EAP-TTLS only require a server-side certificate. 411When a client certificate is used, a matching private key file must 412also be included in configuration. 413If the private key uses a passphrase, this 414has to be configured in the 415.Nm 416file as 417.Va private_key_passwd . 418.Pp 419The 420.Xr wpa_supplicant 8 421utility 422supports X.509 certificates in PEM and DER formats. 423User certificate and private key can be included in the same file. 424.Pp 425If the user certificate and private key is received in PKCS#12/PFX 426format, they need to be converted to a suitable PEM/DER format for 427use by 428.Xr wpa_supplicant 8 . 429This can be done using the 430.Xr openssl 1 431program, e.g.\& with the following commands: 432.Bd -literal 433# convert client certificate and private key to PEM format 434openssl pkcs12 -in example.pfx -out user.pem -clcerts 435# convert CA certificate (if included in PFX file) to PEM format 436openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys 437.Ed 438.Sh EXAMPLES 439WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS 440as a work network: 441.Bd -literal 442# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group 443ctrl_interface=/var/run/wpa_supplicant 444ctrl_interface_group=wheel 445# 446# home network; allow all valid ciphers 447network={ 448 ssid="home" 449 scan_ssid=1 450 key_mgmt=WPA-PSK 451 psk="very secret passphrase" 452} 453# 454# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers 455network={ 456 ssid="work" 457 scan_ssid=1 458 key_mgmt=WPA-EAP 459 pairwise=CCMP TKIP 460 group=CCMP TKIP 461 eap=TLS 462 identity="user@example.com" 463 ca_cert="/etc/cert/ca.pem" 464 client_cert="/etc/cert/user.pem" 465 private_key="/etc/cert/user.prv" 466 private_key_passwd="password" 467} 468.Ed 469.Pp 470WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel 471(e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series): 472.Bd -literal 473ctrl_interface=/var/run/wpa_supplicant 474ctrl_interface_group=wheel 475network={ 476 ssid="example" 477 scan_ssid=1 478 key_mgmt=WPA-EAP 479 eap=PEAP 480 identity="user@example.com" 481 password="foobar" 482 ca_cert="/etc/cert/ca.pem" 483 phase1="peaplabel=0" 484 phase2="auth=MSCHAPV2" 485} 486.Ed 487.Pp 488EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the 489unencrypted use. 490Real identity is sent only within an encrypted TLS tunnel. 491.Bd -literal 492ctrl_interface=/var/run/wpa_supplicant 493ctrl_interface_group=wheel 494network={ 495 ssid="example" 496 scan_ssid=1 497 key_mgmt=WPA-EAP 498 eap=TTLS 499 identity="user@example.com" 500 anonymous_identity="anonymous@example.com" 501 password="foobar" 502 ca_cert="/etc/cert/ca.pem" 503 phase2="auth=MD5" 504} 505.Ed 506.Pp 507Traditional WEP configuration with 104 bit key specified in hexadecimal. 508Note the WEP key is not quoted. 509.Bd -literal 510ctrl_interface=/var/run/wpa_supplicant 511ctrl_interface_group=wheel 512network={ 513 ssid="example" 514 scan_ssid=1 515 key_mgmt=NONE 516 wep_tx_keyidx=0 517 wep_key0=42FEEDDEAFBABEDEAFBEEFAA55 518} 519.Ed 520.Sh SEE ALSO 521.Xr wpa_cli 8 , 522.Xr wpa_passphrase 8 , 523.Xr wpa_supplicant 8 524.Sh HISTORY 525The 526.Nm 527manual page and 528.Xr wpa_supplicant 8 529functionality first appeared in 530.Nx 4.0 . 531.Sh AUTHORS 532This manual page is derived from the 533.Pa README 534and 535.Pa wpa_supplicant.conf 536files in the 537.Nm wpa_supplicant 538distribution provided by 539.An Jouni Malinen Aq Mt jkmaline@cc.hut.fi . 540