1 wpa_supplicant and Hotspot 2.0 2 ============================== 3 4 This document describe how the IEEE 802.11u Interworking and Wi-Fi 5 Hotspot 2.0 (Release 1) implementation in wpa_supplicant can be 6 configured and how an external component on the client e.g., management 7 GUI or Wi-Fi framework) is used to manage this functionality. 8 9 10 Introduction to Wi-Fi Hotspot 2.0 11 --------------------------------- 12 13 Hotspot 2.0 is the name of the Wi-Fi Alliance specification that is used 14 in the Wi-Fi CERTIFIED Passpoint<TM> program. More information about 15 this is available in this white paper: 16 17 http://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 19 The Hotspot 2.0 specification is also available from WFA: 20 https://www.wi-fi.org/knowledge-center/published-specifications 21 22 The core Interworking functionality (network selection, GAS/ANQP) were 23 standardized in IEEE Std 802.11u-2011 which is now part of the IEEE Std 24 802.11-2012. 25 26 27 wpa_supplicant network selection 28 -------------------------------- 29 30 Interworking support added option for configuring credentials that can 31 work with multiple networks as an alternative to configuration of 32 network blocks (e.g., per-SSID parameters). When requested to perform 33 network selection, wpa_supplicant picks the highest priority enabled 34 network block or credential. If a credential is picked (based on ANQP 35 information from APs), a temporary network block is created 36 automatically for the matching network. This temporary network block is 37 used similarly to the network blocks that can be configured by the user, 38 but it is not stored into the configuration file and is meant to be used 39 only for temporary period of time since a new one can be created 40 whenever needed based on ANQP information and the credential. 41 42 By default, wpa_supplicant is not using automatic network selection 43 unless requested explicitly with the interworking_select command. This 44 can be changed with the auto_interworking=1 parameter to perform network 45 selection automatically whenever trying to find a network for connection 46 and none of the enabled network blocks match with the scan results. This 47 case works similarly to "interworking_select auto", i.e., wpa_supplicant 48 will internally determine which network or credential is going to be 49 used based on configured priorities, scan results, and ANQP information. 50 51 52 wpa_supplicant configuration 53 ---------------------------- 54 55 Interworking and Hotspot 2.0 functionality are optional components that 56 need to be enabled in the wpa_supplicant build configuration 57 (.config). This is done by adding following parameters into that file: 58 59 CONFIG_INTERWORKING=y 60 CONFIG_HS20=y 61 62 It should be noted that this functionality requires a driver that 63 supports GAS/ANQP operations. This uses the same design as P2P, i.e., 64 Action frame processing and building in user space within 65 wpa_supplicant. The Linux nl80211 driver interface provides the needed 66 functionality for this. 67 68 69 There are number of run-time configuration parameters (e.g., in 70 wpa_supplicant.conf when using the configuration file) that can be used 71 to control Hotspot 2.0 operations. 72 73 # Enable Interworking 74 interworking=1 75 76 # Enable Hotspot 2.0 77 hs20=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 102 Credentials 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 # 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 # roaming_partner: Roaming partner information 217 # This optional field can be used to configure preferences between roaming 218 # partners. The field is a string in following format: 219 # <FQDN>,<0/1 exact match>,<priority>,<* or country code> 220 # (non-exact match means any subdomain matches the entry; priority is in 221 # 0..255 range with 0 being the highest priority) 222 # 223 # update_identifier: PPS MO ID 224 # (Hotspot 2.0 PerProviderSubscription/UpdateIdentifier) 225 # 226 # provisioning_sp: FQDN of the SP that provisioned the credential 227 # This optional field can be used to keep track of the SP that provisioned 228 # the credential to find the PPS MO (./Wi-Fi/<provisioning_sp>). 229 # 230 # sp_priority: Credential priority within a provisioning SP 231 # This is the priority of the credential among all credentials 232 # provisioned by the same SP (i.e., for entries that have identical 233 # provisioning_sp value). The range of this priority is 0-255 with 0 234 # being the highest and 255 the lower priority. 235 # 236 # Minimum backhaul threshold (PPS/<X+>/Policy/MinBackhauldThreshold/*) 237 # These fields can be used to specify minimum download/upload backhaul 238 # bandwidth that is preferred for the credential. This constraint is 239 # ignored if the AP does not advertise WAN Metrics information or if the 240 # limit would prevent any connection. Values are in kilobits per second. 241 # min_dl_bandwidth_home 242 # min_ul_bandwidth_home 243 # min_dl_bandwidth_roaming 244 # min_ul_bandwidth_roaming 245 # 246 # max_bss_load: Maximum BSS Load Channel Utilization (1..255) 247 # (PPS/<X+>/Policy/MaximumBSSLoadValue) 248 # This value is used as the maximum channel utilization for network 249 # selection purposes for home networks. If the AP does not advertise 250 # BSS Load or if the limit would prevent any connection, this constraint 251 # will be ignored. 252 # 253 # req_conn_capab: Required connection capability 254 # (PPS/<X+>/Policy/RequiredProtoPortTuple) 255 # This value is used to configure set of required protocol/port pairs that 256 # a roaming network shall support (include explicitly in Connection 257 # Capability ANQP element). This constraint is ignored if the AP does not 258 # advertise Connection Capability or if this constraint would prevent any 259 # network connection. This policy is not used in home networks. 260 # Format: <protocol>[:<comma-separated list of ports] 261 # Multiple entries can be used to list multiple requirements. 262 # For example, number of common TCP protocols: 263 # req_conn_capab=6:22,80,443 264 # For example, IPSec/IKE: 265 # req_conn_capab=17:500 266 # req_conn_capab=50 267 # 268 # ocsp: Whether to use/require OCSP to check server certificate 269 # 0 = do not use OCSP stapling (TLS certificate status extension) 270 # 1 = try to use OCSP stapling, but not require response 271 # 2 = require valid OCSP stapling response 272 # 273 # sim_num: Identifier for which SIM to use in multi-SIM devices 274 # 275 # for example: 276 # 277 #cred={ 278 # realm="example.com" 279 # username="user (a] example.com" 280 # password="password" 281 # ca_cert="/etc/wpa_supplicant/ca.pem" 282 # domain="example.com" 283 # domain_suffix_match="example.com" 284 #} 285 # 286 #cred={ 287 # imsi="310026-000000000" 288 # milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82" 289 #} 290 # 291 #cred={ 292 # realm="example.com" 293 # username="user" 294 # password="password" 295 # ca_cert="/etc/wpa_supplicant/ca.pem" 296 # domain="example.com" 297 # roaming_consortium=223344 298 # eap=TTLS 299 # phase2="auth=MSCHAPV2" 300 #} 301 302 303 Control interface 304 ----------------- 305 306 wpa_supplicant provides a control interface that can be used from 307 external programs to manage various operations. The included command 308 line tool, wpa_cli, can be used for manual testing with this interface. 309 310 Following wpa_cli interactive mode commands show some examples of manual 311 operations related to Hotspot 2.0: 312 313 Remove configured networks and credentials: 314 315 > remove_network all 316 OK 317 > remove_cred all 318 OK 319 320 321 Add a username/password credential: 322 323 > add_cred 324 0 325 > set_cred 0 realm "mail.example.com" 326 OK 327 > set_cred 0 username "username" 328 OK 329 > set_cred 0 password "password" 330 OK 331 > set_cred 0 priority 1 332 OK 333 > set_cred 0 temporary 1 334 OK 335 336 Add a SIM credential using a simulated SIM/USIM card for testing: 337 338 > add_cred 339 1 340 > set_cred 1 imsi "23456-0000000000" 341 OK 342 > set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123" 343 OK 344 > set_cred 1 priority 1 345 OK 346 347 Note: the return value of add_cred is used as the first argument to 348 the following set_cred commands. 349 350 Add a SIM credential using a external SIM/USIM processing: 351 352 > set external_sim 1 353 OK 354 > add_cred 355 1 356 > set_cred 1 imsi "23456-0000000000" 357 OK 358 > set_cred 1 eap SIM 359 OK 360 361 362 Add a WPA2-Enterprise network: 363 364 > add_network 365 0 366 > set_network 0 key_mgmt WPA-EAP 367 OK 368 > set_network 0 ssid "enterprise" 369 OK 370 > set_network 0 eap TTLS 371 OK 372 > set_network 0 anonymous_identity "anonymous" 373 OK 374 > set_network 0 identity "user" 375 OK 376 > set_network 0 password "password" 377 OK 378 > set_network 0 priority 0 379 OK 380 > enable_network 0 no-connect 381 OK 382 383 384 Add an open network: 385 386 > add_network 387 3 388 > set_network 3 key_mgmt NONE 389 OK 390 > set_network 3 ssid "coffee-shop" 391 OK 392 > select_network 3 393 OK 394 395 Note: the return value of add_network is used as the first argument to 396 the following set_network commands. 397 398 The preferred credentials/networks can be indicated with the priority 399 parameter (1 is higher priority than 0). 400 401 402 Interworking network selection can be started with interworking_select 403 command. This instructs wpa_supplicant to run a network scan and iterate 404 through the discovered APs to request ANQP information from the APs that 405 advertise support for Interworking/Hotspot 2.0: 406 407 > interworking_select 408 OK 409 <3>Starting ANQP fetch for 02:00:00:00:01:00 410 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 411 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 412 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 413 <3>ANQP fetch completed 414 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 415 416 417 INTERWORKING-AP event messages indicate the APs that support network 418 selection and for which there is a matching 419 credential. interworking_connect command can be used to select a network 420 to connect with: 421 422 423 > interworking_connect 02:00:00:00:01:00 424 OK 425 <3>CTRL-EVENT-SCAN-RESULTS 426 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 427 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 428 <3>Associated with 02:00:00:00:01:00 429 <3>CTRL-EVENT-EAP-STARTED EAP authentication started 430 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 431 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 432 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 433 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 434 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=] 435 436 437 wpa_supplicant creates a temporary network block for the selected 438 network based on the configured credential and ANQP information from the 439 AP: 440 441 > list_networks 442 network id / ssid / bssid / flags 443 0 Example Network any [CURRENT] 444 > get_network 0 key_mgmt 445 WPA-EAP 446 > get_network 0 eap 447 TTLS 448 449 450 Alternatively to using an external program to select the network, 451 "interworking_select auto" command can be used to request wpa_supplicant 452 to select which network to use based on configured priorities: 453 454 455 > remove_network all 456 OK 457 <3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1 458 > interworking_select auto 459 OK 460 <3>Starting ANQP fetch for 02:00:00:00:01:00 461 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 462 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 463 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 464 <3>ANQP fetch completed 465 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 466 <3>CTRL-EVENT-SCAN-RESULTS 467 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 468 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 469 <3>Associated with 02:00:00:00:01:00 470 <3>CTRL-EVENT-EAP-STARTED EAP authentication started 471 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 472 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 473 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 474 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 475 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=] 476 477 478 The connection status can be shown with the status command: 479 480 > status 481 bssid=02:00:00:00:01:00 482 ssid=Example Network 483 id=0 484 mode=station 485 pairwise_cipher=CCMP <--- link layer security indication 486 group_cipher=CCMP 487 key_mgmt=WPA2/IEEE 802.1X/EAP 488 wpa_state=COMPLETED 489 p2p_device_address=02:00:00:00:00:00 490 address=02:00:00:00:00:00 491 hs20=1 <--- HS 2.0 indication 492 Supplicant PAE state=AUTHENTICATED 493 suppPortStatus=Authorized 494 EAP state=SUCCESS 495 selectedMethod=21 (EAP-TTLS) 496 EAP TLS cipher=AES-128-SHA 497 EAP-TTLSv0 Phase2 method=PAP 498 499 500 > status 501 bssid=02:00:00:00:02:00 502 ssid=coffee-shop 503 id=3 504 mode=station 505 pairwise_cipher=NONE 506 group_cipher=NONE 507 key_mgmt=NONE 508 wpa_state=COMPLETED 509 p2p_device_address=02:00:00:00:00:00 510 address=02:00:00:00:00:00 511 512 513 Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status 514 command output. Link layer security is indicated with the 515 pairwise_cipher (CCMP = secure, NONE = no encryption used). 516 517 518 Also the scan results include the Hotspot 2.0 indication: 519 520 > scan_results 521 bssid / frequency / signal level / flags / ssid 522 02:00:00:00:01:00 2412 -30 [WPA2-EAP-CCMP][ESS][HS20] Example Network 523 524 525 ANQP information for the BSS can be fetched using the BSS command: 526 527 > bss 02:00:00:00:01:00 528 id=1 529 bssid=02:00:00:00:01:00 530 freq=2412 531 beacon_int=100 532 capabilities=0x0411 533 qual=0 534 noise=-92 535 level=-30 536 tsf=1345573286517276 537 age=105 538 ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000 539 flags=[WPA2-EAP-CCMP][ESS][HS20] 540 ssid=Example Network 541 anqp_roaming_consortium=031122330510203040500601020304050603fedcba 542 543 544 ANQP queries can also be requested with the anqp_get and hs20_anqp_get 545 commands: 546 547 > anqp_get 02:00:00:00:01:00 261 548 OK 549 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 550 > hs20_anqp_get 02:00:00:00:01:00 2 551 OK 552 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 553 554 In addition, fetch_anqp command can be used to request similar set of 555 ANQP queries to be done as is run as part of interworking_select: 556 557 > scan 558 OK 559 <3>CTRL-EVENT-SCAN-RESULTS 560 > fetch_anqp 561 OK 562 <3>Starting ANQP fetch for 02:00:00:00:01:00 563 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 564 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 565 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 566 <3>ANQP fetch completed 567 568 569 Hotspot 2.0 Rel 2 online signup and OSEN 570 ---------------------------------------- 571 572 Following parameters can be used to create a network profile for 573 link-layer protected Hotspot 2.0 online signup connection with 574 OSEN. Note that ssid and identify (NAI) values need to be set based on 575 the information for the selected provider in the OSU Providers list 576 ANQP-element. 577 578 network={ 579 ssid="HS 2.0 OSU" 580 proto=OSEN 581 key_mgmt=OSEN 582 pairwise=CCMP 583 group=GTK_NOT_USED 584 eap=WFA-UNAUTH-TLS 585 identity="anonymous (a] example.com" 586 ca_cert="osu-ca.pem" 587 ocsp=2 588 } 589 590 591 Hotspot 2.0 connection with external network selection 592 ------------------------------------------------------ 593 594 When an component controlling wpa_supplicant takes care of Interworking 595 network selection, following configuration and network profile 596 parameters can be used to configure a temporary network profile for a 597 Hotspot 2.0 connection (e.g., with SET, ADD_NETWORK, SET_NETWORK, and 598 SELECT_NETWORK control interface commands): 599 600 interworking=1 601 hs20=1 602 auto_interworking=0 603 604 network={ 605 ssid="test-hs20" 606 proto=RSN 607 key_mgmt=WPA-EAP 608 pairwise=CCMP 609 anonymous_identity="anonymous (a] example.com" 610 identity="hs20-test (a] example.com" 611 password="password" 612 ca_cert="ca.pem" 613 eap=TTLS 614 phase2="auth=MSCHAPV2" 615 update_identifier=54321 616 #ocsp=2 617 } 618 619 620 These parameters are set based on the PPS MO credential and/or NAI Realm 621 list ANQP-element: 622 623 anonymous_identity: Credential/UsernamePassword/Username with username part 624 replaced with "anonymous" 625 identity: Credential/UsernamePassword/Username 626 password: Credential/UsernamePassword/Password 627 update_identifier: PPS/UpdateIdentifier 628 ca_cert: from the downloaded trust root based on PPS information 629 eap: Credential/UsernamePassword/EAPMethod or NAI Realm list 630 phase2: Credential/UsernamePassword/EAPMethod or NAI Realm list 631 ocsp: Credential/CheckAAAServerCertStatus 632
