wpa_supplicant/README-HS20

   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 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 # 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 #       provisionined 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 # for example:
 274 #
 275 #cred={
 276 #       realm="example.com"
 277 #       username="user@example.com"
 278 #       password="password"
 279 #       ca_cert="/etc/wpa_supplicant/ca.pem"
 280 #       domain="example.com"
 281 #       domain_suffix_match="example.com"
 282 #}
 283 #
 284 #cred={
 285 #       imsi="310026-000000000"
 286 #       milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82"
 287 #}
 288 #
 289 #cred={
 290 #       realm="example.com"
 291 #       username="user"
 292 #       password="password"
 293 #       ca_cert="/etc/wpa_supplicant/ca.pem"
 294 #       domain="example.com"
 295 #       roaming_consortium=223344
 296 #       eap=TTLS
 297 #       phase2="auth=MSCHAPV2"
 298 #}
 299
 300
 301 Control interface
 302 -----------------
 303
 304 wpa_supplicant provides a control interface that can be used from
 305 external programs to manage various operations. The included command
 306 line tool, wpa_cli, can be used for manual testing with this interface.
 307
 308 Following wpa_cli interactive mode commands show some examples of manual
 309 operations related to Hotspot 2.0:
 310
 311 Remove configured networks and credentials:
 312
 313 > remove_network all
 314 OK
 315 > remove_cred all
 316 OK
 317
 318
 319 Add a username/password credential:
 320
 321 > add_cred
 322 0
 323 > set_cred 0 realm "mail.example.com"
 324 OK
 325 > set_cred 0 username "username"
 326 OK
 327 > set_cred 0 password "password"
 328 OK
 329 > set_cred 0 priority 1
 330 OK
 331 > set_cred 0 temporary 1
 332 OK
 333
 334 Add a SIM credential using a simulated SIM/USIM card for testing:
 335
 336 > add_cred
 337 1
 338 > set_cred 1 imsi "23456-0000000000"
 339 OK
 340 > set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123"
 341 OK
 342 > set_cred 1 priority 1
 343 OK
 344
 345 Note: the return value of add_cred is used as the first argument to
 346 the following set_cred commands.
 347
 348 Add a SIM credential using a external SIM/USIM processing:
 349
 350 > set external_sim 1
 351 OK
 352 > add_cred
 353 1
 354 > set_cred 1 imsi "23456-0000000000"
 355 OK
 356 > set_cred 1 eap SIM
 357 OK
 358
 359
 360 Add a WPA2-Enterprise network:
 361
 362 > add_network
 363 0
 364 > set_network 0 key_mgmt WPA-EAP
 365 OK
 366 > set_network 0 ssid "enterprise"
 367 OK
 368 > set_network 0 eap TTLS
 369 OK
 370 > set_network 0 anonymous_identity "anonymous"
 371 OK
 372 > set_network 0 identity "user"
 373 OK
 374 > set_network 0 password "password"
 375 OK
 376 > set_network 0 priority 0
 377 OK
 378 > enable_network 0 no-connect
 379 OK
 380
 381
 382 Add an open network:
 383
 384 > add_network
 385 3
 386 > set_network 3 key_mgmt NONE
 387 OK
 388 > set_network 3 ssid "coffee-shop"
 389 OK
 390 > select_network 3
 391 OK
 392
 393 Note: the return value of add_network is used as the first argument to
 394 the following set_network commands.
 395
 396 The preferred credentials/networks can be indicated with the priority
 397 parameter (1 is higher priority than 0).
 398
 399
 400 Interworking network selection can be started with interworking_select
 401 command. This instructs wpa_supplicant to run a network scan and iterate
 402 through the discovered APs to request ANQP information from the APs that
 403 advertise support for Interworking/Hotspot 2.0:
 404
 405 > interworking_select
 406 OK
 407 <3>Starting ANQP fetch for 02:00:00:00:01:00
 408 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
 409 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
 410 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
 411 <3>ANQP fetch completed
 412 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
 413
 414
 415 INTERWORKING-AP event messages indicate the APs that support network
 416 selection and for which there is a matching
 417 credential. interworking_connect command can be used to select a network
 418 to connect with:
 419
 420
 421 > interworking_connect 02:00:00:00:01:00
 422 OK
 423 <3>CTRL-EVENT-SCAN-RESULTS
 424 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
 425 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
 426 <3>Associated with 02:00:00:00:01:00
 427 <3>CTRL-EVENT-EAP-STARTED EAP authentication started
 428 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
 429 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
 430 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
 431 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
 432 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=]
 433
 434
 435 wpa_supplicant creates a temporary network block for the selected
 436 network based on the configured credential and ANQP information from the
 437 AP:
 438
 439 > list_networks
 440 network id / ssid / bssid / flags
 441 0       Example Network any     [CURRENT]
 442 > get_network 0 key_mgmt
 443 WPA-EAP
 444 > get_network 0 eap
 445 TTLS
 446
 447
 448 Alternatively to using an external program to select the network,
 449 "interworking_select auto" command can be used to request wpa_supplicant
 450 to select which network to use based on configured priorities:
 451
 452
 453 > remove_network all
 454 OK
 455 <3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1
 456 > interworking_select auto
 457 OK
 458 <3>Starting ANQP fetch for 02:00:00:00:01:00
 459 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
 460 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
 461 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
 462 <3>ANQP fetch completed
 463 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
 464 <3>CTRL-EVENT-SCAN-RESULTS
 465 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
 466 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
 467 <3>Associated with 02:00:00:00:01:00
 468 <3>CTRL-EVENT-EAP-STARTED EAP authentication started
 469 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
 470 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
 471 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
 472 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
 473 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=]
 474
 475
 476 The connection status can be shown with the status command:
 477
 478 > status
 479 bssid=02:00:00:00:01:00
 480 ssid=Example Network
 481 id=0
 482 mode=station
 483 pairwise_cipher=CCMP       <--- link layer security indication
 484 group_cipher=CCMP
 485 key_mgmt=WPA2/IEEE 802.1X/EAP
 486 wpa_state=COMPLETED
 487 p2p_device_address=02:00:00:00:00:00
 488 address=02:00:00:00:00:00
 489 hs20=1      <--- HS 2.0 indication
 490 Supplicant PAE state=AUTHENTICATED
 491 suppPortStatus=Authorized
 492 EAP state=SUCCESS
 493 selectedMethod=21 (EAP-TTLS)
 494 EAP TLS cipher=AES-128-SHA
 495 EAP-TTLSv0 Phase2 method=PAP
 496
 497
 498 > status
 499 bssid=02:00:00:00:02:00
 500 ssid=coffee-shop
 501 id=3
 502 mode=station
 503 pairwise_cipher=NONE
 504 group_cipher=NONE
 505 key_mgmt=NONE
 506 wpa_state=COMPLETED
 507 p2p_device_address=02:00:00:00:00:00
 508 address=02:00:00:00:00:00
 509
 510
 511 Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status
 512 command output. Link layer security is indicated with the
 513 pairwise_cipher (CCMP = secure, NONE = no encryption used).
 514
 515
 516 Also the scan results include the Hotspot 2.0 indication:
 517
 518 > scan_results
 519 bssid / frequency / signal level / flags / ssid
 520 02:00:00:00:01:00       2412    -30     [WPA2-EAP-CCMP][ESS][HS20]      Example Network
 521
 522
 523 ANQP information for the BSS can be fetched using the BSS command:
 524
 525 > bss 02:00:00:00:01:00
 526 id=1
 527 bssid=02:00:00:00:01:00
 528 freq=2412
 529 beacon_int=100
 530 capabilities=0x0411
 531 qual=0
 532 noise=-92
 533 level=-30
 534 tsf=1345573286517276
 535 age=105
 536 ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000
 537 flags=[WPA2-EAP-CCMP][ESS][HS20]
 538 ssid=Example Network
 539 anqp_roaming_consortium=031122330510203040500601020304050603fedcba
 540
 541
 542 ANQP queries can also be requested with the anqp_get and hs20_anqp_get
 543 commands:
 544
 545 > anqp_get 02:00:00:00:01:00 261
 546 OK
 547 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
 548 > hs20_anqp_get 02:00:00:00:01:00 2
 549 OK
 550 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
 551
 552 In addition, fetch_anqp command can be used to request similar set of
 553 ANQP queries to be done as is run as part of interworking_select:
 554
 555 > scan
 556 OK
 557 <3>CTRL-EVENT-SCAN-RESULTS
 558 > fetch_anqp
 559 OK
 560 <3>Starting ANQP fetch for 02:00:00:00:01:00
 561 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
 562 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
 563 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
 564 <3>ANQP fetch completed