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 # 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 # for example:
 194 #
 195 #cred={
 196 #       realm="example.com"
 197 #       username="user@example.com"
 198 #       password="password"
 199 #       ca_cert="/etc/wpa_supplicant/ca.pem"
 200 #       domain="example.com"
 201 #}
 202 #
 203 #cred={
 204 #       imsi="310026-000000000"
 205 #       milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82"
 206 #}
 207 #
 208 #cred={
 209 #       realm="example.com"
 210 #       username="user"
 211 #       password="password"
 212 #       ca_cert="/etc/wpa_supplicant/ca.pem"
 213 #       domain="example.com"
 214 #       roaming_consortium=223344
 215 #       eap=TTLS
 216 #       phase2="auth=MSCHAPV2"
 217 #}
 218
 219
 220 Control interface
 221 -----------------
 222
 223 wpa_supplicant provides a control interface that can be used from
 224 external programs to manage various operations. The included command
 225 line tool, wpa_cli, can be used for manual testing with this interface.
 226
 227 Following wpa_cli interactive mode commands show some examples of manual
 228 operations related to Hotspot 2.0:
 229
 230 Remove configured networks and credentials:
 231
 232 > remove_network all
 233 OK
 234 > remove_cred all
 235 OK
 236
 237
 238 Add a username/password credential:
 239
 240 > add_cred
 241 0
 242 > set_cred 0 realm "mail.example.com"
 243 OK
 244 > set_cred 0 username "username"
 245 OK
 246 > set_cred 0 password "password"
 247 OK
 248 > set_cred 0 priority 1
 249 OK
 250
 251 Add a SIM credential using a simulated SIM/USIM card for testing:
 252
 253 > add_cred
 254 1
 255 > set_cred 1 imsi "23456-0000000000"
 256 OK
 257 > set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123"
 258 OK
 259 > set_cred 1 priority 1
 260 OK
 261
 262 Note: the return value of add_cred is used as the first argument to
 263 the following set_cred commands.
 264
 265
 266 Add a WPA2-Enterprise network:
 267
 268 > add_network
 269 0
 270 > set_network 0 key_mgmt WPA-EAP
 271 OK
 272 > set_network 0 ssid "enterprise"
 273 OK
 274 > set_network 0 eap TTLS
 275 OK
 276 > set_network 0 anonymous_identity "anonymous"
 277 OK
 278 > set_network 0 identity "user"
 279 OK
 280 > set_network 0 password "password"
 281 OK
 282 > set_network 0 priority 0
 283 OK
 284 > enable_network 0 no-connect
 285 OK
 286
 287
 288 Add an open network:
 289
 290 > add_network
 291 3
 292 > set_network 3 key_mgmt NONE
 293 OK
 294 > set_network 3 ssid "coffee-shop"
 295 OK
 296 > select_network 3
 297 OK
 298
 299 Note: the return value of add_network is used as the first argument to
 300 the following set_network commands.
 301
 302 The preferred credentials/networks can be indicated with the priority
 303 parameter (1 is higher priority than 0).
 304
 305
 306 Interworking network selection can be started with interworking_select
 307 command. This instructs wpa_supplicant to run a network scan and iterate
 308 through the discovered APs to request ANQP information from the APs that
 309 advertise support for Interworking/Hotspot 2.0:
 310
 311 > interworking_select
 312 OK
 313 <3>Starting ANQP fetch for 02:00:00:00:01:00
 314 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
 315 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
 316 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
 317 <3>ANQP fetch completed
 318 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
 319
 320
 321 INTERWORKING-AP event messages indicate the APs that support network
 322 selection and for which there is a matching
 323 credential. interworking_connect command can be used to select a network
 324 to connect with:
 325
 326
 327 > interworking_connect 02:00:00:00:01:00
 328 OK
 329 <3>CTRL-EVENT-SCAN-RESULTS
 330 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
 331 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
 332 <3>Associated with 02:00:00:00:01:00
 333 <3>CTRL-EVENT-EAP-STARTED EAP authentication started
 334 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
 335 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
 336 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
 337 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
 338 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=]
 339
 340
 341 wpa_supplicant creates a temporary network block for the selected
 342 network based on the configured credential and ANQP information from the
 343 AP:
 344
 345 > list_networks
 346 network id / ssid / bssid / flags
 347 0       Example Network any     [CURRENT]
 348 > get_network 0 key_mgmt
 349 WPA-EAP
 350 > get_network 0 eap
 351 TTLS
 352
 353
 354 Alternatively to using an external program to select the network,
 355 "interworking_select auto" command can be used to request wpa_supplicant
 356 to select which network to use based on configured priorities:
 357
 358
 359 > remove_network all
 360 OK
 361 <3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1
 362 > interworking_select auto
 363 OK
 364 <3>Starting ANQP fetch for 02:00:00:00:01:00
 365 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
 366 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
 367 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
 368 <3>ANQP fetch completed
 369 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
 370 <3>CTRL-EVENT-SCAN-RESULTS
 371 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
 372 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
 373 <3>Associated with 02:00:00:00:01:00
 374 <3>CTRL-EVENT-EAP-STARTED EAP authentication started
 375 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
 376 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
 377 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
 378 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
 379 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=]
 380
 381
 382 The connection status can be shown with the status command:
 383
 384 > status
 385 bssid=02:00:00:00:01:00
 386 ssid=Example Network
 387 id=0
 388 mode=station
 389 pairwise_cipher=CCMP       <--- link layer security indication
 390 group_cipher=CCMP
 391 key_mgmt=WPA2/IEEE 802.1X/EAP
 392 wpa_state=COMPLETED
 393 p2p_device_address=02:00:00:00:00:00
 394 address=02:00:00:00:00:00
 395 hs20=1      <--- HS 2.0 indication
 396 Supplicant PAE state=AUTHENTICATED
 397 suppPortStatus=Authorized
 398 EAP state=SUCCESS
 399 selectedMethod=21 (EAP-TTLS)
 400 EAP TLS cipher=AES-128-SHA
 401 EAP-TTLSv0 Phase2 method=PAP
 402
 403
 404 > status
 405 bssid=02:00:00:00:02:00
 406 ssid=coffee-shop
 407 id=3
 408 mode=station
 409 pairwise_cipher=NONE
 410 group_cipher=NONE
 411 key_mgmt=NONE
 412 wpa_state=COMPLETED
 413 p2p_device_address=02:00:00:00:00:00
 414 address=02:00:00:00:00:00
 415
 416
 417 Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status
 418 command output. Link layer security is indicated with the
 419 pairwise_cipher (CCMP = secure, NONE = no encryption used).
 420
 421
 422 Also the scan results include the Hotspot 2.0 indication:
 423
 424 > scan_results
 425 bssid / frequency / signal level / flags / ssid
 426 02:00:00:00:01:00       2412    -30     [WPA2-EAP-CCMP][ESS][HS20]      Example Network
 427
 428
 429 ANQP information for the BSS can be fetched using the BSS command:
 430
 431 > bss 02:00:00:00:01:00
 432 id=1
 433 bssid=02:00:00:00:01:00
 434 freq=2412
 435 beacon_int=100
 436 capabilities=0x0411
 437 qual=0
 438 noise=-92
 439 level=-30
 440 tsf=1345573286517276
 441 age=105
 442 ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000
 443 flags=[WPA2-EAP-CCMP][ESS][HS20]
 444 ssid=Example Network
 445 anqp_roaming_consortium=031122330510203040500601020304050603fedcba
 446
 447
 448 ANQP queries can also be requested with the anqp_get and hs20_anqp_get
 449 commands:
 450
 451 > anqp_get 02:00:00:00:01:00 261
 452 OK
 453 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
 454 > hs20_anqp_get 02:00:00:00:01:00 2
 455 OK
 456 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
 457
 458 In addition, fetch_anqp command can be used to request similar set of
 459 ANQP queries to be done as is run as part of interworking_select:
 460
 461 > scan
 462 OK
 463 <3>CTRL-EVENT-SCAN-RESULTS
 464 > fetch_anqp
 465 OK
 466 <3>Starting ANQP fetch for 02:00:00:00:01:00
 467 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
 468 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
 469 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
 470 <3>ANQP fetch completed