1 wpa_supplicant and Hotspot 2.0
2 ==============================
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.
10 Introduction to Wi-Fi Hotspot 2.0
11 ---------------------------------
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:
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
19 The Hotspot 2.0 specification is also available from WFA:
20 https://www.wi-fi.org/knowledge-center/published-specifications
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
27 wpa_supplicant network selection
28 --------------------------------
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.
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.
52 wpa_supplicant configuration
53 ----------------------------
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:
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.
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.
79 # Parameters for controlling scanning
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
85 #hessid=00:11:22:33:44:55
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
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
102 Credentials can be pre-configured for automatic network selection:
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.
112 # temporary: Whether this credential is temporary and not to be saved
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.
122 # pcsc: Use PC/SC and SIM/USIM card
124 # realm: Home Realm for Interworking
126 # username: Username for Interworking network selection
128 # password: Password for Interworking network selection
130 # ca_cert: CA certificate for Interworking network selection
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.
138 # Alternatively, a named configuration blob can be used by setting
139 # this to blob://blob_name.
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
148 # Windows certificate store can be used by leaving client_cert out and
149 # configuring private_key in one of the following formats:
151 # cert://substring_to_match
153 # hash://certificate_thumbprint_in_hex
155 # For example: private_key="hash://63093aa9c47f56ae88334c7b65a4"
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.
161 # Alternatively, a named configuration blob can be used by setting
162 # this to blob://blob_name.
164 # private_key_passwd: Password for private key file
166 # imsi: IMSI in <MCC> | <MNC> | '-' | <MSIN> format
168 # milenage: Milenage parameters for SIM/USIM simulator in <Ki>:<OPc>:<SQN>
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.
182 # For example, domain_suffix_match=example.com would match
183 # test.example.com but would not match test-example.com.
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
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.
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).
205 # phase1: Pre-configure Phase 1 (outer authentication) parameters
206 # This optional field is used with like the 'eap' parameter.
208 # phase2: Pre-configure Phase 2 (inner authentication) parameters
209 # This optional field is used with like the 'eap' parameter.
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
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)
223 # update_identifier: PPS MO ID
224 # (Hotspot 2.0 PerProviderSubscription/UpdateIdentifier)
229 # realm="example.com"
230 # username="user@example.com"
231 # password="password"
232 # ca_cert="/etc/wpa_supplicant/ca.pem"
233 # domain="example.com"
234 # domain_suffix_match="example.com"
238 # imsi="310026-000000000"
239 # milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82"
243 # realm="example.com"
245 # password="password"
246 # ca_cert="/etc/wpa_supplicant/ca.pem"
247 # domain="example.com"
248 # roaming_consortium=223344
250 # phase2="auth=MSCHAPV2"
257 wpa_supplicant provides a control interface that can be used from
258 external programs to manage various operations. The included command
259 line tool, wpa_cli, can be used for manual testing with this interface.
261 Following wpa_cli interactive mode commands show some examples of manual
262 operations related to Hotspot 2.0:
264 Remove configured networks and credentials:
272 Add a username/password credential:
276 > set_cred 0 realm "mail.example.com"
278 > set_cred 0 username "username"
280 > set_cred 0 password "password"
282 > set_cred 0 priority 1
284 > set_cred 0 temporary 1
287 Add a SIM credential using a simulated SIM/USIM card for testing:
291 > set_cred 1 imsi "23456-0000000000"
293 > set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123"
295 > set_cred 1 priority 1
298 Note: the return value of add_cred is used as the first argument to
299 the following set_cred commands.
301 Add a SIM credential using a external SIM/USIM processing:
307 > set_cred 1 imsi "23456-0000000000"
313 Add a WPA2-Enterprise network:
317 > set_network 0 key_mgmt WPA-EAP
319 > set_network 0 ssid "enterprise"
321 > set_network 0 eap TTLS
323 > set_network 0 anonymous_identity "anonymous"
325 > set_network 0 identity "user"
327 > set_network 0 password "password"
329 > set_network 0 priority 0
331 > enable_network 0 no-connect
339 > set_network 3 key_mgmt NONE
341 > set_network 3 ssid "coffee-shop"
346 Note: the return value of add_network is used as the first argument to
347 the following set_network commands.
349 The preferred credentials/networks can be indicated with the priority
350 parameter (1 is higher priority than 0).
353 Interworking network selection can be started with interworking_select
354 command. This instructs wpa_supplicant to run a network scan and iterate
355 through the discovered APs to request ANQP information from the APs that
356 advertise support for Interworking/Hotspot 2.0:
358 > interworking_select
360 <3>Starting ANQP fetch for 02:00:00:00:01:00
361 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
362 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
363 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
364 <3>ANQP fetch completed
365 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
368 INTERWORKING-AP event messages indicate the APs that support network
369 selection and for which there is a matching
370 credential. interworking_connect command can be used to select a network
374 > interworking_connect 02:00:00:00:01:00
376 <3>CTRL-EVENT-SCAN-RESULTS
377 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
378 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
379 <3>Associated with 02:00:00:00:01:00
380 <3>CTRL-EVENT-EAP-STARTED EAP authentication started
381 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
382 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
383 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
384 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
385 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=]
388 wpa_supplicant creates a temporary network block for the selected
389 network based on the configured credential and ANQP information from the
393 network id / ssid / bssid / flags
394 0 Example Network any [CURRENT]
395 > get_network 0 key_mgmt
401 Alternatively to using an external program to select the network,
402 "interworking_select auto" command can be used to request wpa_supplicant
403 to select which network to use based on configured priorities:
408 <3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1
409 > interworking_select auto
411 <3>Starting ANQP fetch for 02:00:00:00:01:00
412 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
413 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
414 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
415 <3>ANQP fetch completed
416 <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
417 <3>CTRL-EVENT-SCAN-RESULTS
418 <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
419 <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
420 <3>Associated with 02:00:00:00:01:00
421 <3>CTRL-EVENT-EAP-STARTED EAP authentication started
422 <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
423 <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
424 <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
425 <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
426 <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=]
429 The connection status can be shown with the status command:
432 bssid=02:00:00:00:01:00
436 pairwise_cipher=CCMP <--- link layer security indication
438 key_mgmt=WPA2/IEEE 802.1X/EAP
440 p2p_device_address=02:00:00:00:00:00
441 address=02:00:00:00:00:00
442 hs20=1 <--- HS 2.0 indication
443 Supplicant PAE state=AUTHENTICATED
444 suppPortStatus=Authorized
446 selectedMethod=21 (EAP-TTLS)
447 EAP TLS cipher=AES-128-SHA
448 EAP-TTLSv0 Phase2 method=PAP
452 bssid=02:00:00:00:02:00
460 p2p_device_address=02:00:00:00:00:00
461 address=02:00:00:00:00:00
464 Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status
465 command output. Link layer security is indicated with the
466 pairwise_cipher (CCMP = secure, NONE = no encryption used).
469 Also the scan results include the Hotspot 2.0 indication:
472 bssid / frequency / signal level / flags / ssid
473 02:00:00:00:01:00 2412 -30 [WPA2-EAP-CCMP][ESS][HS20] Example Network
476 ANQP information for the BSS can be fetched using the BSS command:
478 > bss 02:00:00:00:01:00
480 bssid=02:00:00:00:01:00
489 ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000
490 flags=[WPA2-EAP-CCMP][ESS][HS20]
492 anqp_roaming_consortium=031122330510203040500601020304050603fedcba
495 ANQP queries can also be requested with the anqp_get and hs20_anqp_get
498 > anqp_get 02:00:00:00:01:00 261
500 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
501 > hs20_anqp_get 02:00:00:00:01:00 2
503 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
505 In addition, fetch_anqp command can be used to request similar set of
506 ANQP queries to be done as is run as part of interworking_select:
510 <3>CTRL-EVENT-SCAN-RESULTS
513 <3>Starting ANQP fetch for 02:00:00:00:01:00
514 <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
515 <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
516 <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
517 <3>ANQP fetch completed