README-HS20 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564
  1. wpa_supplicant and Hotspot 2.0
  2. ==============================
  3. This document describe how the IEEE 802.11u Interworking and Wi-Fi
  4. Hotspot 2.0 (Release 1) implementation in wpa_supplicant can be
  5. configured and how an external component on the client e.g., management
  6. GUI or Wi-Fi framework) is used to manage this functionality.
  7. Introduction to Wi-Fi Hotspot 2.0
  8. ---------------------------------
  9. Hotspot 2.0 is the name of the Wi-Fi Alliance specification that is used
  10. in the Wi-Fi CERTIFIED Passpoint<TM> program. More information about
  11. this is available in this white paper:
  12. 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
  13. The Hotspot 2.0 specification is also available from WFA:
  14. https://www.wi-fi.org/knowledge-center/published-specifications
  15. The core Interworking functionality (network selection, GAS/ANQP) were
  16. standardized in IEEE Std 802.11u-2011 which is now part of the IEEE Std
  17. 802.11-2012.
  18. wpa_supplicant network selection
  19. --------------------------------
  20. Interworking support added option for configuring credentials that can
  21. work with multiple networks as an alternative to configuration of
  22. network blocks (e.g., per-SSID parameters). When requested to perform
  23. network selection, wpa_supplicant picks the highest priority enabled
  24. network block or credential. If a credential is picked (based on ANQP
  25. information from APs), a temporary network block is created
  26. automatically for the matching network. This temporary network block is
  27. used similarly to the network blocks that can be configured by the user,
  28. but it is not stored into the configuration file and is meant to be used
  29. only for temporary period of time since a new one can be created
  30. whenever needed based on ANQP information and the credential.
  31. By default, wpa_supplicant is not using automatic network selection
  32. unless requested explicitly with the interworking_select command. This
  33. can be changed with the auto_interworking=1 parameter to perform network
  34. selection automatically whenever trying to find a network for connection
  35. and none of the enabled network blocks match with the scan results. This
  36. case works similarly to "interworking_select auto", i.e., wpa_supplicant
  37. will internally determine which network or credential is going to be
  38. used based on configured priorities, scan results, and ANQP information.
  39. wpa_supplicant configuration
  40. ----------------------------
  41. Interworking and Hotspot 2.0 functionality are optional components that
  42. need to be enabled in the wpa_supplicant build configuration
  43. (.config). This is done by adding following parameters into that file:
  44. CONFIG_INTERWORKING=y
  45. CONFIG_HS20=y
  46. It should be noted that this functionality requires a driver that
  47. supports GAS/ANQP operations. This uses the same design as P2P, i.e.,
  48. Action frame processing and building in user space within
  49. wpa_supplicant. The Linux nl80211 driver interface provides the needed
  50. functionality for this.
  51. There are number of run-time configuration parameters (e.g., in
  52. wpa_supplicant.conf when using the configuration file) that can be used
  53. to control Hotspot 2.0 operations.
  54. # Enable Interworking
  55. interworking=1
  56. # Enable Hotspot 2.0
  57. hs20=1
  58. # Parameters for controlling scanning
  59. # Homogenous ESS identifier
  60. # If this is set, scans will be used to request response only from BSSes
  61. # belonging to the specified Homogeneous ESS. This is used only if interworking
  62. # is enabled.
  63. #hessid=00:11:22:33:44:55
  64. # Access Network Type
  65. # When Interworking is enabled, scans can be limited to APs that advertise the
  66. # specified Access Network Type (0..15; with 15 indicating wildcard match).
  67. # This value controls the Access Network Type value in Probe Request frames.
  68. #access_network_type=15
  69. # Automatic network selection behavior
  70. # 0 = do not automatically go through Interworking network selection
  71. # (i.e., require explicit interworking_select command for this; default)
  72. # 1 = perform Interworking network selection if one or more
  73. # credentials have been configured and scan did not find a
  74. # matching network block
  75. #auto_interworking=0
  76. Credentials can be pre-configured for automatic network selection:
  77. # credential block
  78. #
  79. # Each credential used for automatic network selection is configured as a set
  80. # of parameters that are compared to the information advertised by the APs when
  81. # interworking_select and interworking_connect commands are used.
  82. #
  83. # credential fields:
  84. #
  85. # temporary: Whether this credential is temporary and not to be saved
  86. #
  87. # priority: Priority group
  88. # By default, all networks and credentials get the same priority group
  89. # (0). This field can be used to give higher priority for credentials
  90. # (and similarly in struct wpa_ssid for network blocks) to change the
  91. # Interworking automatic networking selection behavior. The matching
  92. # network (based on either an enabled network block or a credential)
  93. # with the highest priority value will be selected.
  94. #
  95. # pcsc: Use PC/SC and SIM/USIM card
  96. #
  97. # realm: Home Realm for Interworking
  98. #
  99. # username: Username for Interworking network selection
  100. #
  101. # password: Password for Interworking network selection
  102. #
  103. # ca_cert: CA certificate for Interworking network selection
  104. #
  105. # client_cert: File path to client certificate file (PEM/DER)
  106. # This field is used with Interworking networking selection for a case
  107. # where client certificate/private key is used for authentication
  108. # (EAP-TLS). Full path to the file should be used since working
  109. # directory may change when wpa_supplicant is run in the background.
  110. #
  111. # Alternatively, a named configuration blob can be used by setting
  112. # this to blob://blob_name.
  113. #
  114. # private_key: File path to client private key file (PEM/DER/PFX)
  115. # When PKCS#12/PFX file (.p12/.pfx) is used, client_cert should be
  116. # commented out. Both the private key and certificate will be read
  117. # from the PKCS#12 file in this case. Full path to the file should be
  118. # used since working directory may change when wpa_supplicant is run
  119. # in the background.
  120. #
  121. # Windows certificate store can be used by leaving client_cert out and
  122. # configuring private_key in one of the following formats:
  123. #
  124. # cert://substring_to_match
  125. #
  126. # hash://certificate_thumbprint_in_hex
  127. #
  128. # For example: private_key="hash://63093aa9c47f56ae88334c7b65a4"
  129. #
  130. # Note that when running wpa_supplicant as an application, the user
  131. # certificate store (My user account) is used, whereas computer store
  132. # (Computer account) is used when running wpasvc as a service.
  133. #
  134. # Alternatively, a named configuration blob can be used by setting
  135. # this to blob://blob_name.
  136. #
  137. # private_key_passwd: Password for private key file
  138. #
  139. # imsi: IMSI in <MCC> | <MNC> | '-' | <MSIN> format
  140. #
  141. # milenage: Milenage parameters for SIM/USIM simulator in <Ki>:<OPc>:<SQN>
  142. # format
  143. #
  144. # domain_suffix_match: Constraint for server domain name
  145. # If set, this FQDN is used as a suffix match requirement for the AAA
  146. # server certificate in SubjectAltName dNSName element(s). If a
  147. # matching dNSName is found, this constraint is met. If no dNSName
  148. # values are present, this constraint is matched against SubjetName CN
  149. # using same suffix match comparison. Suffix match here means that the
  150. # host/domain name is compared one label at a time starting from the
  151. # top-level domain and all the labels in @domain_suffix_match shall be
  152. # included in the certificate. The certificate may include additional
  153. # sub-level labels in addition to the required labels.
  154. #
  155. # For example, domain_suffix_match=example.com would match
  156. # test.example.com but would not match test-example.com.
  157. #
  158. # domain: Home service provider FQDN(s)
  159. # This is used to compare against the Domain Name List to figure out
  160. # whether the AP is operated by the Home SP. Multiple domain entries can
  161. # be used to configure alternative FQDNs that will be considered home
  162. # networks.
  163. #
  164. # roaming_consortium: Roaming Consortium OI
  165. # If roaming_consortium_len is non-zero, this field contains the
  166. # Roaming Consortium OI that can be used to determine which access
  167. # points support authentication with this credential. This is an
  168. # alternative to the use of the realm parameter. When using Roaming
  169. # Consortium to match the network, the EAP parameters need to be
  170. # pre-configured with the credential since the NAI Realm information
  171. # may not be available or fetched.
  172. #
  173. # eap: Pre-configured EAP method
  174. # This optional field can be used to specify which EAP method will be
  175. # used with this credential. If not set, the EAP method is selected
  176. # automatically based on ANQP information (e.g., NAI Realm).
  177. #
  178. # phase1: Pre-configure Phase 1 (outer authentication) parameters
  179. # This optional field is used with like the 'eap' parameter.
  180. #
  181. # phase2: Pre-configure Phase 2 (inner authentication) parameters
  182. # This optional field is used with like the 'eap' parameter.
  183. #
  184. # excluded_ssid: Excluded SSID
  185. # This optional field can be used to excluded specific SSID(s) from
  186. # matching with the network. Multiple entries can be used to specify more
  187. # than one SSID.
  188. #
  189. # roaming_partner: Roaming partner information
  190. # This optional field can be used to configure preferences between roaming
  191. # partners. The field is a string in following format:
  192. # <FQDN>,<0/1 exact match>,<priority>,<* or country code>
  193. # (non-exact match means any subdomain matches the entry; priority is in
  194. # 0..255 range with 0 being the highest priority)
  195. #
  196. # update_identifier: PPS MO ID
  197. # (Hotspot 2.0 PerProviderSubscription/UpdateIdentifier)
  198. #
  199. # provisioning_sp: FQDN of the SP that provisioned the credential
  200. # This optional field can be used to keep track of the SP that provisioned
  201. # the credential to find the PPS MO (./Wi-Fi/<provisioning_sp>).
  202. #
  203. # sp_priority: Credential priority within a provisioning SP
  204. # This is the priority of the credential among all credentials
  205. # provisionined by the same SP (i.e., for entries that have identical
  206. # provisioning_sp value). The range of this priority is 0-255 with 0
  207. # being the highest and 255 the lower priority.
  208. #
  209. # Minimum backhaul threshold (PPS/<X+>/Policy/MinBackhauldThreshold/*)
  210. # These fields can be used to specify minimum download/upload backhaul
  211. # bandwidth that is preferred for the credential. This constraint is
  212. # ignored if the AP does not advertise WAN Metrics information or if the
  213. # limit would prevent any connection. Values are in kilobits per second.
  214. # min_dl_bandwidth_home
  215. # min_ul_bandwidth_home
  216. # min_dl_bandwidth_roaming
  217. # min_ul_bandwidth_roaming
  218. #
  219. # max_bss_load: Maximum BSS Load Channel Utilization (1..255)
  220. # (PPS/<X+>/Policy/MaximumBSSLoadValue)
  221. # This value is used as the maximum channel utilization for network
  222. # selection purposes for home networks. If the AP does not advertise
  223. # BSS Load or if the limit would prevent any connection, this constraint
  224. # will be ignored.
  225. #
  226. # req_conn_capab: Required connection capability
  227. # (PPS/<X+>/Policy/RequiredProtoPortTuple)
  228. # This value is used to configure set of required protocol/port pairs that
  229. # a roaming network shall support (include explicitly in Connection
  230. # Capability ANQP element). This constraint is ignored if the AP does not
  231. # advertise Connection Capability or if this constraint would prevent any
  232. # network connection. This policy is not used in home networks.
  233. # Format: <protocol>[:<comma-separated list of ports]
  234. # Multiple entries can be used to list multiple requirements.
  235. # For example, number of common TCP protocols:
  236. # req_conn_capab=6:22,80,443
  237. # For example, IPSec/IKE:
  238. # req_conn_capab=17:500
  239. # req_conn_capab=50
  240. #
  241. # ocsp: Whether to use/require OCSP to check server certificate
  242. # 0 = do not use OCSP stapling (TLS certificate status extension)
  243. # 1 = try to use OCSP stapling, but not require response
  244. # 2 = require valid OCSP stapling response
  245. #
  246. # for example:
  247. #
  248. #cred={
  249. # realm="example.com"
  250. # username="user@example.com"
  251. # password="password"
  252. # ca_cert="/etc/wpa_supplicant/ca.pem"
  253. # domain="example.com"
  254. # domain_suffix_match="example.com"
  255. #}
  256. #
  257. #cred={
  258. # imsi="310026-000000000"
  259. # milenage="90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82"
  260. #}
  261. #
  262. #cred={
  263. # realm="example.com"
  264. # username="user"
  265. # password="password"
  266. # ca_cert="/etc/wpa_supplicant/ca.pem"
  267. # domain="example.com"
  268. # roaming_consortium=223344
  269. # eap=TTLS
  270. # phase2="auth=MSCHAPV2"
  271. #}
  272. Control interface
  273. -----------------
  274. wpa_supplicant provides a control interface that can be used from
  275. external programs to manage various operations. The included command
  276. line tool, wpa_cli, can be used for manual testing with this interface.
  277. Following wpa_cli interactive mode commands show some examples of manual
  278. operations related to Hotspot 2.0:
  279. Remove configured networks and credentials:
  280. > remove_network all
  281. OK
  282. > remove_cred all
  283. OK
  284. Add a username/password credential:
  285. > add_cred
  286. 0
  287. > set_cred 0 realm "mail.example.com"
  288. OK
  289. > set_cred 0 username "username"
  290. OK
  291. > set_cred 0 password "password"
  292. OK
  293. > set_cred 0 priority 1
  294. OK
  295. > set_cred 0 temporary 1
  296. OK
  297. Add a SIM credential using a simulated SIM/USIM card for testing:
  298. > add_cred
  299. 1
  300. > set_cred 1 imsi "23456-0000000000"
  301. OK
  302. > set_cred 1 milenage "90dca4eda45b53cf0f12d7c9c3bc6a89:cb9cccc4b9258e6dca4760379fb82581:000000000123"
  303. OK
  304. > set_cred 1 priority 1
  305. OK
  306. Note: the return value of add_cred is used as the first argument to
  307. the following set_cred commands.
  308. Add a SIM credential using a external SIM/USIM processing:
  309. > set external_sim 1
  310. OK
  311. > add_cred
  312. 1
  313. > set_cred 1 imsi "23456-0000000000"
  314. OK
  315. > set_cred 1 eap SIM
  316. OK
  317. Add a WPA2-Enterprise network:
  318. > add_network
  319. 0
  320. > set_network 0 key_mgmt WPA-EAP
  321. OK
  322. > set_network 0 ssid "enterprise"
  323. OK
  324. > set_network 0 eap TTLS
  325. OK
  326. > set_network 0 anonymous_identity "anonymous"
  327. OK
  328. > set_network 0 identity "user"
  329. OK
  330. > set_network 0 password "password"
  331. OK
  332. > set_network 0 priority 0
  333. OK
  334. > enable_network 0 no-connect
  335. OK
  336. Add an open network:
  337. > add_network
  338. 3
  339. > set_network 3 key_mgmt NONE
  340. OK
  341. > set_network 3 ssid "coffee-shop"
  342. OK
  343. > select_network 3
  344. OK
  345. Note: the return value of add_network is used as the first argument to
  346. the following set_network commands.
  347. The preferred credentials/networks can be indicated with the priority
  348. parameter (1 is higher priority than 0).
  349. Interworking network selection can be started with interworking_select
  350. command. This instructs wpa_supplicant to run a network scan and iterate
  351. through the discovered APs to request ANQP information from the APs that
  352. advertise support for Interworking/Hotspot 2.0:
  353. > interworking_select
  354. OK
  355. <3>Starting ANQP fetch for 02:00:00:00:01:00
  356. <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
  357. <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
  358. <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
  359. <3>ANQP fetch completed
  360. <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
  361. INTERWORKING-AP event messages indicate the APs that support network
  362. selection and for which there is a matching
  363. credential. interworking_connect command can be used to select a network
  364. to connect with:
  365. > interworking_connect 02:00:00:00:01:00
  366. OK
  367. <3>CTRL-EVENT-SCAN-RESULTS
  368. <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
  369. <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
  370. <3>Associated with 02:00:00:00:01:00
  371. <3>CTRL-EVENT-EAP-STARTED EAP authentication started
  372. <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
  373. <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
  374. <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
  375. <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
  376. <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (auth) [id=0 id_str=]
  377. wpa_supplicant creates a temporary network block for the selected
  378. network based on the configured credential and ANQP information from the
  379. AP:
  380. > list_networks
  381. network id / ssid / bssid / flags
  382. 0 Example Network any [CURRENT]
  383. > get_network 0 key_mgmt
  384. WPA-EAP
  385. > get_network 0 eap
  386. TTLS
  387. Alternatively to using an external program to select the network,
  388. "interworking_select auto" command can be used to request wpa_supplicant
  389. to select which network to use based on configured priorities:
  390. > remove_network all
  391. OK
  392. <3>CTRL-EVENT-DISCONNECTED bssid=02:00:00:00:01:00 reason=1 locally_generated=1
  393. > interworking_select auto
  394. OK
  395. <3>Starting ANQP fetch for 02:00:00:00:01:00
  396. <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
  397. <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
  398. <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
  399. <3>ANQP fetch completed
  400. <3>INTERWORKING-AP 02:00:00:00:01:00 type=unknown
  401. <3>CTRL-EVENT-SCAN-RESULTS
  402. <3>SME: Trying to authenticate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
  403. <3>Trying to associate with 02:00:00:00:01:00 (SSID='Example Network' freq=2412 MHz)
  404. <3>Associated with 02:00:00:00:01:00
  405. <3>CTRL-EVENT-EAP-STARTED EAP authentication started
  406. <3>CTRL-EVENT-EAP-PROPOSED-METHOD vendor=0 method=21
  407. <3>CTRL-EVENT-EAP-METHOD EAP vendor 0 method 21 (TTLS) selected
  408. <3>CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
  409. <3>WPA: Key negotiation completed with 02:00:00:00:01:00 [PTK=CCMP GTK=CCMP]
  410. <3>CTRL-EVENT-CONNECTED - Connection to 02:00:00:00:01:00 completed (reauth) [id=0 id_str=]
  411. The connection status can be shown with the status command:
  412. > status
  413. bssid=02:00:00:00:01:00
  414. ssid=Example Network
  415. id=0
  416. mode=station
  417. pairwise_cipher=CCMP <--- link layer security indication
  418. group_cipher=CCMP
  419. key_mgmt=WPA2/IEEE 802.1X/EAP
  420. wpa_state=COMPLETED
  421. p2p_device_address=02:00:00:00:00:00
  422. address=02:00:00:00:00:00
  423. hs20=1 <--- HS 2.0 indication
  424. Supplicant PAE state=AUTHENTICATED
  425. suppPortStatus=Authorized
  426. EAP state=SUCCESS
  427. selectedMethod=21 (EAP-TTLS)
  428. EAP TLS cipher=AES-128-SHA
  429. EAP-TTLSv0 Phase2 method=PAP
  430. > status
  431. bssid=02:00:00:00:02:00
  432. ssid=coffee-shop
  433. id=3
  434. mode=station
  435. pairwise_cipher=NONE
  436. group_cipher=NONE
  437. key_mgmt=NONE
  438. wpa_state=COMPLETED
  439. p2p_device_address=02:00:00:00:00:00
  440. address=02:00:00:00:00:00
  441. Note: The Hotspot 2.0 indication is shown as "hs20=1" in the status
  442. command output. Link layer security is indicated with the
  443. pairwise_cipher (CCMP = secure, NONE = no encryption used).
  444. Also the scan results include the Hotspot 2.0 indication:
  445. > scan_results
  446. bssid / frequency / signal level / flags / ssid
  447. 02:00:00:00:01:00 2412 -30 [WPA2-EAP-CCMP][ESS][HS20] Example Network
  448. ANQP information for the BSS can be fetched using the BSS command:
  449. > bss 02:00:00:00:01:00
  450. id=1
  451. bssid=02:00:00:00:01:00
  452. freq=2412
  453. beacon_int=100
  454. capabilities=0x0411
  455. qual=0
  456. noise=-92
  457. level=-30
  458. tsf=1345573286517276
  459. age=105
  460. ie=000f4578616d706c65204e6574776f726b010882848b960c1218240301012a010432043048606c30140100000fac040100000fac040100000fac0100007f04000000806b091e07010203040506076c027f006f1001531122331020304050010203040506dd05506f9a1000
  461. flags=[WPA2-EAP-CCMP][ESS][HS20]
  462. ssid=Example Network
  463. anqp_roaming_consortium=031122330510203040500601020304050603fedcba
  464. ANQP queries can also be requested with the anqp_get and hs20_anqp_get
  465. commands:
  466. > anqp_get 02:00:00:00:01:00 261
  467. OK
  468. <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
  469. > hs20_anqp_get 02:00:00:00:01:00 2
  470. OK
  471. <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
  472. In addition, fetch_anqp command can be used to request similar set of
  473. ANQP queries to be done as is run as part of interworking_select:
  474. > scan
  475. OK
  476. <3>CTRL-EVENT-SCAN-RESULTS
  477. > fetch_anqp
  478. OK
  479. <3>Starting ANQP fetch for 02:00:00:00:01:00
  480. <3>RX-ANQP 02:00:00:00:01:00 ANQP Capability list
  481. <3>RX-ANQP 02:00:00:00:01:00 Roaming Consortium list
  482. <3>RX-HS20-ANQP 02:00:00:00:01:00 HS Capability List
  483. <3>ANQP fetch completed