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 # priority: Priority group 113 # By default, all networks and credentials get the same priority group 114 # (0). This field can be used to give higher priority for credentials 115 # (and similarly in struct wpa_ssid for network blocks) to change the 116 # Interworking automatic networking selection behavior. The matching 117 # network (based on either an enabled network block or a credential) 118 # with the highest priority value will be selected. 119 # 120 # pcsc: Use PC/SC and SIM/USIM card 121 # 122 # realm: Home Realm for Interworking 123 # 124 # username: Username for Interworking network selection 125 # 126 # password: Password for Interworking network selection 127 # 128 # ca_cert: CA certificate for Interworking network selection 129 # 130 # client_cert: File path to client certificate file (PEM/DER) 131 # This field is used with Interworking networking selection for a case 132 # where client certificate/private key is used for authentication 133 # (EAP-TLS). Full path to the file should be used since working 134 # directory may change when wpa_supplicant is run in the background. 135 # 136 # Alternatively, a named configuration blob can be used by setting 137 # this to blob://blob_name. 138 # 139 # private_key: File path to client private key file (PEM/DER/PFX) 140 # When PKCS#12/PFX file (.p12/.pfx) is used, client_cert should be 141 # commented out. Both the private key and certificate will be read 142 # from the PKCS#12 file in this case. Full path to the file should be 143 # used since working directory may change when wpa_supplicant is run 144 # in the background. 145 # 146 # Windows certificate store can be used by leaving client_cert out and 147 # configuring private_key in one of the following formats: 148 # 149 # cert://substring_to_match 150 # 151 # hash://certificate_thumbprint_in_hex 152 # 153 # For example: private_key="hash://63093aa9c47f56ae88334c7b65a4" 154 # 155 # Note that when running wpa_supplicant as an application, the user 156 # certificate store (My user account) is used, whereas computer store 157 # (Computer account) is used when running wpasvc as a service. 158 # 159 # Alternatively, a named configuration blob can be used by setting 160 # this to blob://blob_name. 161 # 162 # private_key_passwd: Password for private key file 163 # 164 # imsi: IMSI in <MCC> | <MNC> | '-' | <MSIN> format 165 # 166 # milenage: Milenage parameters for SIM/USIM simulator in <Ki>:<OPc>:<SQN> 167 # format 168 # 169 # domain: Home service provider FQDN 170 # This is used to compare against the Domain Name List to figure out 171 # whether the AP is operated by the Home SP. 172 # 173 # roaming_consortium: Roaming Consortium OI 174 # If roaming_consortium_len is non-zero, this field contains the 175 # Roaming Consortium OI that can be used to determine which access 176 # points support authentication with this credential. This is an 177 # alternative to the use of the realm parameter. When using Roaming 178 # Consortium to match the network, the EAP parameters need to be 179 # pre-configured with the credential since the NAI Realm information 180 # may not be available or fetched. 181 # 182 # eap: Pre-configured EAP method 183 # This optional field can be used to specify which EAP method will be 184 # used with this credential. If not set, the EAP method is selected 185 # automatically based on ANQP information (e.g., NAI Realm). 186 # 187 # phase1: Pre-configure Phase 1 (outer authentication) parameters 188 # This optional field is used with like the 'eap' parameter. 189 # 190 # phase2: Pre-configure Phase 2 (inner authentication) parameters 191 # This optional field is used with like the 'eap' parameter. 192 # 193 # excluded_ssid: Excluded SSID 194 # This optional field can be used to excluded specific SSID(s) from 195 # matching with the network. Multiple entries can be used to specify more 196 # than one SSID. 197 # 198 # for example: 199 # 200 #cred={ 201 # realm="example.com" 202 # username="user (a] example.com" 203 # password="password" 204 # ca_cert="/etc/wpa_supplicant/ca.pem" 205 # domain="example.com" 206 #} 207 # 208 #cred={ 209 # imsi="310026-000000000" 210 # milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82" 211 #} 212 # 213 #cred={ 214 # realm="example.com" 215 # username="user" 216 # password="password" 217 # ca_cert="/etc/wpa_supplicant/ca.pem" 218 # domain="example.com" 219 # roaming_consortium=223344 220 # eap=TTLS 221 # phase2="auth=MSCHAPV2" 222 #} 223 224 225 Control interface 226 ----------------- 227 228 wpa_supplicant provides a control interface that can be used from 229 external programs to manage various operations. The included command 230 line tool, wpa_cli, can be used for manual testing with this interface. 231 232 Following wpa_cli interactive mode commands show some examples of manual 233 operations related to Hotspot 2.0: 234 235 Remove configured networks and credentials: 236 237 > remove_network all 238 OK 239 > remove_cred all 240 OK 241 242 243 Add a username/password credential: 244 245 > add_cred 246 0 247 > set_cred 0 realm "mail.example.com" 248 OK 249 > set_cred 0 username "username" 250 OK 251 > set_cred 0 password "password" 252 OK 253 > set_cred 0 priority 1 254 OK 255 256 Add a SIM credential using a simulated SIM/USIM card for testing: 257 258 > add_cred 259 1 260 > set_cred 1 imsi "23456-0000000000" 261 OK 262 > set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123" 263 OK 264 > set_cred 1 priority 1 265 OK 266 267 Note: the return value of add_cred is used as the first argument to 268 the following set_cred commands. 269 270 271 Add a WPA2-Enterprise network: 272 273 > add_network 274 0 275 > set_network 0 key_mgmt WPA-EAP 276 OK 277 > set_network 0 ssid "enterprise" 278 OK 279 > set_network 0 eap TTLS 280 OK 281 > set_network 0 anonymous_identity "anonymous" 282 OK 283 > set_network 0 identity "user" 284 OK 285 > set_network 0 password "password" 286 OK 287 > set_network 0 priority 0 288 OK 289 > enable_network 0 no-connect 290 OK 291 292 293 Add an open network: 294 295 > add_network 296 3 297 > set_network 3 key_mgmt NONE 298 OK 299 > set_network 3 ssid "coffee-shop" 300 OK 301 > select_network 3 302 OK 303 304 Note: the return value of add_network is used as the first argument to 305 the following set_network commands. 306 307 The preferred credentials/networks can be indicated with the priority 308 parameter (1 is higher priority than 0). 309 310 311 Interworking network selection can be started with interworking_select 312 command. This instructs wpa_supplicant to run a network scan and iterate 313 through the discovered APs to request ANQP information from the APs that 314 advertise support for Interworking/Hotspot 2.0: 315 316 > interworking_select 317 OK 318 <3>Starting ANQP fetch for 02:00:00:00:01:00 319 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 320 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 321 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 322 <3>ANQP fetch completed 323 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 324 325 326 INTERWORKING-AP event messages indicate the APs that support network 327 selection and for which there is a matching 328 credential. interworking_connect command can be used to select a network 329 to connect with: 330 331 332 > interworking_connect 02:00:00:00:01:00 333 OK 334 <3>CTRL-EVENT-SCAN-RESULTS 335 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 336 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 337 <3>Associated with 02:00:00:00:01:00 338 <3>CTRL-EVENT-EAP-STARTED EAP authentication started 339 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 340 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 341 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 342 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 343 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=] 344 345 346 wpa_supplicant creates a temporary network block for the selected 347 network based on the configured credential and ANQP information from the 348 AP: 349 350 > list_networks 351 network id / ssid / bssid / flags 352 0 Example Network any [CURRENT] 353 > get_network 0 key_mgmt 354 WPA-EAP 355 > get_network 0 eap 356 TTLS 357 358 359 Alternatively to using an external program to select the network, 360 "interworking_select auto" command can be used to request wpa_supplicant 361 to select which network to use based on configured priorities: 362 363 364 > remove_network all 365 OK 366 <3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1 367 > interworking_select auto 368 OK 369 <3>Starting ANQP fetch for 02:00:00:00:01:00 370 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 371 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 372 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 373 <3>ANQP fetch completed 374 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown 375 <3>CTRL-EVENT-SCAN-RESULTS 376 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 377 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz) 378 <3>Associated with 02:00:00:00:01:00 379 <3>CTRL-EVENT-EAP-STARTED EAP authentication started 380 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21 381 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected 382 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 383 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP] 384 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=] 385 386 387 The connection status can be shown with the status command: 388 389 > status 390 bssid=02:00:00:00:01:00 391 ssid=Example Network 392 id=0 393 mode=station 394 pairwise_cipher=CCMP <--- link layer security indication 395 group_cipher=CCMP 396 key_mgmt=WPA2/IEEE 802.1X/EAP 397 wpa_state=COMPLETED 398 p2p_device_address=02:00:00:00:00:00 399 address=02:00:00:00:00:00 400 hs20=1 <--- HS 2.0 indication 401 Supplicant PAE state=AUTHENTICATED 402 suppPortStatus=Authorized 403 EAP state=SUCCESS 404 selectedMethod=21 (EAP-TTLS) 405 EAP TLS cipher=AES-128-SHA 406 EAP-TTLSv0 Phase2 method=PAP 407 408 409 > status 410 bssid=02:00:00:00:02:00 411 ssid=coffee-shop 412 id=3 413 mode=station 414 pairwise_cipher=NONE 415 group_cipher=NONE 416 key_mgmt=NONE 417 wpa_state=COMPLETED 418 p2p_device_address=02:00:00:00:00:00 419 address=02:00:00:00:00:00 420 421 422 Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status 423 command output. Link layer security is indicated with the 424 pairwise_cipher (CCMP = secure, NONE = no encryption used). 425 426 427 Also the scan results include the Hotspot 2.0 indication: 428 429 > scan_results 430 bssid / frequency / signal level / flags / ssid 431 02:00:00:00:01:00 2412 -30 [WPA2-EAP-CCMP][ESS][HS20] Example Network 432 433 434 ANQP information for the BSS can be fetched using the BSS command: 435 436 > bss 02:00:00:00:01:00 437 id=1 438 bssid=02:00:00:00:01:00 439 freq=2412 440 beacon_int=100 441 capabilities=0x0411 442 qual=0 443 noise=-92 444 level=-30 445 tsf=1345573286517276 446 age=105 447 ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000 448 flags=[WPA2-EAP-CCMP][ESS][HS20] 449 ssid=Example Network 450 anqp_roaming_consortium=031122330510203040500601020304050603fedcba 451 452 453 ANQP queries can also be requested with the anqp_get and hs20_anqp_get 454 commands: 455 456 > anqp_get 02:00:00:00:01:00 261 457 OK 458 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 459 > hs20_anqp_get 02:00:00:00:01:00 2 460 OK 461 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 462 463 In addition, fetch_anqp command can be used to request similar set of 464 ANQP queries to be done as is run as part of interworking_select: 465 466 > scan 467 OK 468 <3>CTRL-EVENT-SCAN-RESULTS 469 > fetch_anqp 470 OK 471 <3>Starting ANQP fetch for 02:00:00:00:01:00 472 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list 473 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list 474 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List 475 <3>ANQP fetch completed 476
