RFC 8952
Captive Portal Architecture
RFC 8952: Captive Portal Architecture 🎀
okay bestie, this one is the RFC for captive portal architecture 🧠 and the authors are K. Larose (Agilicus), D. Dolson, and H. Liu (Google). It's Request for Comments: 8952, published as Informational (so not a Standards Track spec 👀), out of the Internet Engineering Task Force (IETF) stream, with ISSN 2070-1721, dated November 2020. It doesn't obsolete or update anything, so it's a fresh start ✨
Abstract ✨
so the vibe of this doc is that it lays out a whole captive portal architecture 🏰 Network provisioning protocols like DHCP or Router Advertisements (RAs), plus an optional signaling protocol and an HTTP API, are how it all comes together 💅
Status of This Memo 📜
this one is NOT an Internet Standards Track spec 🙈 it's just published for information. It's still an IETF product, though, which means it has the IETF community's consensus 🫶 It got public review and got approved by the Internet Engineering Steering Group (IESG). Not every IESG-approved doc is up for any level of Internet Standard, so check Section 2 of RFC 7841 if you want the deets 🧚
If you want the current status, any errata, or to send feedback, go to https://www.rfc-editor.org/info/rfc8952 💜
Copyright Notice ⚖️
Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved 🌈
This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stood on the publication date. Read those carefully, because they spell out what you can and can't do with it 🙏 And any Code Components pulled out of this doc have to include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions. They come with no warranty, same as the Simplified BSD License says 🔥
Table of Contents 🗂️
1. Introduction
1.1. Requirements Language
1.2. Terminology
2. Components
2.1. User Equipment
2.2. Provisioning Service
2.2.1. DHCP or Router Advertisements
2.2.2. Provisioning Domains
2.3. Captive Portal API Server
2.4. Captive Portal Enforcement Device
2.5. Captive Portal Signal
2.6. Component Diagram
3. User Equipment Identity
3.1. Identifiers
3.2. Recommended Properties
3.2.1. Uniquely Identify User Equipment
3.2.2. Hard to Spoof
3.2.3. Visible to the API Server
3.2.4. Visible to the Enforcement Device
3.3. Evaluating Types of Identifiers
3.4. Example Identifier Types
3.4.1. Physical Interface
3.4.2. IP Address
3.4.3. Media Access Control (MAC) Address
3.5. Context-Free URI
4. Solution Workflow
4.1. Initial Connection
4.2. Conditions about to Expire
4.3. Handling of Changes in Portal URI
5. IANA Considerations
6. Security Considerations
6.1. Trusting the Network
6.2. Authenticated APIs
6.3. Secure APIs
6.4. Risks Associated with the Signaling Protocol
6.5. User Options
6.6. Privacy
7. References
7.1. Normative References
7.2. Informative References
Appendix A. Existing Captive Portal Detection Implementations
Acknowledgments
Authors' Addresses1. Introduction 🌸
okay so in this doc, "Captive Portal" means a network a device may voluntarily join, but its network access is limited until some requirements get fulfilled 🚧 Usually that means using a web browser to do stuff the network operator asks for, like reading ads, accepting an acceptable-use policy, or giving some kind of credentials 📝
Captive portal implementations generally need a web server, some way to allow or block traffic, and some way to alert the user 🚨 Before this work, the usual alerting methods messed with HTTP or DNS traffic 😬
This doc describes an architecture for building captive portals that fixes most of the problems with current captive portal mechanisms 💖 It's guided by these requirements:
- Current captive portal solutions usually do some version of forging DNS or HTTP responses. Some even try man-in-the-middle (MITM) proxying of HTTPS to forge stuff. Captive portal solutions should not have to break any protocols or otherwise act like an attacker. So solutions MUST NOT require the forging of responses from DNS or HTTP servers or from any other protocol 🙅♀️
- Solutions MUST permit clients to perform DNSSEC validation, which rules out solutions that forge DNS responses. Solutions SHOULD permit clients to detect and avoid TLS man-in-the-middle attacks without requiring a human to perform any kind of "exception" processing 🔐
- To maximize universality and adoption, solutions MUST operate at the layer of Internet Protocol (IP) or above, not being specific to any particular access technology such as cable, Wi-Fi, or mobile telecom 📡
- Solutions SHOULD allow a device to query the network to determine whether the device is captive, without the solution being coupled to forging intercepted protocols or requiring the device to make sacrificial queries to "canary" URIs to check for response tampering (see Appendix A). Current captive portal solutions that work by affecting DNS or HTTP generally only function as intended with browsers, breaking other applications using those protocols. Applications using other protocols are not alerted that the network is a captive portal 😭
- The state of captivity SHOULD be explicitly available to devices via a standard protocol, rather than having to infer the state indirectly 🧃
- The architecture MUST provide a path of incremental migration, acknowledging the existence of a huge variety of pre-existing portals and end-user device implementations and software versions. This requirement is not to recommend or standardize existing approaches, but rather to provide device and portal implementors a path to a new standard 🦋
A side benefit here is that devices without user interfaces can still figure out the parameters of their captivity 🧚 However, this doc doesn't describe a mechanism for those devices to negotiate for unrestricted network access. A future document could solve that for devices without UIs. This doc focuses on devices with user interfaces 💅
The architecture uses these mechanisms:
- Network provisioning protocols give end-user devices a Uniform Resource Identifier (URI) [RFC3986] for the API they query to learn what's required to escape captivity 🔑 DHCP, DHCPv6, and Router Advertisement options for this purpose are available in [RFC8910]. Other protocols (such as RADIUS), Provisioning Domains [CAPPORT-PVD], or static configuration may also be used to convey this Captive Portal API URI. A device MAY query this API at any time to determine whether the network is holding the device in a captive state 👀
- A Captive Portal can signal User Equipment in response to transmissions by the User Equipment. This signal works in response to any Internet protocol and is not done by modifying protocols in band 📣 The signal does not carry the Captive Portal API URI. Instead, it just tells the User Equipment that it's in a captive state 🙈
- Getting a Captive Portal Signal is a hint that User Equipment could be captive 💡 In response, the device MAY query the provisioned API to get info about the network state. The device can take immediate action to satisfy the portal (according to its configuration/policy) 🏃♀️
The architecture tries to provide confidentiality, authentication, and safety mechanisms to the extent possible 🔒
1.1. Requirements Language 🔑
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🧠 Lowercase versions are just regular words, bestie 🫶
1.2. Terminology 📖
Captive Portal A network that limits the communication of attached devices to restricted hosts until the user has satisfied Captive Portal Conditions, after which access is permitted to a wider set of hosts (typically the Internet).
Captive Portal Conditions Site-specific requirements that a user or device must satisfy in order to gain access to the wider network.
Captive Portal Enforcement Device The network equipment that enforces the traffic restriction. Also known as "Enforcement Device".
Captive Portal User Equipment A device that has voluntarily joined a network for purposes of communicating beyond the constraints of the Captive Portal. Also known as "User Equipment".
User Portal The web server providing a user interface for assisting the user in satisfying the conditions to escape captivity.
Captive Portal API An HTTP API allowing User Equipment to query information about its state of captivity within the Captive Portal. This information might include how to obtain full network access (e.g., by visiting a URI). Also known as "API".
Captive Portal API Server A server hosting the Captive Portal API. Also known as "API Server".
Captive Portal Signal A notification from the network used to signal to the User Equipment that the state of its captivity could have changed.
Captive Portal Signaling Protocol The protocol for communicating Captive Portal Signals. Also known as "Signaling Protocol".
Captive Portal Session Also referred to simply as the "Session", a Captive Portal Session is the association for a particular User Equipment instance that starts when it interacts with the Captive Portal and gains open access to the network and ends when the User Equipment moves back into the original captive state. The Captive Network maintains the state of each active Session and can limit Sessions based on a length of time or a number of bytes used. The Session is associated with a particular User Equipment instance using the User Equipment's identifier (see Section 3) 🎀
2. Components 🧩
2.1. User Equipment
okay so the User Equipment is basically the device a user wants to hook up to a network so they get full access to everything, like the internet 💖 The Enforcement Device (more on that in Section 2.4 🧚) usually keeps the User Equipment's traffic restricted until the site-specific requirements are met.
This doc only looks at devices with web browsers, since web apps are how you satisfy the Captive Portal Conditions. A smart phone is the classic example 📱✨
The User Equipment:
- SHOULD support provisioning of the URI for the Captive Portal API (e.g., by DHCP). 🎀
- SHOULD distinguish Captive Portal API access per network interface, in the manner of Provisioning Domain Architecture [RFC7556]. 🦋
- SHOULD have a non-spoofable mechanism for notifying the user of the Captive Portal. 🫶
- SHOULD have a web browser so that the user may navigate to the User Portal. 🌸
- SHOULD support updates to the Captive Portal API URI from the Provisioning Service. 🍓
- MAY prevent applications from using networks that do not grant full network access. For example, a device connected to a mobile network may be connecting to a captive Wi-Fi network; the operating system could avoid updating the default route to a device on the captive Wi-Fi network until network access restrictions have been lifted (excepting access to the User Portal) in the new network. This has been termed "make before break". 💅
None of the above requirements are mandatory because (a) we do not wish to say users or devices must seek full access to the Captive Portal, (b) the requirements may be fulfilled by manually visiting the captive portal web application, and (c) legacy devices must continue to be supported. ngl that's super considerate of legacy devices 🥺🌈
If User Equipment supports the Captive Portal API, it MUST validate the API Server's TLS certificate (see [RFC2818]) according to the procedures in [RFC6125]. The API Server's URI is obtained via a network provisioning protocol, which will typically provide a hostname to be used in TLS server certificate validation, against a DNS-ID in the server certificate. If the API Server is identified by IP address, the iPAddress subjectAltName is used to validate the server certificate. An Enforcement Device SHOULD allow access to any services that User Equipment could need to contact to perform certificate validation, such as Online Certificate Status Protocol (OCSP) responders, Certificate Revocation Lists (CRLs), and NTP servers; see Section 4.1 of [RFC8908] for more information. If certificate validation fails, User Equipment MUST NOT make any calls to the API Server. 🔐💀
The User Equipment can store the last response it received from the Captive Portal API as a cached view of its state within the Captive Portal. This state can be used to determine whether its Captive Portal Session is near expiry. For example, the User Equipment might compare a timestamp indicating when the Session expires to the current time. Storing state in this way can reduce the need for communication with the Captive Portal API. However, it could lead to the state becoming stale if the User Equipment's view of the relevant conditions (byte quota, for example) is not consistent with the Captive Portal API's. 🧠✨
2.2. Provisioning Service
the Provisioning Service is mainly in charge of handing the User Equipment a Captive Portal API URI when it connects to the network, and again later if that URI changes. It could also be the same service that sets up the User Equipment for Captive Portal access (e.g., by giving it an IP address). This section covers two mechanisms that may be used to deliver the Captive Portal API URI to the User Equipment. 👑
2.2.1. DHCP or Router Advertisements
A standard for providing a Captive Portal API URI using DHCP or Router Advertisements is described in [RFC8910]. The captive portal architecture expects this URI to indicate the API described in Section 2.3. 🌷
2.2.2. Provisioning Domains
[CAPPORT-PVD] proposes a mechanism for User Equipment to be provided with Provisioning Domain (PvD) Bootstrap Information containing the URI for the API described in Section 2.3. 🦄
2.3. Captive Portal API Server
the whole point of a Captive Portal API is to let you check the Captive Portal state without interrupting the user 🙌 It basically gets rid of the need for User Equipment to send clear-text "canary" (see Appendix A) queries just to check whether someone is tampering with responses. 🕵️♀️
The URI of this API will have been provisioned to the User Equipment. (Refer to Section 2.2.)
This architecture expects the User Equipment to query the API when the User Equipment attaches to the network and multiple times thereafter. Therefore, the API MUST support multiple repeated queries from the same User Equipment and return the state of captivity for the equipment. 🔁
At minimum, the API MUST provide the state of captivity. Further, the API MUST be able to provide a URI for the User Portal. The scheme for the URI MUST be "https" so that the User Equipment communicates with the User Portal over TLS. 🔒
If the API receives a request for state that does not correspond to the requesting User Equipment, the API SHOULD deny access. Given that the API might use the User Equipment's identifier for authentication, this requirement motivates Section 3.2.2. 🙅♀️
A caller to the API needs to be presented with evidence that the content it is receiving is for a version of the API that it supports. For an HTTP-based interaction, such as in [RFC8908], this might be achieved by using a content type that is unique to the protocol. 🎯
When User Equipment receives Captive Portal Signals, the User Equipment MAY query the API to check its state of captivity. The User Equipment SHOULD rate-limit these API queries in the event of the signal being flooded. (See Section 6.) 🚦
The API MUST be extensible to support future use cases by allowing extensible information elements. 🧩
The API MUST use TLS to ensure server authentication. The implementation of the API MUST ensure both confidentiality and integrity of any information provided by or required by it. 🛡️
This document does not specify the details of the API. 🤷♀️
2.4. Captive Portal Enforcement Device
The Enforcement Device component restricts the network access of User Equipment according to the site-specific policy. Typically, User Equipment is permitted access to a small number of services (according to the policies of the network provider) and is denied general network access until it satisfies the Captive Portal Conditions. 🚧
The Enforcement Device component:
- Allows traffic to pass for User Equipment that is permitted to use the network and has satisfied the Captive Portal Conditions. ✅
- Blocks (discards) traffic according to the site-specific policy for User Equipment that has not yet satisfied the Captive Portal Conditions. 🚫
- Optionally signals User Equipment using the Captive Portal Signaling Protocol if certain traffic is blocked. 📣
- Permits User Equipment that has not satisfied the Captive Portal Conditions to access necessary APIs and web pages to fulfill requirements for escaping captivity. 🗝️
- Updates allow/block rules per User Equipment in response to operations from the User Portal. 🔄
2.5. Captive Portal Signal
When User Equipment first connects to a network, or when there are changes in status, the Enforcement Device could generate a signal toward the User Equipment. This signal indicates that the User Equipment might need to contact the API Server to receive updated information. For instance, this signal might be generated when the end of a Session is imminent or when network access was denied. For simplicity, and to reduce the attack surface, all signals SHOULD be considered equivalent by the User Equipment as a hint to contact the API. If future solutions have multiple signal types, each type SHOULD be rate-limited independently. 📶
An Enforcement Device MUST rate-limit any signal generated in response to these conditions. See Section 6.4 for a discussion of risks related to a Captive Portal Signal. ⚠️
2.6. Component Diagram
okay bestie, this diagram is giving full architecture glow-up ✨🖼️ It shows how every component talks to the others when the Captive Portal has a User Portal and the User Equipment decides to visit it after finding and poking the API Server 💅
o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . o
. CAPTIVE PORTAL .
. +------------+ Join Network +--------------+ .
. | |+--------------------------->| Provisioning | .
. | | Provision API URI | Service | .
. | |<---------------------------+| | .
. | User | +--------------+ .
. | Equipment | Query captivity status +-------------+ .
. | |+--------------------------->| API | .
. | | Captivity status response | Server | .
. | |<---------------------------+| | .
. | | +------+------+ .
. | | | Status .
. | | Portal UI page requests +------+------+ .
. | |+--------------------------->| | .
. | | Portal UI pages | User Portal | .
. | |<---------------------------+| | .
. +------------+ | | .
. ^ ^ | +-------------+ .
. | | | Data to/from ext. network | .
. | | +-----------------> +---------------+ Allow/Deny .
. | +--------------------+| | Rules .
. | | Enforcement | | .
. | Captive Portal Signal | Device |<----+ .
. +-------------------------+---------------+ .
. ^ | .
. | | .
. Data to/from external network .
. | | .
o . . . . . . . . . . . . . . . . . . .| |. . . . . . . . . . . o
| v
EXTERNAL NETWORK
Figure 1: Captive Portal Architecture Component DiagramHere's the tea on what's happening in the diagram 🫖💖
- During provisioning (e.g., DHCP), and possibly later, the User Equipment grabs the Captive Portal API URI 🎀
- The User Equipment checks the API to find out its captivity status. If it's captive, the User Equipment shows the portal UI from the User Portal to the user 👀
- Based on what the user does, the User Portal tells the Enforcement Device to either allow or deny external network access for the User Equipment 🚦
- The User Equipment tries to talk to the external network through the Enforcement Device 📡
- The Enforcement Device either lets the User Equipment's packets reach the external network or blocks them. If it's blocking traffic and a signal has been implemented, it may respond with a Captive Portal Signal 🛑✨
The Provisioning Service, API Server, and User Portal are described as discrete functions, but one implementation might bundle several of them into a single entity 🧚 And honestly, these functions (combined or not) plus the Enforcement Device could all be replicated for redundancy or scale. Main character energy for infrastructure 👑
3. User Equipment Identity 🪪
Okay so, multiple components in this architecture interact with both the User Equipment and with each other. Since the User Equipment is the star of every single one of these interactions, the components have to be able to identify it from how it's behaving, and they also have to agree on who it is when they're talking to each other 💅
The methods the components use to interact limit what kind of information can be used as an identifying characteristic. This section breaks down those identifying characteristics 🦋
3.1. Identifiers
An identifier is a characteristic of the User Equipment that the components of a Captive Portal use to uniquely figure out which specific User Equipment instance is interacting with them 🔍 An identifier can be a field inside packets the User Equipment sends to the external network. Or it can be an ephemeral property that isn't in those packets at all, but gets matched up with that information through knowledge the different components have 🧩
3.2. Recommended Properties
The set of possible identifiers is super big, ngl 🌈 But to be considered a good identifier, an identifier SHOULD meet the criteria below. The optimal identifier will probably change depending on where the components sit in the network and what information they have access to, so don't assume one size fits all 🫶 An identifier SHOULD:
- uniquely identify the User Equipment ✨
- be hard to spoof 🛡️
- be visible to the API Server 👀
- be visible to the Enforcement Device 🚦
Also, an identifier might only apply to the current point of network attachment. If the device moves to a different network location, its identity could change 🦋
3.2.1. Uniquely Identify User Equipment
The Captive Portal MUST associate the User Equipment with an identifier that is unique among all of the User Equipment interacting with the Captive Portal at that time 💖
Over time, the User Equipment assigned to an identifier value MAY change. Letting the identified device change over time keeps the space of possible identifying values from needing to be overly large 🧠
Independent Captive Portals MAY use the same identifying value to identify different User Equipment instances. Letting independent captive portals reuse identifying values means the identifier can be a property of the local network, which expands the space of possible identifiers 🌸
3.2.2. Hard to Spoof
A good identifier doesn't lend itself to being easily spoofed 🙅♀️ At no time should it be simple or straightforward for one User Equipment instance to pretend to be another, whether or not both are active at the same time. This matters even more when the User Equipment identifier gets referenced externally by things like billing systems, or when the identity of the User Equipment could imply liability 💀
Spoofing is a whole mess, bestie. Keep that identifier locked down 🔒
3.2.3. Visible to the API Server
The API Server has to do operations that rely on the identity of the User Equipment, like answering a query about whether the User Equipment is captive. So the API Server needs to be able to connect a request to the User Equipment that made it 🫶
3.2.4. Visible to the Enforcement Device
The Enforcement Device decides on a per-packet basis whether a packet should be forwarded to the external network 🚦 Since that decision depends on which User Equipment instance sent the packet, the Enforcement Device needs to be able to map each packet to its concept of the User Equipment 🧚
3.3. Evaluating Types of Identifiers
To evaluate whether a type of identifier is appropriate, one should consider every recommended property from the perspective of interactions among the components in the architecture 🔬 When comparing identifier types, choose the one that best satisfies all of the recommended properties. The architecture doesn't give an exact measure of how well an identifier type satisfies a given property, so care should be taken when doing the evaluation 🙈
3.4. Example Identifier Types
This section gives some example identifier types, along with some evaluation of whether they're suitable 📝 The list isn't exhaustive, and other types may be used too. Important point: whether a given identifier type is suitable depends heavily on the capabilities of the components and on where in the network they live 🌍
3.4.1. Physical Interface
The physical interface the User Equipment is attached to the network with can be used to identify the User Equipment 🔌 This identifier type is extremely difficult to spoof, because the User Equipment isn't aware of the property, so one User Equipment instance can't manipulate its interactions to look like another 😭
If only a single User Equipment instance is attached to a given physical interface, the identifier will be unique 🥰 But if multiple User Equipment instances are attached to the network on the same physical interface, this type is not appropriate 🙅♀️
Another thing to keep in mind about uniqueness is that if the attached User Equipment changes, both the API Server and the Enforcement Device MUST invalidate their state related to the User Equipment 🧹
The Enforcement Device needs to be aware of the physical interface, which constrains the environment. It must either be part of the device providing physical access (e.g., implemented in firmware), or packets traversing the network must be extended to include information about the source physical interface (e.g., a tunnel) 🛠️
The API Server faces a similar problem, which implies it should co-exist with the Enforcement Device, or that the Enforcement Device should extend requests to it with the identifying information 🫖💅
3.4.2. IP Address 🌸
okay so the IP address of the User Equipment is a super natural identifier to consider 🦋 at any given moment, no two devices on the network can share an IP address without the whole network glitching out, so it's giving uniqueness energy ✨
ngl it can be spoofed though 💀, especially by bad actors who don't even need the network to work properly for their plans. So any solution using the IP address SHOULD proactively try to prevent spoofing of the IP address. Similarly, if the mapping of IP address to User Equipment is changed, the components of the architecture MUST remove or update their mapping to prevent spoofing. Return routability, like the check that TCP connection establishment does, might be enough defense against spoofing 🛡️ but that might not be enough on networks that use broadcast media (like some wireless networks) 🙈
Since the IP address may traverse multiple segments of the network, the Enforcement Device and the API Server get more flexibility 💅 they simply must exist on a segment of the network where the IP address is still unique. But consider that a NAT may be deployed between the User Equipment and the Enforcement Device. In that case, the components can still uniquely identify the device if they know the port mapping 🧚
In some situations, the User Equipment may have multiple IP addresses (either IPv4, IPv6, or a dual-stack [RFC4213] combination) and still satisfy all of the recommended properties 👑 This raises some challenges for the components of the network. For example, if the User Equipment tries to access the network with multiple IP addresses, should the Enforcement Device and API Server treat each IP address as a unique User Equipment instance, or should they tie the multiple addresses together into one view of the subscriber? An implementation MAY do either. Attention should be paid to IPv6, since it's expected for a device to have multiple IPv6 addresses on a single link. In such cases, identification could be performed by subnet, such as the /64 to which the IP belongs 🍓
3.4.3. Media Access Control (MAC) Address 💜
The MAC address of a device is often used as an identifier in existing implementations. This document doesn't discuss the use of MAC addresses within a captive portal system, but they can be used as an identifier type, subject to the criteria in Section 3.2.
3.5. Context-Free URI 🎀
A Captive Portal API needs to present information that is unique to each client. To do this, some systems use information from the context of a request, such as the source address, to identify the User Equipment.
Using information from context rather than information from the URI lets the same URI be used for different clients ✨ However, it also means the resource can't provide relevant information if the User Equipment makes a request using a different network path. This might happen when the User Equipment has multiple network interfaces. It might also happen if the address of the API provided by DNS depends on where the query originates (as in split DNS [RFC8499]) 🌈
Accessing the API MAY depend on contextual information. However, the URIs provided in the API SHOULD be unique to the User Equipment and not dependent on contextual information to function correctly 💖
A URI might still resolve correctly when the User Equipment makes the request from a different network, but some functions could be limited to requests made using the Captive Portal. For example, payment options could be missing, or a warning could be displayed to indicate the payment is not for the current connection 💸
URIs could include some means of identifying the User Equipment. However, including unauthenticated User Equipment identifiers in the URI may expose the service to spoofing or replay attacks 😭
4. Solution Workflow 🧚
This section aims to improve understanding by describing a possible workflow of solutions that adhere to the architecture. Note that this section is not normative; it describes only a subset of possible implementations 🫶
4.1. Initial Connection 🦋
This section describes a possible workflow when the User Equipment first joins a Captive Portal.
- The User Equipment joins the Captive Portal by acquiring a DHCP lease, RA, or similar, acquiring provisioning information.
- The User Equipment learns the URI for the Captive Portal API from the provisioning information (e.g., [RFC8910]).
- The User Equipment accesses the Captive Portal API to receive parameters of the Captive Portal, including the User Portal URI. (This step replaces the clear-text query to a canary URI.)
- If necessary, the user navigates to the User Portal to gain access to the external network.
- If the user interacted with the User Portal to gain access to the external network in the previous step, the User Portal indicates to the Enforcement Device that the User Equipment is allowed to access the external network.
- The User Equipment attempts a connection outside the Captive Portal.
- If the requirements have been satisfied, the access is permitted; otherwise, the "Expired" behavior occurs.
- The User Equipment accesses the network until conditions expire.
4.2. Conditions about to Expire ⏰
This section describes a possible workflow when access is about to expire.
- Precondition: the API has provided the User Equipment with a duration over which its access is valid.
- The User Equipment is communicating with the outside network.
- The User Equipment detects that the length of time left for its access has fallen below a threshold by comparing its stored expiry time with the current time.
- The User Equipment visits the API again to validate the expiry time.
- If expiry is still imminent, the User Equipment prompts the user to access the User Portal URI again.
- The user accepts the prompt displayed by the User Equipment.
- The user extends their access through the User Portal via the User Equipment's user interface.
- The User Equipment's access to the outside network continues uninterrupted 🥰
4.3. Handling of Changes in Portal URI 🔄
A different Captive Portal API URI could be returned in the following cases:
- If DHCP is used, a lease renewal/rebind may return a different Captive Portal API URI.
- If RA is used, a new Captive Portal API URI may be specified in a new RA message received by end User Equipment.
When the Provisioning Service updates the Captive Portal API URI, the User Equipment can retrieve updated state from the URI immediately, or it can wait as it normally would until the expiry conditions it retrieved from the old URI are about to expire.
5. IANA Considerations 📋
This document has no IANA actions.
6. Security Considerations 🔐
Okay, this section is serious, so let's be serious for a sec 🫶 Everything below matters a lot.
6.1. Trusting the Network 🤝
When joining a network, some trust is placed in the network operator. This is usually a decision a user makes based on the reputation of an organization. However, once a user makes that decision, protocols can support authenticating that a network is operated by who it claims to be operated by. The Provisioning Domain Architecture [RFC7556] has some discussion on authenticating an operator.
The user makes an informed choice to visit and trust the Captive Portal URI. Since the network provides the Captive Portal URI to the User Equipment, the network SHOULD do so securely, so that the user's trust in the network can extend to their trust of the Captive Portal URI. For example, the DHCPv6 AUTH option can sign this information.
If a user decides to incorrectly trust an attacking network, they might be convinced to visit an attacking web page and unwittingly provide credentials to an attacker. Browsers can authenticate servers, but they can't detect cleverly misspelled domains, for example 😱
Further, the possibility of an on-path attacker in an attacking network introduces some risks. The attacker could redirect traffic to arbitrary destinations. The attacker could analyze the user's traffic, leading to loss of confidentiality, or the attacker could modify the traffic inline 👀
6.2. Authenticated APIs 🔑
The solution described here requires that, when the User Equipment needs to access the API Server, the User Equipment authenticates the server; see Section 2.1.
The Captive Portal API URI might change during the Captive Portal Session. The User Equipment can apply the same trust mechanisms to the new URI that it applied to the URI it received initially from the Provisioning Service.
6.3. Secure APIs 🛡️
The solution described here requires that the API be secured using TLS. This is required to allow the User Equipment and API Server to exchange secrets that can be used to validate future interactions. The API MUST ensure the integrity of this information, as well as its confidentiality.
An attacker with access to this information might be able to masquerade as a specific User Equipment instance when interacting with the API. That could then allow them to masquerade as that User Equipment instance when interacting with the User Portal. This could give them the ability to determine whether the User Equipment has accessed the portal, deny the User Equipment service by ending their Session using mechanisms provided by the User Portal, or consume that User Equipment's quota. An attacker with the ability to modify the information could deny service to the User Equipment or cause it to appear as different User Equipment instances. 😤
6.4. Risks Associated with the Signaling Protocol 📣
If a Signaling Protocol is implemented, it may be possible for any user on the Internet to send signals in an attempt to cause the receiving equipment to communicate with the Captive Portal API. This has been considered, and implementations may address it in the following ways:
- The signal only signals to the User Equipment to query the API. It does not carry any information that may mislead or misdirect the User Equipment.
- Even when responding to the signal, the User Equipment securely authenticates with API Servers.
- The User Equipment limits the rate at which it accesses the API, reducing the impact of an attack attempting to generate excessive load on either the User Equipment or the API. Note that because there is only one type of signal and one type of API request in response to the signal, this rate-limiting will not cause loss of signaling information.
6.5. User Options 🙋
The Captive Portal Signal could signal to the User Equipment that it is being held captive. There is no requirement that the User Equipment do anything about this. Devices MAY permit users to disable automatic reaction to Captive Portal Signal indications for privacy reasons. However, there would be the trade-off that the user doesn't get notified when network access is restricted. Hence, end-user devices MAY allow users to manually control captive portal interactions, possibly on the granularity of Provisioning Domains 💜
6.6. Privacy 🔒
okay bestie, this part is serious but it's also so important 🫶. Section 3 sets up a mechanism where every component in the Captive Portal uses the same identifier to uniquely identify the User Equipment 🆔. That identifier could be abused to track the user 👀. So implementers and designers of Captive Portals should take care to make sure identifiers are stored securely, if they're stored at all 🔐. And if any component sends the identifier over the network, it should protect its confidentiality on the wire by using encryption such as TLS 🛡️.
There are also benefits to using mutable anonymous identifiers ✨. For example, User Equipment could cycle through multiple identifiers to help prevent long-term tracking 🦋. BUT, and this is a big but 😭, if network components use an internal mapping to link the identity to a stable, long-term value so they can handle changing identifiers, they need to treat that value as sensitive information 🚨. Why? Because an attacker could use it to tie traffic back to the originating User Equipment, even after that equipment has changed its identifiers 💀. It's giving "I changed my name but you still know it's me" energy 🙈.
7. References 📚
7.1. Normative References
These are the references the spec needs to be read properly 💅:
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
DOI 10.17487/RFC2818, May 2000,
<https://www.rfc-editor.org/info/rfc2818>.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March
2011, <https://www.rfc-editor.org/info/rfc6125>.
[RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain
Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015,
<https://www.rfc-editor.org/info/rfc7556>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8910] Kumari, W. and E. Kline, "Captive-Portal Identification in
DHCP and Router Advertisements (RAs)", RFC 8910,
DOI 10.17487/RFC8910, September 2020,
<https://www.rfc-editor.org/info/rfc8910>.7.2. Informative References
These ones are for extra context, the vibe check 🧠✨:
[CAPPORT-PVD]
Pfister, P. and T. Pauly, "Using Provisioning Domains for
Captive Portal Discovery", Work in Progress, Internet-
Draft, draft-pfister-capport-pvd-00, 30 June 2018,
<https://tools.ietf.org/html/draft-pfister-capport-pvd-
00>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC4213] Nordmark, E. and R. Gilligan, "Basic Transition Mechanisms
for IPv6 Hosts and Routers", RFC 4213,
DOI 10.17487/RFC4213, October 2005,
<https://www.rfc-editor.org/info/rfc4213>.
[RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS
Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499,
January 2019, <https://www.rfc-editor.org/info/rfc8499>.
[RFC8908] Pauly, T., Ed. and D. Thakore, Ed., "Captive Portal API",
RFC 8908, DOI 10.17487/RFC8908, September 2020,
<https://www.rfc-editor.org/info/rfc8908>.Appendix A. Existing Captive Portal Detection Implementations 🕵️♀️
okay so before all the fancy stuff, let's talk about how devices already check for captive portals in the wild 🍓. Operating systems and apps often run a few tests when a network connection comes up, to figure out if the device is sitting behind a captive portal 🚪. A super common move is making an HTTP request to a known, vendor-hosted endpoint that always gives back a fixed response 🎯. If the response is anything other than that expected one, the device takes it as a sign that a captive portal is there 🚨.
This check usually isn't secured with TLS 🙃. The reason is that a network with a captive portal may intercept the connection, which leads to a host name mismatch 💔. People call these "canary" requests, because just like the canary in the coal mine, they can be the first sign that something is wrong 🐤💛.
Another test is a DNS lookup to a known address with an expected answer 🔍. If the answer is different from what's expected, the equipment detects that a captive portal is present 💅. DNS queries over TCP or HTTPS are less likely to be messed with than DNS queries over UDP, because they're more complicated to implement 🧩.
The different tests can reach different conclusions 🤷♀️. It depends on whether or not the implementation handles both TCP and UDP traffic, and on which types of DNS are intercepted 🌀.
And lowkey the scariest part: malicious or misconfigured networks with a captive portal may not intercept these canary requests at all 😬. They might just pass them through, or they might impersonate the endpoint, which leaves the device with a false negative 👻.
Acknowledgments 🫶💖
The authors thank Lorenzo Colitti for providing the majority of the content for the Captive Portal Signal requirements 👑.
The authors thank Benjamin Kaduk for providing the content related to TLS certificate validation of the API Server 🔐.
The authors thank Michael Richardson for providing wording requiring DNSSEC and TLS to operate without the user adding exceptions 🌈.
The authors thank various individuals for their feedback on the mailing list and during the IETF 98 hackathon: David Bird, Erik Kline, Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van Dam 🎀✨. Literally the whole squad 🥹.
Authors' Addresses 💌
Kyle Larose
Agilicus
Email: kyle@agilicus.com
David Dolson
Email: ddolson@acm.org
Heng Liu
Google
Email: liucougar@google.comThat's the whole RFC, bestie! 🌈💖✨
📦 where this page comes from
- ietf: rfc8952 2020-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms