1wpa_supplicant and Hotspot 2.0
2==============================
3
4This document describe how the IEEE 802.11u Interworking and Wi-Fi
5Hotspot 2.0 (Release 1) implementation in wpa_supplicant can be
6configured and how an external component on the client e.g., management
7GUI or Wi-Fi framework) is used to manage this functionality.
8
9
10Introduction to Wi-Fi Hotspot 2.0
11---------------------------------
12
13Hotspot 2.0 is the name of the Wi-Fi Alliance specification that is used
14in the Wi-Fi CERTIFIED Passpoint<TM> program. More information about
15this is available in this white paper:
16
17http://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
19The Hotspot 2.0 specification is also available from WFA:
20https://www.wi-fi.org/knowledge-center/published-specifications
21
22The core Interworking functionality (network selection, GAS/ANQP) were
23standardized in IEEE Std 802.11u-2011 which is now part of the IEEE Std
24802.11-2012.
25
26
27wpa_supplicant network selection
28--------------------------------
29
30Interworking support added option for configuring credentials that can
31work with multiple networks as an alternative to configuration of
32network blocks (e.g., per-SSID parameters). When requested to perform
33network selection, wpa_supplicant picks the highest priority enabled
34network block or credential. If a credential is picked (based on ANQP
35information from APs), a temporary network block is created
36automatically for the matching network. This temporary network block is
37used similarly to the network blocks that can be configured by the user,
38but it is not stored into the configuration file and is meant to be used
39only for temporary period of time since a new one can be created
40whenever needed based on ANQP information and the credential.
41
42By default, wpa_supplicant is not using automatic network selection
43unless requested explicitly with the interworking_select command. This
44can be changed with the auto_interworking=1 parameter to perform network
45selection automatically whenever trying to find a network for connection
46and none of the enabled network blocks match with the scan results. This
47case works similarly to "interworking_select auto", i.e., wpa_supplicant
48will internally determine which network or credential is going to be
49used based on configured priorities, scan results, and ANQP information.
50
51
52wpa_supplicant configuration
53----------------------------
54
55Interworking and Hotspot 2.0 functionality are optional components that
56need to be enabled in the wpa_supplicant build configuration
57(.config). This is done by adding following parameters into that file:
58
59CONFIG_INTERWORKING=y
60CONFIG_HS20=y
61
62It should be noted that this functionality requires a driver that
63supports GAS/ANQP operations. This uses the same design as P2P, i.e.,
64Action frame processing and building in user space within
65wpa_supplicant. The Linux nl80211 driver interface provides the needed
66functionality for this.
67
68
69There are number of run-time configuration parameters (e.g., in
70wpa_supplicant.conf when using the configuration file) that can be used
71to control Hotspot 2.0 operations.
72
73# Enable Interworking
74interworking=1
75
76# Enable Hotspot 2.0
77hs20=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
102Credentials 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 SubjectName 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#	provisioned 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# sim_num: Identifier for which SIM to use in multi-SIM devices
274#
275# for example:
276#
277#cred={
278#	realm="example.com"
279#	username="user@example.com"
280#	password="password"
281#	ca_cert="/etc/wpa_supplicant/ca.pem"
282#	domain="example.com"
283#	domain_suffix_match="example.com"
284#}
285#
286#cred={
287#	imsi="310026-000000000"
288#	milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82"
289#}
290#
291#cred={
292#	realm="example.com"
293#	username="user"
294#	password="password"
295#	ca_cert="/etc/wpa_supplicant/ca.pem"
296#	domain="example.com"
297#	roaming_consortium=223344
298#	eap=TTLS
299#	phase2="auth=MSCHAPV2"
300#}
301
302
303Control interface
304-----------------
305
306wpa_supplicant provides a control interface that can be used from
307external programs to manage various operations. The included command
308line tool, wpa_cli, can be used for manual testing with this interface.
309
310Following wpa_cli interactive mode commands show some examples of manual
311operations related to Hotspot 2.0:
312
313Remove configured networks and credentials:
314
315> remove_network all
316OK
317> remove_cred all
318OK
319
320
321Add a username/password credential:
322
323> add_cred
3240
325> set_cred 0 realm "mail.example.com"
326OK
327> set_cred 0 username "username"
328OK
329> set_cred 0 password "password"
330OK
331> set_cred 0 priority 1
332OK
333> set_cred 0 temporary 1
334OK
335
336Add a SIM credential using a simulated SIM/USIM card for testing:
337
338> add_cred
3391
340> set_cred 1 imsi "23456-0000000000"
341OK
342> set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123"
343OK
344> set_cred 1 priority 1
345OK
346
347Note: the return value of add_cred is used as the first argument to
348the following set_cred commands.
349
350Add a SIM credential using a external SIM/USIM processing:
351
352> set external_sim 1
353OK
354> add_cred
3551
356> set_cred 1 imsi "23456-0000000000"
357OK
358> set_cred 1 eap SIM
359OK
360
361
362Add a WPA2-Enterprise network:
363
364> add_network
3650
366> set_network 0 key_mgmt WPA-EAP
367OK
368> set_network 0 ssid "enterprise"
369OK
370> set_network 0 eap TTLS
371OK
372> set_network 0 anonymous_identity "anonymous"
373OK
374> set_network 0 identity "user"
375OK
376> set_network 0 password "password"
377OK
378> set_network 0 priority 0
379OK
380> enable_network 0 no-connect
381OK
382
383
384Add an open network:
385
386> add_network
3873
388> set_network 3 key_mgmt NONE
389OK
390> set_network 3 ssid "coffee-shop"
391OK
392> select_network 3
393OK
394
395Note: the return value of add_network is used as the first argument to
396the following set_network commands.
397
398The preferred credentials/networks can be indicated with the priority
399parameter (1 is higher priority than 0).
400
401
402Interworking network selection can be started with interworking_select
403command. This instructs wpa_supplicant to run a network scan and iterate
404through the discovered APs to request ANQP information from the APs that
405advertise support for Interworking/Hotspot 2.0:
406
407> interworking_select
408OK
409<3>Starting ANQP fetch for 02:00:00:00:01:00
410<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
411<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
412<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
413<3>ANQP fetch completed
414<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
415
416
417INTERWORKING-AP event messages indicate the APs that support network
418selection and for which there is a matching
419credential. interworking_connect command can be used to select a network
420to connect with:
421
422
423> interworking_connect 02:00:00:00:01:00
424OK
425<3>CTRL-EVENT-SCAN-RESULTS
426<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
427<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
428<3>Associated with 02:00:00:00:01:00
429<3>CTRL-EVENT-EAP-STARTED EAP authentication started
430<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
431<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
432<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
433<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
434<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=]
435
436
437wpa_supplicant creates a temporary network block for the selected
438network based on the configured credential and ANQP information from the
439AP:
440
441> list_networks
442network id / ssid / bssid / flags
4430	Example Network	any	[CURRENT]
444> get_network 0 key_mgmt
445WPA-EAP
446> get_network 0 eap
447TTLS
448
449
450Alternatively to using an external program to select the network,
451"interworking_select auto" command can be used to request wpa_supplicant
452to select which network to use based on configured priorities:
453
454
455> remove_network all
456OK
457<3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1
458> interworking_select auto
459OK
460<3>Starting ANQP fetch for 02:00:00:00:01:00
461<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
462<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
463<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
464<3>ANQP fetch completed
465<3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
466<3>CTRL-EVENT-SCAN-RESULTS
467<3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
468<3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
469<3>Associated with 02:00:00:00:01:00
470<3>CTRL-EVENT-EAP-STARTED EAP authentication started
471<3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
472<3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
473<3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
474<3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
475<3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=]
476
477
478The connection status can be shown with the status command:
479
480> status
481bssid=02:00:00:00:01:00
482ssid=Example Network
483id=0
484mode=station
485pairwise_cipher=CCMP       <--- link layer security indication
486group_cipher=CCMP
487key_mgmt=WPA2/IEEE 802.1X/EAP
488wpa_state=COMPLETED
489p2p_device_address=02:00:00:00:00:00
490address=02:00:00:00:00:00
491hs20=1      <--- HS 2.0 indication
492Supplicant PAE state=AUTHENTICATED
493suppPortStatus=Authorized
494EAP state=SUCCESS
495selectedMethod=21 (EAP-TTLS)
496EAP TLS cipher=AES-128-SHA
497EAP-TTLSv0 Phase2 method=PAP
498
499
500> status
501bssid=02:00:00:00:02:00
502ssid=coffee-shop
503id=3
504mode=station
505pairwise_cipher=NONE
506group_cipher=NONE
507key_mgmt=NONE
508wpa_state=COMPLETED
509p2p_device_address=02:00:00:00:00:00
510address=02:00:00:00:00:00
511
512
513Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status
514command output. Link layer security is indicated with the
515pairwise_cipher (CCMP = secure, NONE = no encryption used).
516
517
518Also the scan results include the Hotspot 2.0 indication:
519
520> scan_results
521bssid / frequency / signal level / flags / ssid
52202:00:00:00:01:00	2412	-30	[WPA2-EAP-CCMP][ESS][HS20]	Example Network
523
524
525ANQP information for the BSS can be fetched using the BSS command:
526
527> bss 02:00:00:00:01:00
528id=1
529bssid=02:00:00:00:01:00
530freq=2412
531beacon_int=100
532capabilities=0x0411
533qual=0
534noise=-92
535level=-30
536tsf=1345573286517276
537age=105
538ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000
539flags=[WPA2-EAP-CCMP][ESS][HS20]
540ssid=Example Network
541anqp_roaming_consortium=031122330510203040500601020304050603fedcba
542
543
544ANQP queries can also be requested with the anqp_get and hs20_anqp_get
545commands:
546
547> anqp_get 02:00:00:00:01:00 261
548OK
549<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
550> hs20_anqp_get 02:00:00:00:01:00 2
551OK
552<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
553
554In addition, fetch_anqp command can be used to request similar set of
555ANQP queries to be done as is run as part of interworking_select:
556
557> scan
558OK
559<3>CTRL-EVENT-SCAN-RESULTS
560> fetch_anqp
561OK
562<3>Starting ANQP fetch for 02:00:00:00:01:00
563<3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
564<3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
565<3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
566<3>ANQP fetch completed
567
568
569Hotspot 2.0 Rel 2 online signup and OSEN
570----------------------------------------
571
572Following parameters can be used to create a network profile for
573link-layer protected Hotspot 2.0 online signup connection with
574OSEN. Note that ssid and identify (NAI) values need to be set based on
575the information for the selected provider in the OSU Providers list
576ANQP-element.
577
578network={
579    ssid="HS 2.0 OSU"
580    proto=OSEN
581    key_mgmt=OSEN
582    pairwise=CCMP
583    group=GTK_NOT_USED
584    eap=WFA-UNAUTH-TLS
585    identity="anonymous@example.com"
586    ca_cert="osu-ca.pem"
587    ocsp=2
588}
589
590
591Hotspot 2.0 connection with external network selection
592------------------------------------------------------
593
594When an component controlling wpa_supplicant takes care of Interworking
595network selection, following configuration and network profile
596parameters can be used to configure a temporary network profile for a
597Hotspot 2.0 connection (e.g., with SET, ADD_NETWORK, SET_NETWORK, and
598SELECT_NETWORK control interface commands):
599
600interworking=1
601hs20=1
602auto_interworking=0
603
604network={
605    ssid="test-hs20"
606    proto=RSN
607    key_mgmt=WPA-EAP
608    pairwise=CCMP
609    anonymous_identity="anonymous@example.com"
610    identity="hs20-test@example.com"
611    password="password"
612    ca_cert="ca.pem"
613    eap=TTLS
614    phase2="auth=MSCHAPV2"
615    update_identifier=54321
616    #ocsp=2
617}
618
619
620These parameters are set based on the PPS MO credential and/or NAI Realm
621list ANQP-element:
622
623anonymous_identity: Credential/UsernamePassword/Username with username part
624		    replaced with "anonymous"
625identity: Credential/UsernamePassword/Username
626password: Credential/UsernamePassword/Password
627update_identifier: PPS/UpdateIdentifier
628ca_cert: from the downloaded trust root based on PPS information
629eap: Credential/UsernamePassword/EAPMethod or NAI Realm list
630phase2: Credential/UsernamePassword/EAPMethod or NAI Realm list
631ocsp: Credential/CheckAAAServerCertStatus
632