Passpoint (Hotspot 2.0)

Passpoint is a Wi-Fi Alliance (WFA) protocol that enables mobile devices to discover and authenticate to Wi-Fi hotspots that provide internet access.

Device support

To support Passpoint, device manufacturers need to implement the Supplicant interface. Starting with Android 13, the interface uses AIDL for the HAL definition. For releases before Android 13, interfaces and vendor partitions use HIDL. The HIDL files are in hardware/interfaces/supplicant/1.x and the AIDL files are in hardware/interfaces/supplicant/aidl. 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).

Implementation

Android 11 or higher

To support Passpoint on devices running Android 11 or higher, device manufacturers need to provide firmware support for 802.11u. All other requirements for supporting Passpoint are included in AOSP.

Android 10 or lower

For devices running Android 10 or lower, 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 Passpoint. In device.mk located in device/<oem>/<device>, modify the PRODUCT_COPY_FILES environment variable to include support for the Passpoint feature:

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.

Validation

To validate your implementation of the Passpoint feature, run the following Passpoint package unit tests:

Service tests:

atest com.android.server.wifi.hotspot2

Manager tests:

atest android.net.wifi.hotspot2

Passpoint R1 provisioning

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'.

Download mechanism

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-Type must be set to application/x-wifi-config.
  • Content-Transfer-Encoding must be set to base64.
  • Content-Disposition must 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.

File composition

The Base64 encoded content must consist of MIME multipart content with a Content-Type of multipart/mixed. The following parts make up the individual parts of the multipart content.

Part Content-Type (less quotes) Required Description
Profile application/x-passpoint-profile Always OMA-DM SyncML formatted payload containing the Passpoint R1 PerProviderSubscription formatted MO for HomeSP and Credential.
Trust certificate application/x-x509-ca-cert Required for EAP-TLS and EAP-TTLS A single X.509v3 base64-encoded certificate payload.
EAP-TLS key application/x-pkcs12 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 HomeSP and 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 HomeSP:

  • FriendlyName: Must be set; used as display text
  • FQDN: Required
  • RoamingConsortiumOI

The following subtree nodes are used under Credential:

  • 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 21
    • EAPMethod/InnerMethod: Must be set to one of PAP, CHAP, MS-CHAP, or MS-CHAP-V2

  • DigitalCertificate: Required for EAP-TLS. The following nodes must be set:

    • CertificateType set to x509v3
    • CertSHA256Fingerprint set 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 EAPType field must be set to the appropriate EAP type and IMSI must 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 5 or 6 decimal digits followed by an asterisk (*) to relax the IMSI matching to MCC/MNC only. For example, the IMSI string 123456* matches any SIM card with MCC as 123 and MNC as 456.

Android 11 introduces capabilities that make Passpoint R1 provisioning more flexible.

Separate authentication, authorization, and accounting (AAA) domain name

Passpoint network administrators that require a AAA domain name specified independently of the fully qualified domain name (FQDN) advertised by the network through the Access Network Query Protocol (ANQP) can specify a semicolon-delimited list of FQDNs in a new node under the Extension subtree. This is an optional node and devices running Android version 10 or lower ignore this node.

  • Android: Android extension subtree

    • AAAServerTrustedNames: Required for AAA server trusted names with the following nodes set:

      • FQDN: String that contains the AAA server trusted names. Use semicolons to separate the trusted names. For example, example.org;example.com.
Self-signed private Root CAs
Passpoint network administrators that manage their certificates internally can provision profiles with a private self-signed CA for AAA authentication.
Allow installation of profiles without a Root CA certificate
The Root CA certificate that's attached to the profile is used for AAA server authentication. Passpoint network administrators that want to rely on public trusted Root CAs for their AAA server authentication can provision profiles without a Root CA certificate. In this case, the system verifies the AAA server certificates against the public Root CA certificates installed in the trust store.

Passpoint R2 provisioning

Android 10 introduced support for Passpoint R2 features. Passpoint R2 implements online sign up (OSU), a standard method to provision new Passpoint profiles. Android 10 and higher supports the provisioning of EAP-TTLS profiles using the SOAP-XML protocol over open OSU ESS.

The supported Passpoint R2 features supported only require AOSP reference code (no additional driver or firmware support is required). The AOSP reference code also includes a default implementation of the Passpoint R2 UI in the Settings app.

When Android detects a Passpoint R2 access point, the Android framework:

  1. Displays a list of the service providers advertised by the AP in the Wi-Fi picker (in addition to displaying the SSIDs).
  2. Prompts the user to tap one of the service providers to set up a Passpoint profile.
  3. Walks the user through the Passpoint profile setup flow.
  4. Installs the resulting Passpoint profile on successful completion.
  5. Associates to the Passpoint network using the newly provisioned Passpoint profile.

Passpoint R3 features

Android 12 introduces the following Passpoint R3 features that improve the user experience and allow networks to comply with local laws:

Terms and conditions

Acceptance of terms and conditions is legally required in some locations and venues to provide network access. This feature allows network deployments to replace insecure captive portals, which use open networks, with a secure Passpoint network. A notification is displayed to the user when terms and conditions are required to be accepted.

The terms and conditions URL must point to a secure website using HTTPS. If the URL points to an insecure website, the framework immediately disconnects and blocks the network.

Venue information URL

Allows networks operators and venues to provide additional information to the user, such as venue maps, directories, promotions, and coupons. A notification is displayed to the user when the network is connected.

The venue information URL must point to a secure web site using HTTPS. If the URL points to an insecure website, the framework ignores the URL and doesn't display a notification.

