Current status of the capport RFC

Closing the protocol gap

This is the second article in our series The Protocol Gap. In the first post, we highlighted how difficult communication between end devices and the captive portal is, as there is no standardized procedure for it. If you haven’t already, we recommend reading the first blog post on this topic first.

Defining the problem space

Before the IETF working group began its work, an attempt was made to create a problem definition explaining what captive portals are for and what problems they entail. Captive portals are used to authenticate users, provide terms of service, the privacy policy (GDPR), or other information, or to enforce different bandwidths per device, etc. Statistics on WiFi usage behavior could also be of interest to the provider in this context. And since there is no standardized way to do all this, many workarounds and network traffic manipulations must be performed, which were described in our first blog post of this series.

A new standard

To counteract this, the Capport working group now wants to present a supplement to existing protocols (such as ICMP) and a new interface (API) to provide a standardized way of communication.

It should be noted that this is an unfinished draft of this RFC and represents the status as of January 2019.

The following diagram shows the interaction between the parties involved.

1. The end user’s device receives basic network settings such as IP, subnet mask, gateway, DNS server, etc., via DHCP. A variant with PvD (Provisioning Domains) is also currently being discussed. The device additionally receives the URL of the CAPPORT API server via a new DHCP option (DHCP6 and RA for IPv6), which is defined in the already published RFC-7710 (with a small change in RFC-7710bis).

2. If the device does not support this new standard, it does not know what to do with these DHCP options (160) and this URL and will begin to establish connections. Even if the device has been taken offline by the captive portal and does not recognize this immediately, it will continue to try to establish connections.

3. In the case of step 2, the captive portal will send an ICMP message to inform the end user’s device that it is not allowed to send traffic. Devices that can understand such an ICMP message know that they must ask the CAPPORT API server for the current status. Other devices will simply ignore this message.

4. The device asks the CAPPORT API server for the current restrictions and also receives an optional URL for a login page suitable for users. This page can show a login form, payment modalities, or other information.

5. If a URL was provided in step 4, the device now opens a (captive) browser and shows the user the login page.

6. Once the requirements of the captive portal are finally met by the user, the device is taken online and is allowed to access the internet.

Backward compatibility

When this new standard is fully developed and rolled out on the latest versions of devices and operating systems, there will still be old devices for years with which no interaction with the CAPPORT API will be possible. The previous procedure (redirecting HTTP traffic from offline users) must continue to be supported. The current document suggests still sending the ICMP responses because, on the one hand, it is initially unclear whether the client is able to understand the new interface, and on the other hand, a device/operating system might both perform the old connection check and attempt to access the new API.

Why ICMP?

ICMP was the big surprise for us in this draft – yet we consider it the right choice. If a device is denied network access (so far), it must be informed about it. The device opens every connection via IP and is blocked by the captive portal. With ICMP, there is a way to notify the client without being dependent on a specific higher-level protocol, such as the current proprietary connection check via unencrypted HTTP. For example, if a device’s first connection was an SMTP connection to a mail server, the captive portal can now respond with an ICMP message and thereby communicate the restrictions to the device.
An interesting aspect of the ICMP notification is that it does not contain a URL to the captive API, as this would enable simple attacks. The URL for the API is transmitted via the DHCP option (RFC-7710). Of course, DHCP is also not secure and can be forged, but these new additions will at least not lower the security barrier.

The CAPPORT interface

With the CAPPORT API, the client can communicate with a captive portal via a classic HTTP interface using JSON as the data format. It is necessary to use HTTPS (HTTP over TLS – version 1.2 or higher). While the device already knows it is behind a captive portal, it now wants to retrieve the current status and some details regarding network restriction. Primarily, the interface must provide a URL for the login page, but also other optional 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 this JSON content for this 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”
}

All of this is, of course, a draft, but it clearly shows what this interface can offer us.

Online or not?

There is currently a debate as to whether the captive portal can only signal a binary state to a device – online or offline – compared to a differentiated version where the device can recognize that it is allowed to access certain resources (as in a walled garden) but cannot establish a connection to other servers on the internet. We would clearly prefer the latter, as captive portals are mainly used in environments with many restrictions.

Outlook

The current status looks promising to us as a manufacturer, and we are very interested in implementing this interface as soon as a first version is available. The lack of support for RFC-7710 has shown that it depends on the two major mobile operating system providers – Google and Apple – whether all of this can be used one day. Looking at the list of email addresses of the IETF working group participants, it appears that people from both companies are involved, so we can continue to hope.

You can find the update to this article here.