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