Current state of the capport RFC

This is the second article in the series “The protocol gap”. In the first post we’ve shown the difficulties that guest devices have to communicate with captive portals because there is no standardized protocol for this situation. It’s recommended to read that blog post first if you haven’t done yet.

Define the problem space

Before this IETF working group started they tried to define a problem statement which lists what captive portals are used for and which problems they introduce. Captive portals are used to authenticate users, show the terms-of-service, enforcing different bandwidths per user, showing a privacy policy (GDPR) or other information and so on. Also statistics about the usage of the WiFi can be of interest to the operator. Because there is no standardized way of doing this, many workarounds and network manipulations are currently used as described in our first blog post in this series.

A new standard

The capport working group now wants to come up with additions to present protocols (like ICMP) and a new interface (API) to provide a standardized way how to communicate.

It’s important to state that this is an unfinished RFC draft and represents the current state in January 2019. Different approaches and opinions have been discussed how the communication between a client device and a captive portal should be done and the discussion is still ongoing.

The following flow chart shows the interaction between the involved parts.

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 the already released RFC-7710 (with a small addition RFC-7710bis).

2. If the device does not implement this new standard it does not know what to do with this DHCP option (160) and this URL, so it will start sending traffic. Another case is when the device was taken offline by the captive portal and it hasn’t realized that it’s blocked again it will send traffic too.

3. In the case of step 2. the captive portal now sends an ICMP message to tell the enduser device that it’s not allowed to send traffic. Devices that understand such an ICMP message now know that they have to ask the CAPPORT API server about the current state. Other devices will ignore that message.

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

5. The device now opens a (captive) browser and presents the login page to the user if a URL was provided in step 4.

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

Backwards compatibility

When this new standard is finished and is rolled out with the newest devices and operating system versions, there will be legacy devices around for many years that are not able to interact with the CAPPORT API. The old behavior (redirecting HTTP traffic of offline clients) still needs to be supported. The current document suggests to send the ICMP responses anyway. First it’s not clear if the client is able to understand the new API and secondly a device/OS maybe does both, the connectivity check and the API check.

Why ICMP?

ICMP was the big surprise for us in this draft but lets see why this seems to be the right choice. If a client device has not been allowed to access the Internet (yet) it has to be notified about that. The device opens any connection on top of IP and is blocked by the captive portal. With ICMP there’s a way to notify the client without depending on a certain protocol on higher layers like the current proprietary connections checks depend on unencrypted HTTP. So for example the first connection of a client device was an SMTP connection to a mail server and the captive portal can now answer with an ICMP message notifying it about the captivity.
Another interesting thing to note about the ICMP notification is that it’s not containing an URL to the capitve API because this would allow easy attacks. The URL for the API is transmitted via the DHCP option (RFC-7710). Of course DHCP is not secure too and can be forged but this new additions will at least not lower the security barrier.

The CAPPORT API

The CAPPORT API 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 loginpage or any other information.

An example request and response could look like this:

GET/captive-portal/api/X54PD
Host: example.org
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, 04 Dec 2018 05:07:35 GMT
Content-Type: application/captive+json
{
     “permitted”: false,
     “user-portal-url”: “https://example.org/portal”
     “expire-date”: “2019-01-01T23:28:56. 782Z”
}

This is of course only a draft but clearly shows where it will lead us.

Online or not?

At the moment there’s a debate if the captive portal can signal a device only a binary state – online or offline – in comparison to a more differentiated version where the device can learn that it’s allowed to access certain resources (like in a walled garden) but is not able to connect to any server on the Internet. We would prefer the latter one as captive portals are mainly used in environments with some restrictions.

Outlook

The current state of the document looks promising to us as manufacturer and we are eager to implement it when there’s a first version out there. The lack of support for RFC-7710 has shown that it depends on the two big mobile OS vendors – Google and Apple – if all this can be used some day. Just looking at the email addresses it looks like there are people from both companies participating, so we’re still hoping.

There is an update to this article.