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 March 16, 2022 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 frame. 137Technique 1 uses directed Probe Request frames, sent to each configured SSID. 138Access points that cloak themselves by not broadcasting their SSID require 139technique 1. 140Beware that this technique can cause scanning to take longer to complete, 141and exposes the list of configured network SSIDs to eavesdroppers. 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), or 158.Va key_mgmt 159set to 160.Li WPA-NONE 161(fixed group key TKIP/CCMP). 162In addition, 163.Va ap_scan 164has to be set to 2 for IBSS. 165.Li WPA-NONE 166requires 167.Va proto 168set to WPA, 169.Va key_mgmt 170set to WPA-NONE, 171.Va pairwise 172set to NONE, 173.Va group 174set to either 175CCMP or TKIP (but not both), and 176.Va psk 177must also be set. 178.It Va proto 179List of acceptable protocols; one or more of: 180.Li WPA 181(IEEE 802.11i/D3.0) 182and 183.Li RSN 184(IEEE 802.11i). 185.Li WPA2 186is another name for 187.Li RSN . 188If not set this defaults to 189.Qq Li "WPA RSN" . 190.It Va key_mgmt 191List of acceptable key management protocols; one or more of: 192.Li WPA-PSK 193(WPA pre-shared key), 194.Li WPA-EAP 195(WPA using EAP authentication), 196.Li IEEE8021X 197(IEEE 802.1x using EAP authentication and, 198optionally, dynamically generated WEP keys), 199.Li NONE 200(plaintext or static WEP keys). 201If not set this defaults to 202.Qq Li "WPA-PSK WPA-EAP" . 203.It Va auth_alg 204List of allowed IEEE 802.11 authentication algorithms; one or more of: 205.Li OPEN 206(Open System authentication, required for WPA/WPA2), 207.Li SHARED 208(Shared Key authentication), 209.Li LEAP 210(LEAP/Network EAP). 211If not set automatic selection is used (Open System with LEAP 212enabled if LEAP is allowed as one of the EAP methods). 213.It Va pairwise 214List of acceptable pairwise (unicast) ciphers for WPA; one or more of: 215.Li CCMP 216(AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0), 217.Li TKIP 218(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0), 219.Li NONE 220(deprecated). 221If not set this defaults to 222.Qq Li "CCMP TKIP" . 223.It Va group 224List of acceptable group (multicast) ciphers for WPA; one or more of: 225.Li CCMP 226(AES in Counter mode with CBC-MAC, RFC 3610, IEEE 802.11i/D7.0), 227.Li TKIP 228(Temporal Key Integrity Protocol, IEEE 802.11i/D7.0), 229.Li WEP104 230(WEP with 104-bit key), 231.Li WEP40 232(WEP with 40-bit key). 233If not set this defaults to 234.Qq Li "CCMP TKIP WEP104 WEP40" . 235.It Va psk 236WPA preshared key used in WPA-PSK mode. 237The key is specified as 64 hex digits or as 238an 8-63 character 239.Tn ASCII 240passphrase. 241.Tn ASCII 242passphrases are dynamically converted to a 256-bit key at runtime 243using the network SSID, or they can be statically converted at 244configuration time using 245the 246.Xr wpa_passphrase 8 247utility. 248.It Va eapol_flags 249Dynamic WEP key usage for non-WPA mode, specified as a bit field. 250Bit 0 (1) forces dynamically generated unicast WEP keys to be used. 251Bit 1 (2) forces dynamically generated broadcast WEP keys to be used. 252By default this is set to 3 (use both). 253.It Va eap 254List of acceptable EAP methods; one or more of: 255.Li MD5 256(EAP-MD5, cannot be used with WPA, 257used only as a Phase 2 method with EAP-PEAP or EAP-TTLS), 258.Li MSCHAPV2 259(EAP-MSCHAPV2, cannot be used with WPA; 260used only as a Phase 2 method with EAP-PEAP or EAP-TTLS), 261.Li OTP 262(EAP-OTP, cannot be used with WPA; 263used only as a Phase 2 metod with EAP-PEAP or EAP-TTLS), 264.Li GTC 265(EAP-GTC, cannot be used with WPA; 266used only as a Phase 2 metod with EAP-PEAP or EAP-TTLS), 267.Li TLS 268(EAP-TLS, client and server certificate), 269.Li PEAP 270(EAP-PEAP, with tunneled EAP authentication), 271.Li TTLS 272(EAP-TTLS, with tunneled EAP or PAP/CHAP/MSCHAP/MSCHAPV2 authentication). 273If not set this defaults to all available methods compiled in to 274.Xr wpa_supplicant 8 . 275Note that by default 276.Xr wpa_supplicant 8 277is compiled with EAP support; see 278.Xr make.conf 5 279for the 280.Va NO_WPA_SUPPLICANT_EAPOL 281configuration variable that can be used to disable EAP support. 282.It Va identity 283Identity string for EAP. 284.It Va anonymous_identity 285Anonymous identity string for EAP (to be used as the unencrypted identity 286with EAP types that support different tunneled identities; e.g.\& EAP-TTLS). 287.It Va mixed_cell 288Configure whether networks that allow both plaintext and encryption 289are allowed when selecting a BSS from the scan results. 290By default this is set to 0 (disabled). 291.It Va password 292Password string for EAP. 293.It Va ca_cert 294Pathname to CA certificate file. 295This file can have one or more trusted CA certificates. 296If 297.Va ca_cert 298is not included, server certificates will not be verified (not recommended). 299.It Va client_cert 300Pathname to client certificate file (PEM/DER). 301.It Va private_key 302Pathname to a client private key file (PEM/DER/PFX). 303When a PKCS#12/PFX file is used, then 304.Va client_cert 305should not be specified as both the private key and certificate will be 306read from PKCS#12 file. 307.It Va private_key_passwd 308Password for any private key file. 309.It Va dh_file 310Pathname to a file holding DH/DSA parameters (in PEM format). 311This file holds parameters for an ephemeral DH key exchange. 312In most cases, the default RSA authentication does not use this configuration. 313However, it is possible to set up RSA to use an ephemeral DH key exchange. 314In addition, ciphers with 315DSA keys always use ephemeral DH keys. 316This can be used to achieve forward secrecy. 317If the 318.Va dh_file 319is in DSA parameters format, it will be automatically converted 320into DH parameters. 321.It Va subject_match 322Substring to be matched against the subject of the 323authentication server certificate. 324If this string is set, the server 325certificate is only accepted if it contains this string in the subject. 326The subject string is in following format: 327.Pp 328.Dl "/C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@example.com" 329.It Va phase1 330Phase1 (outer authentication, i.e., TLS tunnel) parameters 331(string with field-value pairs, e.g., 332.Qq Li peapver=0 333or 334.Qq Li "peapver=1 peaplabel=1" ) . 335.Bl -inset 336.It Li peapver 337can be used to force which PEAP version (0 or 1) is used. 338.It Li peaplabel=1 339can be used to force new label, 340.Dq "client PEAP encryption" , 341to be used during key derivation when PEAPv1 or newer. 342Most existing PEAPv1 implementations seem to be using the old label, 343.Dq Li "client EAP encryption" , 344and 345.Xr wpa_supplicant 8 346is now using that as the 347default value. 348Some servers, e.g., 349.Tn Radiator , 350may require 351.Li peaplabel=1 352configuration to interoperate with PEAPv1; see 353.Pa eap_testing.txt 354for more details. 355.It Li peap_outer_success=0 356can be used to terminate PEAP authentication on 357tunneled EAP-Success. 358This is required with some RADIUS servers that 359implement 360.Pa draft-josefsson-pppext-eap-tls-eap-05.txt 361(e.g., 362.Tn Lucent NavisRadius v4.4.0 363with PEAP in 364.Dq "IETF Draft 5" 365mode). 366.It Li include_tls_length=1 367can be used to force 368.Xr wpa_supplicant 8 369to include 370TLS Message Length field in all TLS messages even if they are not 371fragmented. 372.It Li sim_min_num_chal=3 373can be used to configure EAP-SIM to require three 374challenges (by default, it accepts 2 or 3). 375.It Li fast_provisioning=1 376option enables in-line provisioning of EAP-FAST 377credentials (PAC). 378.El 379.It Va phase2 380phase2: Phase2 (inner authentication with TLS tunnel) parameters 381(string with field-value pairs, e.g., 382.Qq Li "auth=MSCHAPV2" 383for EAP-PEAP or 384.Qq Li "autheap=MSCHAPV2 autheap=MD5" 385for EAP-TTLS). 386.It Va ca_cert2 387Like 388.Va ca_cert 389but for EAP inner Phase 2. 390.It Va client_cert2 391Like 392.Va client_cert 393but for EAP inner Phase 2. 394.It Va private_key2 395Like 396.Va private_key 397but for EAP inner Phase 2. 398.It Va private_key2_passwd 399Like 400.Va private_key_passwd 401but for EAP inner Phase 2. 402.It Va dh_file2 403Like 404.Va dh_file 405but for EAP inner Phase 2. 406.It Va subject_match2 407Like 408.Va subject_match 409but for EAP inner Phase 2. 410.It Va eappsk 41116-byte pre-shared key in hex format for use with EAP-PSK. 412.It Va nai 413User NAI for use with EAP-PSK. 414.It Va server_nai 415Authentication Server NAI for use with EAP-PSK. 416.It Va pac_file 417Pathname to the file to use for PAC entries with EAP-FAST. 418The 419.Xr wpa_supplicant 8 420utility 421must be able to create this file and write updates to it when 422PAC is being provisioned or refreshed. 423.It Va eap_workaround 424Enable/disable EAP workarounds for various interoperability issues 425with misbehaving authentication servers. 426By default these workarounds are enabled. 427Strict EAP conformance can be configured by setting this to 0. 428.It Va wep_tx_keyidx 429which key to use for transmission of packets. 430.It Va wep_keyN key 431An 432.Tn ASCII 433string enclosed in quotation marks to encode the WEP key. 434Without quotes this is a hex string of the actual key. 435WEP is considered insecure and should be avoided. 436The exact translation from an ASCII key to a hex key varies. 437Use hex keys where possible. 438.El 439.Sh CERTIFICATES 440Some EAP authentication methods require use of certificates. 441EAP-TLS uses both server- and client-side certificates, 442whereas EAP-PEAP and EAP-TTLS only require a server-side certificate. 443When a client certificate is used, a matching private key file must 444also be included in configuration. 445If the private key uses a passphrase, this 446has to be configured in the 447.Nm 448file as 449.Va private_key_passwd . 450.Pp 451The 452.Xr wpa_supplicant 8 453utility 454supports X.509 certificates in PEM and DER formats. 455User certificate and private key can be included in the same file. 456.Pp 457If the user certificate and private key is received in PKCS#12/PFX 458format, they need to be converted to a suitable PEM/DER format for 459use by 460.Xr wpa_supplicant 8 . 461This can be done using the 462.Xr openssl 1 463program, e.g.\& with the following commands: 464.Bd -literal 465# convert client certificate and private key to PEM format 466openssl pkcs12 -in example.pfx -out user.pem -clcerts 467# convert CA certificate (if included in PFX file) to PEM format 468openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys 469.Ed 470.Sh FILES 471.Bl -tag -width ".Pa /usr/share/examples/etc/wpa_supplicant.conf" -compact 472.It Pa /etc/wpa_supplicant.conf 473.It Pa /usr/share/examples/etc/wpa_supplicant.conf 474.El 475.Sh EXAMPLES 476WPA-Personal (PSK) as a home network and WPA-Enterprise with EAP-TLS 477as a work network: 478.Bd -literal 479# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group 480ctrl_interface=/var/run/wpa_supplicant 481ctrl_interface_group=wheel 482# 483# home network; allow all valid ciphers 484network={ 485 ssid="home" 486 scan_ssid=1 487 key_mgmt=WPA-PSK 488 psk="very secret passphrase" 489} 490# 491# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers 492network={ 493 ssid="work" 494 scan_ssid=1 495 key_mgmt=WPA-EAP 496 pairwise=CCMP TKIP 497 group=CCMP TKIP 498 eap=TLS 499 identity="user@example.com" 500 ca_cert="/etc/cert/ca.pem" 501 client_cert="/etc/cert/user.pem" 502 private_key="/etc/cert/user.prv" 503 private_key_passwd="password" 504} 505.Ed 506.Pp 507WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that use old peaplabel 508(e.g., Funk Odyssey and SBR, Meetinghouse Aegis, Interlink RAD-Series): 509.Bd -literal 510ctrl_interface=/var/run/wpa_supplicant 511ctrl_interface_group=wheel 512network={ 513 ssid="example" 514 scan_ssid=1 515 key_mgmt=WPA-EAP 516 eap=PEAP 517 identity="user@example.com" 518 password="foobar" 519 ca_cert="/etc/cert/ca.pem" 520 phase1="peaplabel=0" 521 phase2="auth=MSCHAPV2" 522} 523.Ed 524.Pp 525EAP-TTLS/EAP-MD5-Challenge configuration with anonymous identity for the 526unencrypted use. 527Real identity is sent only within an encrypted TLS tunnel. 528.Bd -literal 529ctrl_interface=/var/run/wpa_supplicant 530ctrl_interface_group=wheel 531network={ 532 ssid="example" 533 scan_ssid=1 534 key_mgmt=WPA-EAP 535 eap=TTLS 536 identity="user@example.com" 537 anonymous_identity="anonymous@example.com" 538 password="foobar" 539 ca_cert="/etc/cert/ca.pem" 540 phase2="auth=MD5" 541} 542.Ed 543.Pp 544Traditional WEP configuration with 104 bit key specified in hexadecimal. 545Note the WEP key is not quoted. 546.Bd -literal 547ctrl_interface=/var/run/wpa_supplicant 548ctrl_interface_group=wheel 549network={ 550 ssid="example" 551 scan_ssid=1 552 key_mgmt=NONE 553 wep_tx_keyidx=0 554 # hex keys denoted without quotes 555 wep_key0=42FEEDDEAFBABEDEAFBEEFAA55 556 # ASCII keys denoted with quotes. 557 wep_key1="FreeBSDr0cks!" 558} 559.Ed 560.Pp 561Minimal eduroam configuration. 562.Bd -literal 563ctrl_interface=/var/run/wpa_supplicant 564ctrl_interface_group=wheel 565network={ 566 ssid="eduroam" 567 scan_ssid=1 568 key_mgmt=WPA-EAP 569 eap=TTLS 570 identity="user@example.org" 571 password="foobar" 572 phase2="auth=MSCHAPV2" 573} 574.Ed 575.Sh SEE ALSO 576.Xr wpa_cli 8 , 577.Xr wpa_passphrase 8 , 578.Xr wpa_supplicant 8 579.Sh HISTORY 580The 581.Nm 582manual page and 583.Xr wpa_supplicant 8 584functionality first appeared in 585.Fx 6.0 . 586.Sh AUTHORS 587This manual page is derived from the 588.Pa README 589and 590.Pa wpa_supplicant.conf 591files in the 592.Nm wpa_supplicant 593distribution provided by 594.An Jouni Malinen Aq Mt j@w1.fi . 595