To support Passpoint, device manufacturers need to implement
hardware/interfaces/wifi/supplicant/1.0 or higher. The Wi-Fi
HAL interface design language (HIDL) provided
in the Android Open Source Project (AOSP) defines a HAL to the supplicant.
The supplicant provides support for
the 802.11u standard, specifically
network discovery and selection features such as Generic Advertisement Service
(GAS) and access network query protocol (ANQP).
Device manufacturers need to provide both framework and HAL/firmware support:
- Framework: Enable Passpoint (requires a feature flag)
- Firmware: Support for 802.11u
To support Passpoint, implement the Wi-Fi HAL and enable the feature flag for
device.mk located in
device/<oem>/<device>, modify the
PRODUCT_COPY_FILES environment variable to include support for the
PRODUCT_COPY_FILES += frameworks/native/data/etc/android.hardware.wifi.passpoint.xml:$(TARGET_COPY_OUT_VENDOR)/etc/permissions/android.hardware.wifi.passpoint.xml
All other requirements for supporting Passpoint are included in AOSP.
To validate your implementation of the Passpoint feature, use the set of unit tests and integration tests provided in the Android Comms Test Suite (ACTS).
Run the following Passpoint package unit tests.
% ./frameworks/opt/net/wifi/tests/wifitests/runtests.sh -e package com.android.server.wifi.hotspot2
% ./frameworks/base/wifi/tests/runtests.sh -e package android.net.wifi.hotspot2
Integration tests (ACTS)
The ACTS Passpoint test suite, located in
implements a set of functional tests.
Android has supported Passpoint R1 since Android 6.0, allowing the provisioning of Passpoint R1 (release 1) credentials through web-based downloading of a special file that contains profile and credential information. The client automatically launches a special installer for the Wi-Fi information and allows the user to view parts of the information before accepting or declining the content.
The profile information contained in the file is used for matching to data retrieved from Passpoint-enabled access points, and the credentials are automatically applied for any matched network.
The Android reference implementation supports EAP-TTLS, EAP-TLS, EAP-SIM, EAP-AKA, and EAP-AKA'.
The Passpoint configuration file must be hosted on a web server and should be protected with TLS (HTTPS) because it may contain clear text password or private key data. The content is made up of wrapped multipart MIME text represented in UTF-8 and encoded in base64 encoding per RFC-2045 section 6.8.
The following HTTP header fields are used by the client to automatically launch a Wi-Fi installer on the device:
Content-Typemust be set to
Content-Transfer-Encodingmust be set to
Content-Dispositionmust not be set.
The HTTP method used to retrieve the file must be GET. Any time an HTTP GET from the browser receives a response with these MIME headers, the installation app is started. The download must be triggered by tapping on an HTML element such as a button (automatic redirects to a download URL aren't supported). This behavior is specific to Google Chrome; other web browsers may or may not provide similar functionality.
The base64-encoded content must consist of MIME multipart content with a
multipart/mixed. The following parts make up the individual
parts of the multipart content.
|Part||Content-Type (less quotes)||Required||Description|
||Always||OMA-DM SyncML formatted payload containing the Passpoint R1
||Required for EAP-TLS and EAP-TTLS||A single X.509v3 base64-encoded certificate payload.|
||Required for EAP-TLS||A base64-encoded PKCS #12 ASN.1 structure containing a client certificate chain with at least the client certificate and the associated private key. The PKCS 12 container as well as the private key and the certificates must all be in clear text with no password.|
The Profile section must be transferred as base64-encoded, UTF-8-encoded XML
text that specifies parts of the
Credential subtrees in the
Passpoint R2 Technical Specification Version 1.0.0, section 9.1.
The top-level node must be
MgmtTree and the immediate subnode must be
PerProviderSubscription. An example XML file appears in
Example profile OMA-DM XML.
The following subtree nodes are used under
FriendlyName: Must be set; used as display text
The following subtree nodes are used under
Realm: Must be a nonempty string
UsernamePassword: Required for EAP-TTLS with the following nodes set:
Username: String that contains the username
Password: Base64-encoded string (set to
cGFzc3dvcmQ=, the base64-encoded string for "password", in the example below)
EAPMethod/EAPType: Must be set to
EAPMethod/InnerMethod: Must be set to one of
DigitalCertificate: Required for EAP-TLS. The following nodes must be set:
CertSHA256Fingerprintset to the correct SHA-256 digest of the client certificate in the EAP-TLS key MIME section
SIM: Required for EAP-SIM, EAP-AKA, and EAP-AKA'. The
EAPTypefield must be set to the appropriate EAP type and
IMSImust match an IMSI of one of the SIM cards installed in the device at the time of provisioning. The IMSI string can either consist entirely of decimal digits to force full equality match, or of zero or more decimal digits followed by an asterisk (*) to relax the IMSI matching to prefix only. For example, the IMSI string 123* matches any SIM card with an IMSI starting with 123.
Example profile OMA-DM XML
<MgmtTree xmlns="syncml:dmddf1.2"> <VerDTD>1.2</VerDTD> <Node> <NodeName>PerProviderSubscription</NodeName> <RTProperties> <Type> <DDFName>urn:wfa:mo:hotspot2dot0-perprovidersubscription:1.0</DDFName> </Type> </RTProperties> <Node> <NodeName>i001</NodeName> <Node> <NodeName>HomeSP</NodeName> <Node> <NodeName>FriendlyName</NodeName> <Value>Example Network</Value> </Node> <Node> <NodeName>FQDN</NodeName> <Value>hotspot.example.net</Value> </Node> <Node> <NodeName>RoamingConsortiumOI</NodeName> <Value>112233,445566</Value> </Node> </Node> <Node> <NodeName>Credential</NodeName> <Node> <NodeName>Realm</NodeName> <Value>example.com</Value> </Node> <Node> <NodeName>UsernamePassword</NodeName> <Node> <NodeName>Username</NodeName> <Value>user</Value> </Node> <Node> <NodeName>Password</NodeName> <Value>cGFzc3dvcmQ=</Value> </Node> <Node> <NodeName>EAPMethod</NodeName> <Node> <NodeName>EAPType</NodeName> <Value>21</Value> </Node> <Node> <NodeName>InnerMethod</NodeName> <Value>MS-CHAP-V2</Value> </Node> </Node> </Node> </Node> </Node> </Node> </MgmtTree>
Devices running Android 8.x or Android 9 with a Passpoint R1 EAP-SIM, EAP-AKA, or EAP-AKA' profile won't autoconnect to the Passpoint network. This issue affects users, carriers, and services by reducing the Wi-Fi offload.
|Segment||Impact||Size of impact|
|Carriers and Passpoint service providers||Increased load on cellular network.||Any carrier using Passpoint R1.|
|Users||Missed opportunity to autoconnect to Carrier Wi-Fi access points (APs), resulting in higher data costs.||Any user with a device that runs on a carrier network supporting Passpoint R1.|
Cause of failure
Passpoint specifies a mechanism to match an advertised (ANQP) service provider to a profile installed on the device. The following matching rules for EAP-SIM, EAP-AKA, and EAP-AKA' are a partial set of rules focusing on the EAP-SIM/AKA/AKA' failures:
If the FQDN (Fully Qualified Domain Name) matches then the service is a Home Service Provider. Else: If the PLMN ID (3GPP Network) matches then the service is a Roaming Service Provider.
The second criterion was modified in Android 8.0:
Else: If the PLMN ID (3GPP Network) matches AND the NAI Realm matches then the service is a Roaming Service Provider.
With this modification, the system observed no match for previously working service providers, so Passpoint devices didn't autoconnect.
To work around the issue of the modified matching criteria, carriers and service providers need to add the network access identifier (NAI) realm to the information published by the Passpoint AP.
The recommended solution is for network service providers to implement a network-side workaround for the fastest time to deployment. A device-side workaround depends on OEMs picking up a changelist (CL) from AOSP and then updating devices in the field.
Network fix for carriers and Passpoint service providers
The network-side workaround requires reconfiguring the network to add the NAI realm ANQP element as specified below. The Passpoint specifications don't require the NAI realm ANQP element, but the addition of this property complies with the Passpoint specifications, so spec-compliant client implementations should not break.
- Add the NAI realm ANQP element.
- Set the NAI realm subfield to match the
Realmof the profile installed on the device.
Set the following information based on each EAP type:
- EAP-TTLS: Set
EAPMethod(21)and supported inner auth types (
- EAP-TLS: Set
- EAP-SIM: Set
- EAP-AKA: Set
- EAP-AKA': Set
- EAP-TTLS: Set
Device/AOSP fix for OEMs
To implement a device-side workaround, OEMs need to pick the patch CL aosp/718508. This patch can be applied on top of the following releases (doesn't apply to Android 10 or higher):
- Android 9
- Android 8.x
When the patch is picked up, OEMs need to update devices in the field.
Android 10 introduces support for Passpoint R2 features. Passpoint R2 implements online sign up (OSU), a standard method to provision new Passpoint profiles. Android 10 supports the provisioning of EAP-TTLS profiles using SOAP-XML.
The Passpoint R2 features supported in Android 10 only require AOSP code (no additional driver or firmware support is required). The AOSP code also includes a default implementation of the Passpoint R2 UI in the Settings application.
When Android detects a Passpoint R2 access point, the Android framework:
- Displays a list of the service providers in the Wi-Fi picker (in addition to displaying the SSIDs).
- Prompts the user to tap one of the service providers to set up a Passpoint profile.
- Walks the user through the Passpoint profile setup flow.
- Installs the resulting Passpoint profile on successful completion.
- Associates to the Passpoint network using the newly provisioned Passpoint profile.