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