| Internet-Draft | Captive Portal Architecture | August 2020 |
| Larose, et al. | Expires 9 February 2021 | [Page] |
This document describes a captive portal architecture. Network provisioning protocols such as DHCP or Router Advertisements (RAs), an optional signaling protocol, and an HTTP API are used to provide the solution.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 9 February 2021.¶
Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
In this document, "Captive Portal" is used to describe a network to which a device may be voluntarily attached, such that network access is limited until some requirements have been fulfilled. Typically a user is required to use a web browser to fulfill requirements imposed by the network operator, such as reading advertisements, accepting an acceptable-use policy, or providing some form of credentials.¶
Implementations of captive portals generally require a web server, some method to allow/block traffic, and some method to alert the user. Common methods of alerting the user in implementations prior to this work involve modifying HTTP or DNS traffic.¶
This document describes an architecture for implementing captive portals while addressing most of the problems arising for current captive portal mechanisms. The architecture is guided by these requirements:¶
A side-benefit of the architecture described in this document is that devices without user interfaces are able to identify parameters of captivity. However, this document does not describe a mechanism for such devices to negotiate for unrestricted network access. A future document could provide a solution to devices without user interfaces. This document focuses on devices with user interfaces.¶
The architecture uses the following mechanisms:¶
The architecture attempts to provide confidentiality, authentication, and safety mechanisms to the extent possible.¶
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.¶
Captive Portal: A network which limits 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 which enforces the traffic restriction. Also known as Enforcement Device.¶
Captive Portal User Equipment: Also known as User Equipment. A device which has voluntarily joined a network for purposes of communicating beyond the constraints of the captive network.¶
User Portal: The web server providing a user interface for assisting the user in satisfying the conditions to escape captivity.¶
Captive Portal API: Also known as 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 visting a URI).¶
Captive Portal API Server: Also known as API Server. A server hosting the Captive Portal API.¶
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: Also known as Signaling Protocol. The protocol for communicating Captive Portal Signals.¶
Captive Portal Session: Also referred to simply as the "session", a Captive Portal Session is the association for a particular User Equipment 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 using the User Equipment's identifier (see Section 3).¶
The User Equipment is the device that a user desires to be attached to a network with full access to all hosts on the network (e.g., to have Internet access). The User Equipment communication is typically restricted by the Enforcement Device, described in Section 2.4, until site-specific requirements have been met.¶
This document only considers devices with web browsers, with web applications being the means of satisfying Captive Portal Conditions. An example of such User Equipment is a smart phone.¶
The User Equipment:¶
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 network, (b) the requirements may be fulfilled by manually visiting the captive portal web application, and (c) legacy devices must continue to be supported.¶
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 OCSP responders, CRLs, and NTP servers; see Section 4.1 of [I-D.ietf-capport-api] 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.¶
The Provisioning Service is primarily responsible for providing a Captive Portal API URI to the User Equipment when it connects to the network, and later if the URI changes. The provisioning service could also be the same service which is responsible for provisioning the User Equipment for access to the Captive Portal (e.g., by providing it with an IP address). This section discusses two mechanisms which may be used to provide the Captive Portal API URI to the User Equipment.¶
A standard for providing a Captive Portal API URI using DHCP or Router Advertisements is described in [RFC7710bis]. The captive portal architecture expects this URI to indicate the API described in Section 2.3.¶
Although still a work in progress, [I-D.pfister-capport-pvd] proposes a mechanism for User Equipment to be provided with PvD Bootstrap Information containing the URI for the API described in Section 2.3.¶
The purpose of a Captive Portal API is to permit a query of Captive Portal state without interrupting the user. This API thereby removes the need for User Equipment to perform clear-text "canary" (see Appendix A) queries to check for response tampering.¶
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 [I-D.ietf-capport-api] 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 7.)¶
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.¶
The Enforcement Device component restricts the network access of User Equipment according to 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:¶
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 7.4 for a discussion of risks related to a Captive Portal Signal.¶
The following diagram shows the communication between each component in the case where the Captive Portal has a User Portal, and the User Equipment chooses to visit the User Portal in response to discovering and interacting with 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
In the diagram:¶
The Provisioning Service, API Server, and User Portal are described as discrete functions. An implementation might provide the multiple functions within a single entity. Furthermore, these functions, combined or not, as well as the Enforcement Device, could be replicated for redundancy or scale.¶
Multiple components in the architecture interact with both the User Equipment and each other. Since the User Equipment is the focus of these interactions, the components must be able to both identify the User Equipment from their interactions with it, and to agree on the identity of the User Equipment when interacting with each other.¶
The methods by which the components interact restrict the type of information that may be used as an identifying characteristics. This section discusses the identifying characteristics.¶
An Identifier is a characteristic of the User Equipment used by the components of a Captive Portal to uniquely determine which specific User Equipment is interacting with them. An Identifier can be a field contained in packets sent by the User Equipment to the External Network. Or, an Identifier can be an ephemeral property not contained in packets destined for the External Network, but instead correlated with such information through knowledge available to the different components.¶
The set of possible identifiers is quite large. However, in order to be considered a good identifier, an identifier SHOULD meet the following criteria. Note that the optimal identifier will likely change depending on the position of the components in the network as well as the information available to them. An identifier SHOULD:¶
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.¶
The Captive Portal MUST associate the User Equipment with an identifier that is unique among the User Equipment that are interacting with the Captive Portal at that time.¶
Over time, the User Equipment assigned to an identifier value MAY change. Allowing the identified device to change over time ensures that the space of possible identifying values need not be overly large.¶
Independent Captive Portals MAY use the same identifying value to identify different User Equipment. Allowing independent captive portals to reuse identifying values allows the identifier to be a property of the local network, expanding the space of possible identifiers.¶
A good identifier does not lend itself to being easily spoofed. At no time should it be simple or straightforward for one User Equipment to pretend to be another User Equipment, regardless of whether both are active at the same time. This property is particularly important when the User Equipment identifier is referenced externally by devices such as billing systems, or where the identity of the User Equipment could imply liability.¶
Since the API Server will need to perform operations which rely on the identity of the User Equipment, such as answering a query about whether the User Equipment is captive, the API Server needs to be able to relate a request to the User Equipment making the request.¶
The Enforcement Device will decide on a per-packet basis whether the packet should be forwarded to the external network. Since this decision depends on which User Equipment sent the packet, the Enforcement Device requires that it be able to map the packet to its concept of the User Equipment.¶
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 which best satisfies all of the recommended properties. The architecture does not provide an exact measure of how well an identifier type satisfies a given property; care should be taken in performing the evaluation.¶
This section provides some example identifier types, along with some evaluation of whether they are suitable types. The list of identifier types is not exhaustive. Other types may be used. An important point to note is that whether a given identifier type is suitable depends heavily on the capabilities of the components and where in the network the components exist.¶
The physical interface by which the User Equipment is attached to the network can be used to identify the User Equipment. This identifier type has the property of being extremely difficult to spoof: the User Equipment is unaware of the property; one User Equipment cannot manipulate its interactions to appear as though it is another.¶
Further, if only a single User Equipment is attached to a given physical interface, then the identifier will be unique. If multiple User Equipment is attached to the network on the same physical interface, then this type is not appropriate.¶
Another consideration related to uniqueness of the User Equipment 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, implying that it should co-exist with the Enforcement Device, or that the Enforcement Device should extend requests to it with the identifying information.¶
A natural identifier type to consider is the IP address of the User Equipment. At any given time, no device on the network can have the same IP address without causing the network to malfunction, so it is appropriate from the perspective of uniqueness.¶
However, it may be possible to spoof the IP address, particularly for malicious reasons where proper functioning of the network is not necessary for the malicious actor. Consequently, 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. Demonstrations of return routeability, such as that required for TCP connection establishment, might be sufficient defense against spoofing, though this might not be sufficient in networks that use broadcast media (such as some wireless networks).¶
Since the IP address may traverse multiple segments of the network, more flexibility is afforded to the Enforcement Device and the API Server: they simply must exist on a segment of the network where the IP address is still unique. However, consider that a NAT may be deployed between the User Equipment and the Enforcement Device. In such cases, it is possible for the components to still uniquely identify the device if they are aware of the port mapping.¶
In some situations, the User Equipment may have multiple IP addresses (either IPv4, IPv6 or a dual-stack [RFC4213] combination), while still satisfying all of the recommended properties. This raises some challenges to 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, or should it tie the multiple addresses together into one view of the subscriber? An implementation MAY do either. Attention should be paid to IPv6 and the fact that it is 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.¶
The MAC address of a device is often used as an identifier in existing implementations. This document does not 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.¶
A Captive Portal API needs to present information to clients that is unique to that 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 allows the same URI to be used for different clients. However, it also means that the resource is unable to provide relevant information if the User Equipment makes a request using a different network path. This might happen when 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.¶
Though a URI might still correctly resolve when the User Equipment makes the request from a different network, it is possible that some functions could be limited to when the User Equipment makes requests using the captive network. For example, payment options could be absent 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 in the URIs. However, including unauthenticated User Equipment identifiers in the URI may expose the service to spoofing or replay attacks.¶
This section aims to improve understanding by describing a possible workflow of solutions adhering to the architecture. Note that the section is not normative: it describes only as subset of possible implementations.¶
This section describes a possible workflow when User Equipment initially joins a Captive Portal.¶
This section describes a possible workflow when access is about to expire.¶
A different Captive Portal API URI could be returned in the following cases:¶
When the Network 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.¶
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 IETF98 hackathon: David Bird, Erik Kline, Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van Dam.¶
This memo includes no request to IANA.¶
When joining a network, some trust is placed in the network operator. This is usually considered to be a decision by a user on the basis of the reputation of an organization. However, once a user makes such a decision, protocols can support authenticating that a network is operated by who claims to be operating it. The Provisioning Domain Architecture [RFC7556] provides some discussion on authenticating an operator.¶
The user makes an informed choice to visit and trust the Captive Portal URI. Since the network provides 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. E.g., 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 cannot 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.¶
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 as it did to the URI it received initially from the network provisioning service.¶
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 which 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 when interacting with the API, which could then allow them to masquerade as that User Equipment when interacting with the User Portal. This could give them the ability to determine whether the User Equipment has accessed the portal, or 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 them to appear as a different User Equipment.¶
If a Signaling Protocol is implemented, it may be possible for any user on the Internet to send signals in 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 Captive Portal Signal could signal to the User Equipment that it is being held captive. There is no requirement that the User Equipment do something about this. Devices MAY permit users to disable automatic reaction to Captive Portal Signals 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.¶
Section 3 describes a mechanism by which all components within the Captive Portal are designed to use the same identifier to uniquely identify the User Equipment. This identifier could be abused to track the user. Implementers and designers of Captive Portals should take care to ensure that identifiers, if stored, are stored securely. Likewise, if any component communicates the identifier over the network, it should ensure the confidentiality of the identifier on the wire by using encryption such as TLS.¶
There are benfits to choosing mutable anonymous identifiers. For example, User Equipment could cycle through multiple identifiers to help prevent long-term tracking. However, if the components of the network use an internal mapping to map the identity to a stable, long-term value in order to deal with changing identifiers, they need to treat that value as sensitive information: an attacker could use it to tie traffic back to the originating User Equipment, despite the User Equipment having changed identifiers.¶
Operating systems and user applications may perform various tests when network connectivity is established to determine if the device is attached to a network with a captive portal present. A common method is to attempt to make a HTTP request to a known, vendor-hosted endpoint with a fixed response. Any other response is interpreted as a signal that a captive portal is present. This check is typically not secured with TLS, as a network with a captive portal may intercept the connection, leading to a host name mismatch. This has been referred to as a "canary" request because, like the canary in the coal mine, it can be the first sign that something is wrong.¶
Another test that can be performed is a DNS lookup to a known address with an expected answer. If the answer differs from the expected answer, the equipment detects that a captive portal is present. DNS queries over TCP or HTTPS are less likely to be modified than DNS queries over UDP due to the complexity of implementation.¶
The different tests may produce different conclusions, varying by whether or not the implementation treats both TCP and UDP traffic, and by which types of DNS are intercepted.¶
Malicious or misconfigured networks with a captive portal present may not intercept these canary requests and choose to pass them through or decide to impersonate, leading to the device having a false negative.¶