Other Passpoint features

Android 11 introduces the following Passpoint capabilities that improve the user experience, power usage, and deployment flexibility.

Expiration date enforcement and notification
Enforcing expiration dates on profiles allows the framework to avoid autoconnection to access points with expired credentials, which are bound to fail. This prevents airtime usage, and saves battery and backend bandwidth. The framework displays a notification to the user when a network matching their profile is in range and the profile has expired.
Multiple profiles with identical FQDN
Carriers that deploy Passpoint networks and use multiple public land mobile network (PLMN) IDs can provision multiple Passpoint profiles with the same FQDN, one for each PLMN ID, which is automatically matched with the installed SIM card and used to connect the network.

Android 12 introduces the following Passpoint capabilities that improve the user experience, power usage, and deployment flexibility:

Decorated identity prefix
When authenticating to networks with a prefix decoration, the decorated identity prefix allows network operators to update the Network Access Identifier (NAI) to perform explicit routing through multiple proxies inside of an AAA network (see RFC 7542). Android 12 implements this feature according to the WBA specification for PPS-MO extensions.
Deauthentication imminent handling
Allows network operators to signal to a device that service isn't available for the credential used to authenticate to the network for a certain duration (specified through a timeout delay). After receiving this signal, devices won't attempt to reconnect to the network with the same credential until after the timeout delay expires. In contrast, devices that don't support this feature might attempt to repeatedly reconnect to the network while the service is unavailable.

Examples of OMA-DM PerProviderSubscription-MO XML profiles

Profile with a username/password credential (EAP-TTLS)

The following example demonstrates a profile for a network with:

  • Network friendly name set to Example Network
  • FQDN set to hotspot.example.net
  • Roaming consortium OIs (for roaming)
  • Credential with username user, password password encoded with Base64, and realm set to example.net
  • EAP method set to 21 (EAP-TTLS)
  • Phase-2 inner method set to MS-CHAP-V2
  • Alternative AAA domain names set to trusted.com and trusted.net
<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.net</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>
        <NodeName>Extension</NodeName>
        <Node>
            <NodeName>Android</NodeName>
            <Node>
                <NodeName>AAAServerTrustedNames</NodeName>
                <Node>
                    <NodeName>FQDN</NodeName>
                    <Value>trusted.com;trusted.net</Value>
                </Node>
            </Node>
        </Node>
      </Node>
    </Node>
  </Node>
</MgmtTree>

Profile with a digital certificate credential (EAP-TLS)

The following example demonstrates a profile for a network with:

  • Network friendly name set to GlobalRoaming
  • FQDN set to globalroaming.net
  • Roaming Consortium OIs (for roaming)
  • Realm set to users.globalroaming.net
  • Credential with a digital certificate that has the specified fingerprint
<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>GlobalRoaming</Value>
        </Node>
        <Node>
          <NodeName>FQDN</NodeName>
          <Value>globalroaming.net</Value>
        </Node>
        <Node>
          <NodeName>RoamingConsortiumOI</NodeName>
          <Value>FFEEDDCC0,FFEEDDCC1,009999,008888</Value>
        </Node>
      </Node>
      <Node>
        <NodeName>Credential</NodeName>
        <Node>
          <NodeName>Realm</NodeName>
          <Value>users.globalroaming.net</Value>
        </Node>
        <Node>
          <NodeName>DigitalCertificate</NodeName>
          <Node>
            <NodeName>CertificateType</NodeName>
            <Value>x509v3</Value>
          </Node>
          <Node>
            <NodeName>CertSHA256Fingerprint</NodeName>
            <Value>0ef08a3d2118700474ca51fa25dc5e6d3d63d779aaad8238b608a853761da533</Value>
          </Node>
        </Node>
      </Node>
    </Node>
  </Node>
</MgmtTree>

Profile with a SIM credential (EAP-AKA)

The following example demonstrates a profile for a network with:

  • Network friendly name set to Purple Passpoint
  • FQDN set to wlan.mnc888.mcc999.3gppnetwork.org
  • SIM credential with PLMN ID of 999888
  • EAP method set to 23 (EAP-AKA)
<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>Purple Passpoint</Value>
        </Node>
        <Node>
          <NodeName>FQDN</NodeName>
          <Value>purplewifi.com</Value>
        </Node>
      </Node>
      <Node>
        <NodeName>Credential</NodeName>
        <Node>
          <NodeName>Realm</NodeName>
          <Value>wlan.mnc888.mcc999.3gppnetwork.org</Value>
        </Node>
        <Node>
          <NodeName>SIM</NodeName>
          <Node>
            <NodeName>IMSI</NodeName>
            <Value>999888*</Value>
          </Node>
          <Node>
            <NodeName>EAPType</NodeName>
            <Value>23</Value>
          </Node>
        </Node>
      </Node>
    </Node>
  </Node>
</MgmtTree>

Auth advisory

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.

Workarounds

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.

  1. Add the NAI realm ANQP element.
  2. Set the NAI realm subfield to match the Realm of the profile installed on the device.

  3. Set the following information based on each EAP type:

    • EAP-TTLS: Set EAPMethod(21) and supported inner auth types (PAP, CHAP, MS-CHAP, or MS-CHAP-V2)
    • EAP-TLS: Set EAPMethod(13)
    • EAP-SIM: Set EAPMethod(18)
    • EAP-AKA: Set EAPMethod(23)
    • EAP-AKA': Set EAPMethod(50)

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.