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