1wpa_supplicant and Hotspot 2.0 2============================== 3 4This document describe how the IEEE 802.11u Interworking and Wi-Fi 5Hotspot 2.0 (Release 1) implementation in wpa_supplicant can be 6configured and how an external component on the client e.g., management 7GUI or Wi-Fi framework) is used to manage this functionality. 8 9 10Introduction to Wi-Fi Hotspot 2.0 11--------------------------------- 12 13Hotspot 2.0 is the name of the Wi-Fi Alliance specification that is used 14in the Wi-Fi CERTIFIED Passpoint<TM> program. More information about 15this is available in this white paper: 16 17http://www.wi-fi.org/knowledge-center/white-papers/wi-fi-certified-passpoint%E2%84%A2-new-program-wi-fi-alliance%C2%AE-enable-seamless 18 19The Hotspot 2.0 specification is also available from WFA: 20https://www.wi-fi.org/knowledge-center/published-specifications 21 22The core Interworking functionality (network selection, GAS/ANQP) were 23standardized in IEEE Std 802.11u-2011 which is now part of the IEEE Std 24802.11-2012. 25 26 27wpa_supplicant network selection 28-------------------------------- 29 30Interworking support added option for configuring credentials that can 31work with multiple networks as an alternative to configuration of 32network blocks (e.g., per-SSID parameters). When requested to perform 33network selection, wpa_supplicant picks the highest priority enabled 34network block or credential. If a credential is picked (based on ANQP 35information from APs), a temporary network block is created 36automatically for the matching network. This temporary network block is 37used similarly to the network blocks that can be configured by the user, 38but it is not stored into the configuration file and is meant to be used 39only for temporary period of time since a new one can be created 40whenever needed based on ANQP information and the credential. 41 42By default, wpa_supplicant is not using automatic network selection 43unless requested explicitly with the interworking_select command. This 44can be changed with the auto_interworking=1 parameter to perform network 45selection automatically whenever trying to find a network for connection 46and none of the enabled network blocks match with the scan results. This 47case works similarly to "interworking_select auto", i.e., wpa_supplicant 48will internally determine which network or credential is going to be 49used based on configured priorities, scan results, and ANQP information. 50 51 52wpa_supplicant configuration 53---------------------------- 54 55Interworking and Hotspot 2.0 functionality are optional components that 56need to be enabled in the wpa_supplicant build configuration 57(.config). This is done by adding following parameters into that file: 58 59CONFIG_INTERWORKING=y 60CONFIG_HS20=y 61 62It should be noted that this functionality requires a driver that 63supports GAS/ANQP operations. This uses the same design as P2P, i.e., 64Action frame processing and building in user space within 65wpa_supplicant. The Linux nl80211 driver interface provides the needed 66functionality for this. 67 68 69There are number of run-time configuration parameters (e.g., in 70wpa_supplicant.conf when using the configuration file) that can be used 71to control Hotspot 2.0 operations. 72 73# Enable Interworking 74interworking=1 75 76# Enable Hotspot 2.0 77hs20=1 78 79# Parameters for controlling scanning 80 81# Homogenous ESS identifier 82# If this is set, scans will be used to request response only from BSSes 83# belonging to the specified Homogeneous ESS. This is used only if interworking 84# is enabled. 85#hessid=00:11:22:33:44:55 86 87# Access Network Type 88# When Interworking is enabled, scans can be limited to APs that advertise the 89# specified Access Network Type (0..15; with 15 indicating wildcard match). 90# This value controls the Access Network Type value in Probe Request frames. 91#access_network_type=15 92 93# Automatic network selection behavior 94# 0 = do not automatically go through Interworking network selection 95# (i.e., require explicit interworking_select command for this; default) 96# 1 = perform Interworking network selection if one or more 97# credentials have been configured and scan did not find a 98# matching network block 99#auto_interworking=0 100 101 102Credentials can be pre-configured for automatic network selection: 103 104# credential block 105# 106# Each credential used for automatic network selection is configured as a set 107# of parameters that are compared to the information advertised by the APs when 108# interworking_select and interworking_connect commands are used. 109# 110# credential fields: 111# 112# temporary: Whether this credential is temporary and not to be saved 113# 114# priority: Priority group 115# By default, all networks and credentials get the same priority group 116# (0). This field can be used to give higher priority for credentials 117# (and similarly in struct wpa_ssid for network blocks) to change the 118# Interworking automatic networking selection behavior. The matching 119# network (based on either an enabled network block or a credential) 120# with the highest priority value will be selected. 121# 122# pcsc: Use PC/SC and SIM/USIM card 123# 124# realm: Home Realm for Interworking 125# 126# username: Username for Interworking network selection 127# 128# password: Password for Interworking network selection 129# 130# ca_cert: CA certificate for Interworking network selection 131# 132# client_cert: File path to client certificate file (PEM/DER) 133# This field is used with Interworking networking selection for a case 134# where client certificate/private key is used for authentication 135# (EAP-TLS). Full path to the file should be used since working 136# directory may change when wpa_supplicant is run in the background. 137# 138# Alternatively, a named configuration blob can be used by setting 139# this to blob://blob_name. 140# 141# private_key: File path to client private key file (PEM/DER/PFX) 142# When PKCS#12/PFX file (.p12/.pfx) is used, client_cert should be 143# commented out. Both the private key and certificate will be read 144# from the PKCS#12 file in this case. Full path to the file should be 145# used since working directory may change when wpa_supplicant is run 146# in the background. 147# 148# Windows certificate store can be used by leaving client_cert out and 149# configuring private_key in one of the following formats: 150# 151# cert://substring_to_match 152# 153# hash://certificate_thumbprint_in_hex 154# 155# For example: private_key="hash://63093aa9c47f56ae88334c7b65a4" 156# 157# Note that when running wpa_supplicant as an application, the user 158# certificate store (My user account) is used, whereas computer store 159# (Computer account) is used when running wpasvc as a service. 160# 161# Alternatively, a named configuration blob can be used by setting 162# this to blob://blob_name. 163# 164# private_key_passwd: Password for private key file 165# 166# imsi: IMSI in <MCC> | <MNC> | '-' | <MSIN> format 167# 168# milenage: Milenage parameters for SIM/USIM simulator in <Ki>:<OPc>:<SQN> 169# format 170# 171# domain_suffix_match: Constraint for server domain name 172# If set, this FQDN is used as a suffix match requirement for the AAA 173# server certificate in SubjectAltName dNSName element(s). If a 174# matching dNSName is found, this constraint is met. If no dNSName 175# values are present, this constraint is matched against SubjetName CN 176# using same suffix match comparison. Suffix match here means that the 177# host/domain name is compared one label at a time starting from the 178# top-level domain and all the labels in @domain_suffix_match shall be 179# included in the certificate. The certificate may include additional 180# sub-level labels in addition to the required labels. 181# 182# For example, domain_suffix_match=example.com would match 183# test.example.com but would not match test-example.com. 184# 185# domain: Home service provider FQDN(s) 186# This is used to compare against the Domain Name List to figure out 187# whether the AP is operated by the Home SP. Multiple domain entries can 188# be used to configure alternative FQDNs that will be considered home 189# networks. 190# 191# roaming_consortium: Roaming Consortium OI 192# If roaming_consortium_len is non-zero, this field contains the 193# Roaming Consortium OI that can be used to determine which access 194# points support authentication with this credential. This is an 195# alternative to the use of the realm parameter. When using Roaming 196# Consortium to match the network, the EAP parameters need to be 197# pre-configured with the credential since the NAI Realm information 198# may not be available or fetched. 199# 200# eap: Pre-configured EAP method 201# This optional field can be used to specify which EAP method will be 202# used with this credential. If not set, the EAP method is selected 203# automatically based on ANQP information (e.g., NAI Realm). 204# 205# phase1: Pre-configure Phase 1 (outer authentication) parameters 206# This optional field is used with like the 'eap' parameter. 207# 208# phase2: Pre-configure Phase 2 (inner authentication) parameters 209# This optional field is used with like the 'eap' parameter. 210# 211# excluded_ssid: Excluded SSID 212# This optional field can be used to excluded specific SSID(s) from 213# matching with the network. Multiple entries can be used to specify more 214# than one SSID. 215# 216# for example: 217# 218#cred={ 219# realm="example.com" 220# username="user@example.com" 221# password="password" 222# ca_cert="/etc/wpa_supplicant/ca.pem" 223# domain="example.com" 224# domain_suffix_match="example.com" 225#} 226# 227#cred={ 228# imsi="310026-000000000" 229# milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82" 230#} 231# 232#cred={ 233# realm="example.com" 234# username="user" 235# password="password" 236# ca_cert="/etc/wpa_supplicant/ca.pem" 237# domain="example.com" 238# roaming_consortium=223344 239# eap=TTLS 240# phase2="auth=MSCHAPV2" 241#} 242 243 244Control interface 245----------------- 246 247wpa_supplicant provides a control interface that can be used from 248external programs to manage various operations. The included command 249line tool, wpa_cli, can be used for manual testing with this interface. 250 251Following wpa_cli interactive mode commands show some examples of manual 252operations related to Hotspot 2.0: 253 254Remove configured networks and credentials: 255 256> remove_network all 257OK 258> remove_cred all 259OK 260 261 262Add a username/password credential: 263 264> add_cred 2650 266> set_cred 0 realm "mail.example.com" 267OK 268> set_cred 0 username "username" 269OK 270> set_cred 0 password "password" 271OK 272> set_cred 0 priority 1 273OK 274> set_cred 0 temporary 1 275OK 276 277Add a SIM credential using a simulated SIM/USIM card for testing: 278 279> add_cred 2801 281> set_cred 1 imsi "23456-0000000000" 282OK 283> set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123" 284OK 285> set_cred 1 priority 1 286OK 287 288Note: the return value of add_cred is used as the first argument to 289the following set_cred commands. 290 291Add a SIM credential using a external SIM/USIM processing: 292 293> set external_sim 1 294OK 295> add_cred 2961 297> set_cred 1 imsi "23456-0000000000" 298OK 299> set_cred 1 eap SIM 300OK 301 302 303Add a WPA2-Enterprise network: 304 305> add_network 3060 307> set_network 0 key_mgmt WPA-EAP 308OK 309> set_network 0 ssid "enterprise" 310OK 311> set_network 0 eap TTLS 312OK 313> set_network 0 anonymous_identity "anonymous" 314OK 315> set_network 0 identity "user" 316OK 317> set_network 0 password "password" 318OK 319> set_network 0 priority 0 320OK 321> enable_network 0 no-connect 322OK 323 324 325Add an open network: 326 327> add_network 3283 329> set_network 3 key_mgmt NONE 330OK 331> set_network 3 ssid "coffee-shop" 332OK 333> select_network 3 334OK 335 336Note: the return value of add_network is used as the first argument to 337the following set_network commands. 338 339The preferred credentials/networks can be indicated with the priority 340parameter (1 is higher priority than 0). 341 342 343Interworking network selection can be started with interworking_select 344command. This instructs wpa_supplicant to run a network scan and iterate 345through the discovered APs to request ANQP information from the APs that 346advertise support for Interworking/Hotspot 2.0: 347 348> interworking_select 349OK 350<3>Starting ANQP fetch for 02:00:00:00:01:00 351<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 352<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 353<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 354<3>ANQP fetch completed 355<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 356 357 358INTERWORKING-AP event messages indicate the APs that support network 359selection and for which there is a matching 360credential. interworking_connect command can be used to select a network 361to connect with: 362 363 364> interworking_connect 02:00:00:00:01:00 365OK 366<3>CTRL-EVENT-SCAN-RESULTS 367<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 368<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 369<3>Associated with 02:00:00:00:01:00 370<3>CTRL-EVENT-EAP-STARTED EAP authentication started 371<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 372<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 373<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 374<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 375<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=] 376 377 378wpa_supplicant creates a temporary network block for the selected 379network based on the configured credential and ANQP information from the 380AP: 381 382> list_networks 383network id / ssid / bssid / flags 3840 Example Network any [CURRENT] 385> get_network 0 key_mgmt 386WPA-EAP 387> get_network 0 eap 388TTLS 389 390 391Alternatively to using an external program to select the network, 392"interworking_select auto" command can be used to request wpa_supplicant 393to select which network to use based on configured priorities: 394 395 396> remove_network all 397OK 398<3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1 399> interworking_select auto 400OK 401<3>Starting ANQP fetch for 02:00:00:00:01:00 402<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 403<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 404<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 405<3>ANQP fetch completed 406<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 407<3>CTRL-EVENT-SCAN-RESULTS 408<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 409<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 410<3>Associated with 02:00:00:00:01:00 411<3>CTRL-EVENT-EAP-STARTED EAP authentication started 412<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 413<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 414<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 415<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 416<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=] 417 418 419The connection status can be shown with the status command: 420 421> status 422bssid=02:00:00:00:01:00 423ssid=Example Network 424id=0 425mode=station 426pairwise_cipher=CCMP <--- link layer security indication 427group_cipher=CCMP 428key_mgmt=WPA2/IEEE 802.1X/EAP 429wpa_state=COMPLETED 430p2p_device_address=02:00:00:00:00:00 431address=02:00:00:00:00:00 432hs20=1 <--- HS 2.0 indication 433Supplicant PAE state=AUTHENTICATED 434suppPortStatus=Authorized 435EAP state=SUCCESS 436selectedMethod=21 (EAP-TTLS) 437EAP TLS cipher=AES-128-SHA 438EAP-TTLSv0 Phase2 method=PAP 439 440 441> status 442bssid=02:00:00:00:02:00 443ssid=coffee-shop 444id=3 445mode=station 446pairwise_cipher=NONE 447group_cipher=NONE 448key_mgmt=NONE 449wpa_state=COMPLETED 450p2p_device_address=02:00:00:00:00:00 451address=02:00:00:00:00:00 452 453 454Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status 455command output. Link layer security is indicated with the 456pairwise_cipher (CCMP = secure, NONE = no encryption used). 457 458 459Also the scan results include the Hotspot 2.0 indication: 460 461> scan_results 462bssid / frequency / signal level / flags / ssid 46302:00:00:00:01:00 2412 -30 [WPA2-EAP-CCMP][ESS][HS20] Example Network 464 465 466ANQP information for the BSS can be fetched using the BSS command: 467 468> bss 02:00:00:00:01:00 469id=1 470bssid=02:00:00:00:01:00 471freq=2412 472beacon_int=100 473capabilities=0x0411 474qual=0 475noise=-92 476level=-30 477tsf=1345573286517276 478age=105 479ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000 480flags=[WPA2-EAP-CCMP][ESS][HS20] 481ssid=Example Network 482anqp_roaming_consortium=031122330510203040500601020304050603fedcba 483 484 485ANQP queries can also be requested with the anqp_get and hs20_anqp_get 486commands: 487 488> anqp_get 02:00:00:00:01:00 261 489OK 490<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 491> hs20_anqp_get 02:00:00:00:01:00 2 492OK 493<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 494 495In addition, fetch_anqp command can be used to request similar set of 496ANQP queries to be done as is run as part of interworking_select: 497 498> scan 499OK 500<3>CTRL-EVENT-SCAN-RESULTS 501> fetch_anqp 502OK 503<3>Starting ANQP fetch for 02:00:00:00:01:00 504<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 505<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 506<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 507<3>ANQP fetch completed 508