Closing the protocol gap

This is the thrid article in the series The protocol gap. In the first two articles we’ve shown the difficulties that guest devices have to communicate with captive portals and the proposed solution for this problem by defining a new interface in RFC capport-architecture. To be precise, the IETF does not define a new protocol with this RFC, it defines a new interface over known protocols like DHCP, IPv6 RA and HTTPS.

Differences to the previous shown version

In the previous article in this series we’ve already shown the flow and API, but some things have changed since then (Jan 2019):

ICMP was replaced with a more generic term “Captive Portal Signal” which is not specified any further in this version. This is suspended to a later point in time and needs more discussion as there was no consense if this is good thing or not. We think this is fine for now, as the provisioning and API parts are covered and simple to implement.
The DHCPv4 option 160 was replaced by 114 because a test has shown that it’s used (illegaly) in the wild. Apple donated this option which was never actively used.
Also the API has renamed and new JSON fields (see new fields below).

How it works

Here’s the current flow when a device enters the network:

1. The enduser device gets provisioned with initial network settings like IP, subnet mask, gateway, DNS server, … via DHCP. There is also a variation using PvD (Provisioning Domains) discussed. The device learns a URL of the CAPPORT API server via a new DHCP option (DHCP6 and RA for IPv6) defined in RFC-8910 (a new version of RFC-7710-bis).

2. The device asks the CAPPORT API server about the current restrictions and learns an URL for a webpage suited for humans. This page can consist of a login form, needed payment, or any other information.

3. The device opens a (captive) browser and presents the login page to the user.

4. Finally if the requirements of the captive portal are satisfied by the enduser, the device is set online and allowed to access the internet.

5. The device can send traffic now. But if the device is not allowed to access the internet the captive portal can optionally send a “signal”. The current state of this capport interface does not specify what this signal is. So this is not implemented on any side right now.

The capport API

The capport API defined in RFC-8908 allows the client to interact with a captive portal over a typical HTTP API with JSON as data format. It’s mandatory to use HTTPS (HTTP over TLS – at least version 1.2). While the client device already knows that it’s behind a captive portal it now wants to get the current state and some details about the captivity. One important thing the API has to deliver is an URL for a webpage that is presented to the user with a login page or any other information.

An example request and response could look like this:

GET / capport_api HTTP/1.1
Host: hotspot.internet-for-guests.com
Accept: application/captive+json

The server then responds with the JSON content for that client:

HTTP/1.1 200 OK
Cache-Control: private
Date: Mon, 06 Jul 2020 10:07:35 GMT
Content-Type: application/captive+json

{
“captive”: false,
“user-portal-url”:”https://hotspot.internet-for-guests.com”,
“seconds-remaining”: 10000,
“bytes-remaining”: 100000000,
}

Of course this only makes sense if Google and Apple are registering them and (hopefully) using them in the same way.

3, 2, 1, go!

After waiting for a long time we’ve been surprised to see announcments of Apple and Google in 2020 to support the new capport architecture in their newest releases.

Apple already added support in iOS and macOS 14
Google is supporting it with Android 11/R released recently (September 2020)
Your IACBOX is ready for the new API by updating to the latest version right now. Stay secure and up-2-date with our software maintenance.

Outlook

So, we’re done? Not yet – there are multiple things upen that will probably need years to be resolved. The old HTTP based connection checks will remain present as not all captive portals will support this API so we will see a parallel use for years.
Also the first implementations do not include the informational parts of the API like the venue URL or the seconds- and bytes-remaining entries which would be the real benefit.
The capport RFC is currently in the final stage and should be released soon and finally get an official number.
We will update the IACBOX to support newly added API fields as soon as they are released – so stay u2date.

Are you an entrepreneur looking for a solution to these requirements? Or are you a service provider and advise companies on wireless or wired network solutions?