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# Homogeneous 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 SubjectName 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# required_roaming_consortium: Required Roaming Consortium OI 201# If required_roaming_consortium_len is non-zero, this field contains the 202# Roaming Consortium OI that is required to be advertised by the AP for 203# the credential to be considered matching. 204# 205# roaming_consortiums: Roaming Consortium OI(s) memberships 206# This string field contains one or more comma delimited OIs (hexdump) 207# identifying the roaming consortiums of which the provider is a member. 208# The list is sorted from the most preferred one to the least preferred 209# one. A match between the Roaming Consortium OIs advertised by an AP and 210# the OIs in this list indicates that successful authentication is 211# possible. 212# (Hotspot 2.0 PerProviderSubscription/<X+>/HomeSP/RoamingConsortiumOI) 213# 214# eap: Pre-configured EAP method 215# This optional field can be used to specify which EAP method will be 216# used with this credential. If not set, the EAP method is selected 217# automatically based on ANQP information (e.g., NAI Realm). 218# 219# phase1: Pre-configure Phase 1 (outer authentication) parameters 220# This optional field is used with like the 'eap' parameter. 221# 222# phase2: Pre-configure Phase 2 (inner authentication) parameters 223# This optional field is used with like the 'eap' parameter. 224# 225# excluded_ssid: Excluded SSID 226# This optional field can be used to excluded specific SSID(s) from 227# matching with the network. Multiple entries can be used to specify more 228# than one SSID. 229# 230# roaming_partner: Roaming partner information 231# This optional field can be used to configure preferences between roaming 232# partners. The field is a string in following format: 233# <FQDN>,<0/1 exact match>,<priority>,<* or country code> 234# (non-exact match means any subdomain matches the entry; priority is in 235# 0..255 range with 0 being the highest priority) 236# 237# update_identifier: PPS MO ID 238# (Hotspot 2.0 PerProviderSubscription/UpdateIdentifier) 239# 240# provisioning_sp: FQDN of the SP that provisioned the credential 241# This optional field can be used to keep track of the SP that provisioned 242# the credential to find the PPS MO (./Wi-Fi/<provisioning_sp>). 243# 244# sp_priority: Credential priority within a provisioning SP 245# This is the priority of the credential among all credentials 246# provisioned by the same SP (i.e., for entries that have identical 247# provisioning_sp value). The range of this priority is 0-255 with 0 248# being the highest and 255 the lower priority. 249# 250# Minimum backhaul threshold (PPS/<X+>/Policy/MinBackhauldThreshold/*) 251# These fields can be used to specify minimum download/upload backhaul 252# bandwidth that is preferred for the credential. This constraint is 253# ignored if the AP does not advertise WAN Metrics information or if the 254# limit would prevent any connection. Values are in kilobits per second. 255# min_dl_bandwidth_home 256# min_ul_bandwidth_home 257# min_dl_bandwidth_roaming 258# min_ul_bandwidth_roaming 259# 260# max_bss_load: Maximum BSS Load Channel Utilization (1..255) 261# (PPS/<X+>/Policy/MaximumBSSLoadValue) 262# This value is used as the maximum channel utilization for network 263# selection purposes for home networks. If the AP does not advertise 264# BSS Load or if the limit would prevent any connection, this constraint 265# will be ignored. 266# 267# req_conn_capab: Required connection capability 268# (PPS/<X+>/Policy/RequiredProtoPortTuple) 269# This value is used to configure set of required protocol/port pairs that 270# a roaming network shall support (include explicitly in Connection 271# Capability ANQP element). This constraint is ignored if the AP does not 272# advertise Connection Capability or if this constraint would prevent any 273# network connection. This policy is not used in home networks. 274# Format: <protocol>[:<comma-separated list of ports] 275# Multiple entries can be used to list multiple requirements. 276# For example, number of common TCP protocols: 277# req_conn_capab=6:22,80,443 278# For example, IPSec/IKE: 279# req_conn_capab=17:500 280# req_conn_capab=50 281# 282# ocsp: Whether to use/require OCSP to check server certificate 283# 0 = do not use OCSP stapling (TLS certificate status extension) 284# 1 = try to use OCSP stapling, but not require response 285# 2 = require valid OCSP stapling response 286# 287# sim_num: Identifier for which SIM to use in multi-SIM devices 288# 289# engine: Whether to use an engine for private key operations (0/1) 290# engine_id: String identifying the engine to use 291# ca_cert_id: The CA certificate identifier when using an engine 292# cert_id: The certificate identifier when using an engine 293# key_id: The private key identifier when using an engine 294# 295# for example: 296# 297#cred={ 298# realm="example.com" 299# username="user@example.com" 300# password="password" 301# ca_cert="/etc/wpa_supplicant/ca.pem" 302# domain="example.com" 303# domain_suffix_match="example.com" 304#} 305# 306#cred={ 307# imsi="310026-000000000" 308# milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82" 309#} 310# 311#cred={ 312# realm="example.com" 313# username="user" 314# password="password" 315# ca_cert="/etc/wpa_supplicant/ca.pem" 316# domain="example.com" 317# roaming_consortium=223344 318# roaming_consortiums="112233,4455667788,aabbcc" 319# eap=TTLS 320# phase2="auth=MSCHAPV2" 321#} 322 323 324Control interface 325----------------- 326 327wpa_supplicant provides a control interface that can be used from 328external programs to manage various operations. The included command 329line tool, wpa_cli, can be used for manual testing with this interface. 330 331Following wpa_cli interactive mode commands show some examples of manual 332operations related to Hotspot 2.0: 333 334Remove configured networks and credentials: 335 336> remove_network all 337OK 338> remove_cred all 339OK 340 341 342Add a username/password credential: 343 344> add_cred 3450 346> set_cred 0 realm "mail.example.com" 347OK 348> set_cred 0 username "username" 349OK 350> set_cred 0 password "password" 351OK 352> set_cred 0 priority 1 353OK 354> set_cred 0 temporary 1 355OK 356 357Add a SIM credential using a simulated SIM/USIM card for testing: 358 359> add_cred 3601 361> set_cred 1 imsi "23456-0000000000" 362OK 363> set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123" 364OK 365> set_cred 1 priority 1 366OK 367 368Note: the return value of add_cred is used as the first argument to 369the following set_cred commands. 370 371Add a SIM credential using a external SIM/USIM processing: 372 373> set external_sim 1 374OK 375> add_cred 3761 377> set_cred 1 imsi "23456-0000000000" 378OK 379> set_cred 1 eap SIM 380OK 381 382 383Add a WPA2-Enterprise network: 384 385> add_network 3860 387> set_network 0 key_mgmt WPA-EAP 388OK 389> set_network 0 ssid "enterprise" 390OK 391> set_network 0 eap TTLS 392OK 393> set_network 0 anonymous_identity "anonymous" 394OK 395> set_network 0 identity "user" 396OK 397> set_network 0 password "password" 398OK 399> set_network 0 priority 0 400OK 401> enable_network 0 no-connect 402OK 403 404 405Add an open network: 406 407> add_network 4083 409> set_network 3 key_mgmt NONE 410OK 411> set_network 3 ssid "coffee-shop" 412OK 413> select_network 3 414OK 415 416Note: the return value of add_network is used as the first argument to 417the following set_network commands. 418 419The preferred credentials/networks can be indicated with the priority 420parameter (1 is higher priority than 0). 421 422 423Interworking network selection can be started with interworking_select 424command. This instructs wpa_supplicant to run a network scan and iterate 425through the discovered APs to request ANQP information from the APs that 426advertise support for Interworking/Hotspot 2.0: 427 428> interworking_select 429OK 430<3>Starting ANQP fetch for 02:00:00:00:01:00 431<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 432<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 433<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 434<3>ANQP fetch completed 435<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 436 437 438INTERWORKING-AP event messages indicate the APs that support network 439selection and for which there is a matching 440credential. interworking_connect command can be used to select a network 441to connect with: 442 443 444> interworking_connect 02:00:00:00:01:00 445OK 446<3>CTRL-EVENT-SCAN-RESULTS 447<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 448<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 449<3>Associated with 02:00:00:00:01:00 450<3>CTRL-EVENT-EAP-STARTED EAP authentication started 451<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 452<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 453<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 454<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 455<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=] 456 457 458wpa_supplicant creates a temporary network block for the selected 459network based on the configured credential and ANQP information from the 460AP: 461 462> list_networks 463network id / ssid / bssid / flags 4640 Example Network any [CURRENT] 465> get_network 0 key_mgmt 466WPA-EAP 467> get_network 0 eap 468TTLS 469 470 471Alternatively to using an external program to select the network, 472"interworking_select auto" command can be used to request wpa_supplicant 473to select which network to use based on configured priorities: 474 475 476> remove_network all 477OK 478<3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1 479> interworking_select auto 480OK 481<3>Starting ANQP fetch for 02:00:00:00:01:00 482<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 483<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 484<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 485<3>ANQP fetch completed 486<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 487<3>CTRL-EVENT-SCAN-RESULTS 488<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 489<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 490<3>Associated with 02:00:00:00:01:00 491<3>CTRL-EVENT-EAP-STARTED EAP authentication started 492<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 493<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 494<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 495<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 496<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=] 497 498 499The connection status can be shown with the status command: 500 501> status 502bssid=02:00:00:00:01:00 503ssid=Example Network 504id=0 505mode=station 506pairwise_cipher=CCMP <--- link layer security indication 507group_cipher=CCMP 508key_mgmt=WPA2/IEEE 802.1X/EAP 509wpa_state=COMPLETED 510p2p_device_address=02:00:00:00:00:00 511address=02:00:00:00:00:00 512hs20=1 <--- HS 2.0 indication 513Supplicant PAE state=AUTHENTICATED 514suppPortStatus=Authorized 515EAP state=SUCCESS 516selectedMethod=21 (EAP-TTLS) 517EAP TLS cipher=AES-128-SHA 518EAP-TTLSv0 Phase2 method=PAP 519 520 521> status 522bssid=02:00:00:00:02:00 523ssid=coffee-shop 524id=3 525mode=station 526pairwise_cipher=NONE 527group_cipher=NONE 528key_mgmt=NONE 529wpa_state=COMPLETED 530p2p_device_address=02:00:00:00:00:00 531address=02:00:00:00:00:00 532 533 534Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status 535command output. Link layer security is indicated with the 536pairwise_cipher (CCMP = secure, NONE = no encryption used). 537 538 539Also the scan results include the Hotspot 2.0 indication: 540 541> scan_results 542bssid / frequency / signal level / flags / ssid 54302:00:00:00:01:00 2412 -30 [WPA2-EAP-CCMP][ESS][HS20] Example Network 544 545 546ANQP information for the BSS can be fetched using the BSS command: 547 548> bss 02:00:00:00:01:00 549id=1 550bssid=02:00:00:00:01:00 551freq=2412 552beacon_int=100 553capabilities=0x0411 554qual=0 555noise=-92 556level=-30 557tsf=1345573286517276 558age=105 559ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000 560flags=[WPA2-EAP-CCMP][ESS][HS20] 561ssid=Example Network 562anqp_roaming_consortium=031122330510203040500601020304050603fedcba 563 564 565ANQP queries can also be requested with the anqp_get and hs20_anqp_get 566commands: 567 568> anqp_get 02:00:00:00:01:00 261 569OK 570<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 571> hs20_anqp_get 02:00:00:00:01:00 2 572OK 573<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 574 575In addition, fetch_anqp command can be used to request similar set of 576ANQP queries to be done as is run as part of interworking_select: 577 578> scan 579OK 580<3>CTRL-EVENT-SCAN-RESULTS 581> fetch_anqp 582OK 583<3>Starting ANQP fetch for 02:00:00:00:01:00 584<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 585<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 586<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 587<3>ANQP fetch completed 588 589 590Hotspot 2.0 Rel 2 online signup and OSEN 591---------------------------------------- 592 593Following parameters can be used to create a network profile for 594link-layer protected Hotspot 2.0 online signup connection with 595OSEN. Note that ssid and identify (NAI) values need to be set based on 596the information for the selected provider in the OSU Providers list 597ANQP-element. 598 599network={ 600 ssid="HS 2.0 OSU" 601 proto=OSEN 602 key_mgmt=OSEN 603 pairwise=CCMP 604 group=GTK_NOT_USED 605 eap=WFA-UNAUTH-TLS 606 identity="anonymous@example.com" 607 ca_cert="osu-ca.pem" 608 ocsp=2 609} 610 611 612Hotspot 2.0 connection with external network selection 613------------------------------------------------------ 614 615When a component controlling wpa_supplicant takes care of Interworking 616network selection, following configuration and network profile 617parameters can be used to configure a temporary network profile for a 618Hotspot 2.0 connection (e.g., with SET, ADD_NETWORK, SET_NETWORK, and 619SELECT_NETWORK control interface commands): 620 621interworking=1 622hs20=1 623auto_interworking=0 624 625network={ 626 ssid="test-hs20" 627 proto=RSN 628 key_mgmt=WPA-EAP 629 pairwise=CCMP 630 anonymous_identity="anonymous@example.com" 631 identity="hs20-test@example.com" 632 password="password" 633 ca_cert="ca.pem" 634 eap=TTLS 635 phase2="auth=MSCHAPV2" 636 update_identifier=54321 637 roaming_consortium_selection=112233 638 #ocsp=2 639} 640 641 642These parameters are set based on the PPS MO credential and/or NAI Realm 643list ANQP-element: 644 645anonymous_identity: Credential/UsernamePassword/Username with username part 646 replaced with "anonymous" 647identity: Credential/UsernamePassword/Username 648password: Credential/UsernamePassword/Password 649update_identifier: PPS/UpdateIdentifier 650ca_cert: from the downloaded trust root based on PPS information 651eap: Credential/UsernamePassword/EAPMethod or NAI Realm list 652phase2: Credential/UsernamePassword/EAPMethod or NAI Realm list 653roaming_consortium_selection: Matching OI from HomeSP/RoamingConsortiumOI 654ocsp: Credential/CheckAAAServerCertStatus 655