idnits 2.17.1 draft-ietf-capport-architecture-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (23 September 2020) is 1310 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) == Outdated reference: A later version (-11) exists of draft-ietf-capport-rfc7710bis-01 == Outdated reference: A later version (-08) exists of draft-ietf-capport-api-06 -- Obsolete informational reference (is this intentional?): RFC 8499 (Obsoleted by RFC 9499) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force K. Larose 3 Internet-Draft Agilicus 4 Intended status: Informational D. Dolson 5 Expires: 27 March 2021 6 H. Liu 7 Google 8 23 September 2020 10 Captive Portal Architecture 11 draft-ietf-capport-architecture-10 13 Abstract 15 This document describes a captive portal architecture. Network 16 provisioning protocols such as DHCP or Router Advertisements (RAs), 17 an optional signaling protocol, and an HTTP API are used to provide 18 the solution. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on 27 March 2021. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. Code Components 47 extracted from this document must include Simplified BSD License text 48 as described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 5 55 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 56 2. Components . . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2.1. User Equipment . . . . . . . . . . . . . . . . . . . . . 6 58 2.2. Provisioning Service . . . . . . . . . . . . . . . . . . 7 59 2.2.1. DHCP or Router Advertisements . . . . . . . . . . . . 8 60 2.2.2. Provisioning Domains . . . . . . . . . . . . . . . . 8 61 2.3. Captive Portal API Server . . . . . . . . . . . . . . . . 8 62 2.4. Captive Portal Enforcement Device . . . . . . . . . . . . 9 63 2.5. Captive Portal Signal . . . . . . . . . . . . . . . . . . 10 64 2.6. Component Diagram . . . . . . . . . . . . . . . . . . . . 10 65 3. User Equipment Identity . . . . . . . . . . . . . . . . . . . 12 66 3.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 12 67 3.2. Recommended Properties . . . . . . . . . . . . . . . . . 12 68 3.2.1. Uniquely Identify User Equipment . . . . . . . . . . 13 69 3.2.2. Hard to Spoof . . . . . . . . . . . . . . . . . . . . 13 70 3.2.3. Visible to the API Server . . . . . . . . . . . . . . 13 71 3.2.4. Visible to the Enforcement Device . . . . . . . . . . 14 72 3.3. Evaluating Types of Identifiers . . . . . . . . . . . . . 14 73 3.4. Example Identifier Types . . . . . . . . . . . . . . . . 14 74 3.4.1. Physical Interface . . . . . . . . . . . . . . . . . 14 75 3.4.2. IP Address . . . . . . . . . . . . . . . . . . . . . 15 76 3.4.3. Media Access Control (MAC) Address . . . . . . . . . 16 77 3.5. Context-free URI . . . . . . . . . . . . . . . . . . . . 16 78 4. Solution Workflow . . . . . . . . . . . . . . . . . . . . . . 17 79 4.1. Initial Connection . . . . . . . . . . . . . . . . . . . 17 80 4.2. Conditions About to Expire . . . . . . . . . . . . . . . 17 81 4.3. Handling of Changes in Portal URI . . . . . . . . . . . . 18 82 5. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 83 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 84 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 85 7.1. Trusting the Network . . . . . . . . . . . . . . . . . . 19 86 7.2. Authenticated APIs . . . . . . . . . . . . . . . . . . . 19 87 7.3. Secure APIs . . . . . . . . . . . . . . . . . . . . . . . 20 88 7.4. Risks Associated with the Signaling Protocol . . . . . . 20 89 7.5. User Options . . . . . . . . . . . . . . . . . . . . . . 21 90 7.6. Privacy . . . . . . . . . . . . . . . . . . . . . . . . . 21 91 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 92 8.1. Normative References . . . . . . . . . . . . . . . . . . 21 93 8.2. Informative References . . . . . . . . . . . . . . . . . 22 94 Appendix A. Existing Captive Portal Detection Implementations . 23 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 97 1. Introduction 99 In this document, "Captive Portal" is used to describe a network to 100 which a device may be voluntarily attached, such that network access 101 is limited until some requirements have been fulfilled. Typically a 102 user is required to use a web browser to fulfill requirements imposed 103 by the network operator, such as reading advertisements, accepting an 104 acceptable-use policy, or providing some form of credentials. 106 Implementations of captive portals generally require a web server, 107 some method to allow/block traffic, and some method to alert the 108 user. Common methods of alerting the user in implementations prior 109 to this work involve modifying HTTP or DNS traffic. 111 This document describes an architecture for implementing captive 112 portals while addressing most of the problems arising for current 113 captive portal mechanisms. The architecture is guided by these 114 requirements: 116 * Current captive portal solutions typically implement some 117 variations of forging DNS or HTTP responses. Some attempt man-in- 118 the-middle (MITM) proxy of HTTPS in order to forge reponses. 119 Captive Portal Solutions should not have to break any protocols or 120 otherwise act in the manner of an attacker. Therefore, solutions 121 MUST NOT require the forging of responses from DNS or HTTP 122 servers, or any other protocol. 124 * Solutions MUST permit clients to perform DNSSEC validation, which 125 rules out solutions that forge DNS responses. Solutions SHOULD 126 permit clients to detect and avoid TLS man-in-the-middle attacks 127 without requiring a human to perform any kind of "exception" 128 processing. 130 * To maximize universality and adoption, solutions MUST operate at 131 the layer of Internet Protocol (IP) or above, not being specific 132 to any particular access technology such as Cable, WiFi or mobile 133 telecom. 135 * Solutions SHOULD allow a device to query the network to determine 136 whether the device is captive, without the solution being coupled 137 to forging intercepted protocols or requiring the device to make 138 sacrificial queries to "canary" URIs to check for response 139 tampering (see Appendix A). Current captive portal solutions that 140 work by affecting DNS or HTTP generally only function as intended 141 with browsers, breaking other applications using those protocols; 142 applications using other protocols are not alerted that the 143 network is a captive portal. 145 * The state of captivity SHOULD be explicitly available to devices 146 via a standard protocol, rather than having to infer the state 147 indirectly. 149 * The architecture MUST provide a path of incremental migration, 150 acknowledging the existence of a huge variety of pre-existing 151 portals and end-user device implementations and software versions. 152 This requirement is not to recommend or standardize existing 153 approaches, rather to provide device and portal implementors a 154 path to new standard. 156 A side-benefit of the architecture described in this document is that 157 devices without user interfaces are able to identify parameters of 158 captivity. However, this document does not describe a mechanism for 159 such devices to negotiate for unrestricted network access. A future 160 document could provide a solution to devices without user interfaces. 161 This document focuses on devices with user interfaces. 163 The architecture uses the following mechanisms: 165 * Network provisioning protocols provide end-user devices with a 166 Uniform Resource Identifier [RFC3986] (URI) for the API that end- 167 user devices query for information about what is required to 168 escape captivity. DHCP, DHCPv6, and Router-Advertisement options 169 for this purpose are available in [RFC7710bis]. Other protocols 170 (such as RADIUS), Provisioning Domains [I-D.pfister-capport-pvd], 171 or static configuration may also be used to convey this Captive 172 Portal API URI. A device MAY query this API at any time to 173 determine whether the network is holding the device in a captive 174 state. 176 * A Captive Portal can signal User Equipment in response to 177 transmissions by the User Equipment. This signal works in 178 response to any Internet protocol, and is not done by modifying 179 protocols in-band. This signal does not carry the Captive Portal 180 API URI; rather it provides a signal to the User Equipment that it 181 is in a captive state. 183 * Receipt of a Captive Portal Signal provides a hint that User 184 Equipment could be captive. In response, the device MAY query the 185 provisioned API to obtain information about the network state. 186 The device can take immediate action to satisfy the portal 187 (according to its configuration/policy). 189 The architecture attempts to provide confidentiality, authentication, 190 and safety mechanisms to the extent possible. 192 1.1. Requirements Language 194 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 195 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 196 "OPTIONAL" in this document are to be interpreted as described in BCP 197 14 [RFC2119] [RFC8174] when, and only when, they appear in all 198 capitals, as shown here. 200 1.2. Terminology 202 Captive Portal: A network which limits communication of attached 203 devices to restricted hosts until the user has satisfied Captive 204 Portal Conditions, after which access is permitted to a wider set of 205 hosts (typically the Internet). 207 Captive Portal Conditions: site-specific requirements that a user or 208 device must satisfy in order to gain access to the wider network. 210 Captive Portal Enforcement Device: The network equipment which 211 enforces the traffic restriction. Also known as Enforcement Device. 213 Captive Portal User Equipment: Also known as User Equipment. A 214 device which has voluntarily joined a network for purposes of 215 communicating beyond the constraints of the Captive Portal. 217 User Portal: The web server providing a user interface for assisting 218 the user in satisfying the conditions to escape captivity. 220 Captive Portal API: Also known as API. An HTTP API allowing User 221 Equipment to query information about its state of captivity within 222 the Captive Portal. This information might include how to obtain 223 full network access (e.g. by visting a URI). 225 Captive Portal API Server: Also known as API Server. A server 226 hosting the Captive Portal API. 228 Captive Portal Signal: A notification from the network used to signal 229 to the User Equipment that the state of its captivity could have 230 changed. 232 Captive Portal Signaling Protocol: Also known as Signaling Protocol. 233 The protocol for communicating Captive Portal Signals. 235 Captive Portal Session: Also referred to simply as the "session", a 236 Captive Portal Session is the association for a particular User 237 Equipment that starts when it interacts with the Captive Portal and 238 gains open access to the network, and ends when the User Equipment 239 moves back into the original captive state. The Captive Network 240 maintains the state of each active Session, and can limit Sessions 241 based on a length of time or a number of bytes used. The Session is 242 associated with a particular User Equipment using the User 243 Equipment's identifier (see Section 3). 245 2. Components 247 2.1. User Equipment 249 The User Equipment is the device that a user desires to be attached 250 to a network with full access to all hosts on the network (e.g., to 251 have Internet access). The User Equipment communication is typically 252 restricted by the Enforcement Device, described in Section 2.4, until 253 site-specific requirements have been met. 255 This document only considers devices with web browsers, with web 256 applications being the means of satisfying Captive Portal Conditions. 257 An example of such User Equipment is a smart phone. 259 The User Equipment: 261 * SHOULD support provisioning of the URI for the Captive Portal API 262 (e.g., by DHCP) 264 * SHOULD distinguish Captive Portal API access per network 265 interface, in the manner of Provisioning Domain Architecture 266 [RFC7556]. 268 * SHOULD have a non-spoofable mechanism for notifying the user of 269 the Captive Portal 271 * SHOULD have a web browser so that the user may navigate to the 272 User Portal. 274 * SHOULD support updates to the Captive Portal API URI from the 275 network provisioning service. 277 * MAY prevent applications from using networks that do not grant 278 full network access. E.g., a device connected to a mobile network 279 may be connecting to a captive WiFi network; the operating system 280 could avoid updating the default route to a device on captive WiFi 281 network until network access restrictions have been lifted 282 (excepting access to the User Portal) in the new network. This 283 has been termed "make before break". 285 None of the above requirements are mandatory because (a) we do not 286 wish to say users or devices must seek full access to the Captive 287 Portal, (b) the requirements may be fulfilled by manually visiting 288 the captive portal web application, and (c) legacy devices must 289 continue to be supported. 291 If User Equipment supports the Captive Portal API, it MUST validate 292 the API server's TLS certificate (see [RFC2818]) according to the 293 procedures in [RFC6125]. The API server's URI is obtained via a 294 network provisioning protocol, which will typically provide a 295 hostname to be used in TLS server certificate validation, against a 296 DNS-ID in the server certificate. If the API server is identified by 297 IP address, the iPAddress subjectAltName is used to validate the 298 server certificate. An Enforcement Device SHOULD allow access to any 299 services that User Equipment could need to contact to perform 300 certificate validation, such as OCSP responders, CRLs, and NTP 301 servers; see Section 4.1 of [I-D.ietf-capport-api] for more 302 information. If certificate validation fails, User Equipment MUST 303 NOT make any calls to the API server. 305 The User Equipment can store the last response it received from the 306 Captive Portal API as a cached view of its state within the Captive 307 Portal. This state can be used to determine whether its Captive 308 Portal Session is near expiry. For example, the User Equipment might 309 compare a timestamp indicating when the session expires to the 310 current time. Storing state in this way can reduce the need for 311 communication with the Captive Portal API. However, it could lead to 312 the state becoming stale if the User Equipment's view of the relevant 313 conditions (byte quota, for example) is not consistent with the 314 Captive Portal API's. 316 2.2. Provisioning Service 318 The Provisioning Service is primarily responsible for providing a 319 Captive Portal API URI to the User Equipment when it connects to the 320 network, and later if the URI changes. The provisioning service 321 could also be the same service which is responsible for provisioning 322 the User Equipment for access to the Captive Portal (e.g., by 323 providing it with an IP address). This section discusses two 324 mechanisms which may be used to provide the Captive Portal API URI to 325 the User Equipment. 327 2.2.1. DHCP or Router Advertisements 329 A standard for providing a Captive Portal API URI using DHCP or 330 Router Advertisements is described in [RFC7710bis]. The captive 331 portal architecture expects this URI to indicate the API described in 332 Section 2.3. 334 2.2.2. Provisioning Domains 336 Although still a work in progress, [I-D.pfister-capport-pvd] proposes 337 a mechanism for User Equipment to be provided with PvD Bootstrap 338 Information containing the URI for the API described in Section 2.3. 340 2.3. Captive Portal API Server 342 The purpose of a Captive Portal API is to permit a query of Captive 343 Portal state without interrupting the user. This API thereby removes 344 the need for User Equipment to perform clear-text "canary" (see 345 Appendix A) queries to check for response tampering. 347 The URI of this API will have been provisioned to the User Equipment. 348 (Refer to Section 2.2). 350 This architecture expects the User Equipment to query the API when 351 the User Equipment attaches to the network and multiple times 352 thereafter. Therefore the API MUST support multiple repeated queries 353 from the same User Equipment and return the state of captivity for 354 the equipment. 356 At minimum, the API MUST provide the state of captivity. Further the 357 API MUST be able to provide a URI for the User Portal. The scheme 358 for the URI MUST be https so that the User Equipment communicates 359 with the User Portal over TLS. 361 If the API receives a request for state that does not correspond to 362 the requesting User Equipment, the API SHOULD deny access. Given 363 that the API might use the User Equipment's identifier for 364 authentication, this requirement motivates Section 3.2.2. 366 A caller to the API needs to be presented with evidence that the 367 content it is receiving is for a version of the API that it supports. 368 For an HTTP-based interaction, such as in [I-D.ietf-capport-api] this 369 might be achieved by using a content type that is unique to the 370 protocol. 372 When User Equipment receives Captive Portal Signals, the User 373 Equipment MAY query the API to check its state of captivity. The 374 User Equipment SHOULD rate-limit these API queries in the event of 375 the signal being flooded. (See Section 7.) 377 The API MUST be extensible to support future use-cases by allowing 378 extensible information elements. 380 The API MUST use TLS to ensure server authentication. The 381 implementation of the API MUST ensure both confidentiality and 382 integrity of any information provided by or required by it. 384 This document does not specify the details of the API. 386 2.4. Captive Portal Enforcement Device 388 The Enforcement Device component restricts the network access of User 389 Equipment according to site-specific policy. Typically User 390 Equipment is permitted access to a small number of services 391 (according to the policies of the network provider) and is denied 392 general network access until it satisfies the Captive Portal 393 Conditions. 395 The Enforcement Device component: 397 * Allows traffic to pass for User Equipment that is permitted to use 398 the network and has satisfied the Captive Portal Conditions. 400 * Blocks (discards) traffic according to the site-specific policy 401 for User Equipment that has not yet satisfied the Captive Portal 402 Conditions. 404 * Optionally signals User Equipment using the Captive Portal 405 Signaling protocol if certain traffic is blocked. 407 * Permits User Equipment that has not satisfied the Captive Portal 408 Conditions to access necessary APIs and web pages to fulfill 409 requirements for escaping captivity. 411 * Updates allow/block rules per User Equipment in response to 412 operations from the User Portal. 414 2.5. Captive Portal Signal 416 When User Equipment first connects to a network, or when there are 417 changes in status, the Enforcement Device could generate a signal 418 toward the User Equipment. This signal indicates that the User 419 Equipment might need to contact the API Server to receive updated 420 information. For instance, this signal might be generated when the 421 end of a session is imminent, or when network access was denied. For 422 simplicity, and to reduce the attack surface, all signals SHOULD be 423 considered equivalent by the User Equipment: as a hint to contact the 424 API. If future solutions have multiple signal types, each type 425 SHOULD be rate-limited independently. 427 An Enforcement Device MUST rate-limit any signal generated in 428 response to these conditions. See Section 7.4 for a discussion of 429 risks related to a Captive Portal Signal. 431 2.6. Component Diagram 433 The following diagram shows the communication between each component 434 in the case where the Captive Portal has a User Portal, and the User 435 Equipment chooses to visit the User Portal in response to discovering 436 and interacting with the API Server. 438 o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . o 439 . CAPTIVE PORTAL . 440 . +------------+ Join Network +--------------+ . 441 . | |+--------------------------->| Provisioning | . 442 . | | Provision API URI | Service | . 443 . | |<---------------------------+| | . 444 . | User | +--------------+ . 445 . | Equipment | Query captivity status +-------------+ . 446 . | |+--------------------------->| API | . 447 . | | Captivity status response | Server | . 448 . | |<---------------------------+| | . 449 . | | +------+------+ . 450 . | | | Status . 451 . | | Portal UI page requests +------+------+ . 452 . | |+--------------------------->| | . 453 . | | Portal UI pages | User Portal | . 454 . | |<---------------------------+| | . 455 . +------------+ | | . 456 . ^ ^ | +-------------+ . 457 . | | | Data to/from ext. network | . 458 . | | +-----------------> +---------------+ Allow/Deny . 459 . | +--------------------+| | Rules . 460 . | | Enforcement | | . 461 . | Captive Portal Signal | Device |<----+ . 462 . +-------------------------+---------------+ . 463 . ^ | . 464 . | | . 465 . Data to/from external network . 466 . | | . 467 o . . . . . . . . . . . . . . . . . . .| |. . . . . . . . . . . o 468 | v 469 EXTERNAL NETWORK 471 Figure 1: Captive Portal Architecture Component Diagram 473 In the diagram: 475 * During provisioning (e.g., DHCP), and possibly later, the User 476 Equipment acquires the Captive Portal API URI. 478 * The User Equipment queries the API to learn of its state of 479 captivity. If captive, the User Equipment presents the portal 480 user interface from the User Portal to the user. 482 * Based on user interaction, the User Portal directs the Enforcement 483 Device to either allow or deny external network access for the 484 User Equipment. 486 * The User Equipment attempts to communicate to the external network 487 through the Enforcement Device. 489 * The Enforcement Device either allows the User Equipment's packets 490 to the external network, or blocks the packets. If blocking 491 traffic and a signal has been implemented, it may respond with a 492 Captive Portal Signal. 494 The Provisioning Service, API Server, and User Portal are described 495 as discrete functions. An implementation might provide the multiple 496 functions within a single entity. Furthermore, these functions, 497 combined or not, as well as the Enforcement Device, could be 498 replicated for redundancy or scale. 500 3. User Equipment Identity 502 Multiple components in the architecture interact with both the User 503 Equipment and each other. Since the User Equipment is the focus of 504 these interactions, the components must be able to both identify the 505 User Equipment from their interactions with it, and to agree on the 506 identity of the User Equipment when interacting with each other. 508 The methods by which the components interact restrict the type of 509 information that may be used as an identifying characteristics. This 510 section discusses the identifying characteristics. 512 3.1. Identifiers 514 An Identifier is a characteristic of the User Equipment used by the 515 components of a Captive Portal to uniquely determine which specific 516 User Equipment is interacting with them. An Identifier can be a 517 field contained in packets sent by the User Equipment to the External 518 Network. Or, an Identifier can be an ephemeral property not 519 contained in packets destined for the External Network, but instead 520 correlated with such information through knowledge available to the 521 different components. 523 3.2. Recommended Properties 525 The set of possible identifiers is quite large. However, in order to 526 be considered a good identifier, an identifier SHOULD meet the 527 following criteria. Note that the optimal identifier will likely 528 change depending on the position of the components in the network as 529 well as the information available to them. An identifier SHOULD: 531 * uniquely identify the User Equipment 533 * be hard to spoof 534 * be visible to the API Server 536 * be visible to the Enforcement Device 538 An identifier might only apply to the current point of network 539 attachment. If the device moves to a different network location its 540 identity could change. 542 3.2.1. Uniquely Identify User Equipment 544 The Captive Portal MUST associate the User Equipment with an 545 identifier that is unique among the User Equipment that are 546 interacting with the Captive Portal at that time. 548 Over time, the User Equipment assigned to an identifier value MAY 549 change. Allowing the identified device to change over time ensures 550 that the space of possible identifying values need not be overly 551 large. 553 Independent Captive Portals MAY use the same identifying value to 554 identify different User Equipment. Allowing independent captive 555 portals to reuse identifying values allows the identifier to be a 556 property of the local network, expanding the space of possible 557 identifiers. 559 3.2.2. Hard to Spoof 561 A good identifier does not lend itself to being easily spoofed. At 562 no time should it be simple or straightforward for one User Equipment 563 to pretend to be another User Equipment, regardless of whether both 564 are active at the same time. This property is particularly important 565 when the User Equipment identifier is referenced externally by 566 devices such as billing systems, or where the identity of the User 567 Equipment could imply liability. 569 3.2.3. Visible to the API Server 571 Since the API Server will need to perform operations which rely on 572 the identity of the User Equipment, such as answering a query about 573 whether the User Equipment is captive, the API Server needs to be 574 able to relate a request to the User Equipment making the request. 576 3.2.4. Visible to the Enforcement Device 578 The Enforcement Device will decide on a per-packet basis whether the 579 packet should be forwarded to the external network. Since this 580 decision depends on which User Equipment sent the packet, the 581 Enforcement Device requires that it be able to map the packet to its 582 concept of the User Equipment. 584 3.3. Evaluating Types of Identifiers 586 To evaluate whether a type of identifier is appropriate, one should 587 consider every recommended property from the perspective of 588 interactions among the components in the architecture. When 589 comparing identifier types, choose the one which best satisfies all 590 of the recommended properties. The architecture does not provide an 591 exact measure of how well an identifier type satisfies a given 592 property; care should be taken in performing the evaluation. 594 3.4. Example Identifier Types 596 This section provides some example identifier types, along with some 597 evaluation of whether they are suitable types. The list of 598 identifier types is not exhaustive. Other types may be used. An 599 important point to note is that whether a given identifier type is 600 suitable depends heavily on the capabilities of the components and 601 where in the network the components exist. 603 3.4.1. Physical Interface 605 The physical interface by which the User Equipment is attached to the 606 network can be used to identify the User Equipment. This identifier 607 type has the property of being extremely difficult to spoof: the User 608 Equipment is unaware of the property; one User Equipment cannot 609 manipulate its interactions to appear as though it is another. 611 Further, if only a single User Equipment is attached to a given 612 physical interface, then the identifier will be unique. If multiple 613 User Equipment is attached to the network on the same physical 614 interface, then this type is not appropriate. 616 Another consideration related to uniqueness of the User Equipment is 617 that if the attached User Equipment changes, both the API Server and 618 the Enforcement Device MUST invalidate their state related to the 619 User Equipment. 621 The Enforcement Device needs to be aware of the physical interface, 622 which constrains the environment: it must either be part of the 623 device providing physical access (e.g., implemented in firmware), or 624 packets traversing the network must be extended to include 625 information about the source physical interface (e.g. a tunnel). 627 The API Server faces a similar problem, implying that it should co- 628 exist with the Enforcement Device, or that the Enforcement Device 629 should extend requests to it with the identifying information. 631 3.4.2. IP Address 633 A natural identifier type to consider is the IP address of the User 634 Equipment. At any given time, no device on the network can have the 635 same IP address without causing the network to malfunction, so it is 636 appropriate from the perspective of uniqueness. 638 However, it may be possible to spoof the IP address, particularly for 639 malicious reasons where proper functioning of the network is not 640 necessary for the malicious actor. Consequently, any solution using 641 the IP address SHOULD proactively try to prevent spoofing of the IP 642 address. Similarly, if the mapping of IP address to User Equipment 643 is changed, the components of the architecture MUST remove or update 644 their mapping to prevent spoofing. Demonstrations of return 645 routeability, such as that required for TCP connection establishment, 646 might be sufficient defense against spoofing, though this might not 647 be sufficient in networks that use broadcast media (such as some 648 wireless networks). 650 Since the IP address may traverse multiple segments of the network, 651 more flexibility is afforded to the Enforcement Device and the API 652 Server: they simply must exist on a segment of the network where the 653 IP address is still unique. However, consider that a NAT may be 654 deployed between the User Equipment and the Enforcement Device. In 655 such cases, it is possible for the components to still uniquely 656 identify the device if they are aware of the port mapping. 658 In some situations, the User Equipment may have multiple IP addresses 659 (either IPv4, IPv6 or a dual-stack [RFC4213] combination), while 660 still satisfying all of the recommended properties. This raises some 661 challenges to the components of the network. For example, if the 662 User Equipment tries to access the network with multiple IP 663 addresses, should the Enforcement Device and API Server treat each IP 664 address as a unique User Equipment, or should it tie the multiple 665 addresses together into one view of the subscriber? An 666 implementation MAY do either. Attention should be paid to IPv6 and 667 the fact that it is expected for a device to have multiple IPv6 668 addresses on a single link. In such cases, identification could be 669 performed by subnet, such as the /64 to which the IP belongs. 671 3.4.3. Media Access Control (MAC) Address 673 The MAC address of a device is often used as an identifier in 674 existing implementations. This document does not discuss the use of 675 MAC addresses within a captive portal system, but they can be used as 676 an identifier type, subject to the criteria in Section 3.2. 678 3.5. Context-free URI 680 A Captive Portal API needs to present information to clients that is 681 unique to that client. To do this, some systems use information from 682 the context of a request, such as the source address, to identify the 683 User Equipment. 685 Using information from context rather than information from the URI 686 allows the same URI to be used for different clients. However, it 687 also means that the resource is unable to provide relevant 688 information if the User Equipment makes a request using a different 689 network path. This might happen when User Equipment has multiple 690 network interfaces. It might also happen if the address of the API 691 provided by DNS depends on where the query originates (as in split 692 DNS [RFC8499]). 694 Accessing the API MAY depend on contextual information. However, the 695 URIs provided in the API SHOULD be unique to the User Equipment and 696 not dependent on contextual information to function correctly. 698 Though a URI might still correctly resolve when the User Equipment 699 makes the request from a different network, it is possible that some 700 functions could be limited to when the User Equipment makes requests 701 using the Captive Portal. For example, payment options could be 702 absent or a warning could be displayed to indicate the payment is not 703 for the current connection. 705 URIs could include some means of identifying the User Equipment in 706 the URIs. However, including unauthenticated User Equipment 707 identifiers in the URI may expose the service to spoofing or replay 708 attacks. 710 4. Solution Workflow 712 This section aims to improve understanding by describing a possible 713 workflow of solutions adhering to the architecture. Note that the 714 section is not normative: it describes only as subset of possible 715 implementations. 717 4.1. Initial Connection 719 This section describes a possible workflow when User Equipment 720 initially joins a Captive Portal. 722 1. The User Equipment joins the Captive Portal by acquiring a DHCP 723 lease, RA, or similar, acquiring provisioning information. 725 2. The User Equipment learns the URI for the Captive Portal API from 726 the provisioning information (e.g., [RFC7710bis]). 728 3. The User Equipment accesses the Captive Portal API to receive 729 parameters of the Captive Portal, including User Portal URI. 730 (This step replaces the clear-text query to a canary URI.) 732 4. If necessary, the User navigates to the User Portal to gain 733 access to the external network. 735 5. If the User interacted with the User Portal to gain access to the 736 external network in the previous step, the User Portal indicates 737 to the Enforcement Device that the User Equipment is allowed to 738 access the external network. 740 6. The User Equipment attempts a connection outside the Captive 741 Portal 743 7. If the requirements have been satisfied, the access is permitted; 744 otherwise the "Expired" behavior occurs. 746 8. The User Equipment accesses the network until conditions Expire. 748 4.2. Conditions About to Expire 750 This section describes a possible workflow when access is about to 751 expire. 753 1. Precondition: the API has provided the User Equipment with a 754 duration over which its access is valid. 756 2. The User Equipment is communicating with the outside network. 758 3. The User Equipment detects that the length of time left for its 759 access has fallen below a threshold by comparing its stored 760 expiry time with the current time. 762 4. The User Equipment visits the API again to validate the expiry 763 time. 765 5. If expiry is still imminent, the User Equipment prompts the user 766 to access the User Portal URI again. 768 6. The User accepts the prompt displayed by the User Equipment. 770 7. The User extends their access through the User Portal via the 771 User Equipment's user interface. 773 8. The User Equipment's access to the outside network continues 774 uninterrupted. 776 4.3. Handling of Changes in Portal URI 778 A different Captive Portal API URI could be returned in the following 779 cases: 781 * If DHCP is used, a lease renewal/rebind may return a different 782 Captive Portal API URI. 784 * If RA is used, a new Captive Portal API URI may be specified in a 785 new RA message received by end User Equipment. 787 When the Network Provisioning Service updates the Captive Portal API 788 URI, the User Equipment can retrieve updated state from the URI 789 immediately, or it can wait as it normally would until the expiry 790 conditions it retrieved from the old URI are about to expire. 792 5. Acknowledgments 794 The authors thank Lorenzo Colitti for providing the majority of the 795 content for the Captive Portal Signal requirements. 797 The authors thank Benjamin Kaduk for providing the content related to 798 TLS certificate validation of the API server. 800 The authors thank Michael Richardson for providing wording requiring 801 DNSSEC and TLS to operate without the user adding exceptions. 803 The authors thank various individuals for their feedback on the 804 mailing list and during the IETF98 hackathon: David Bird, Erik Kline, 805 Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van 806 Dam. 808 6. IANA Considerations 810 This memo includes no request to IANA. 812 7. Security Considerations 814 7.1. Trusting the Network 816 When joining a network, some trust is placed in the network operator. 817 This is usually considered to be a decision by a user on the basis of 818 the reputation of an organization. However, once a user makes such a 819 decision, protocols can support authenticating that a network is 820 operated by who claims to be operating it. The Provisioning Domain 821 Architecture [RFC7556] provides some discussion on authenticating an 822 operator. 824 The user makes an informed choice to visit and trust the Captive 825 Portal URI. Since the network provides Captive Portal URI to the 826 user equipment, the network SHOULD do so securely so that the user's 827 trust in the network can extend to their trust of the Captive Portal 828 URI. E.g., the DHCPv6 AUTH option can sign this information. 830 If a user decides to incorrectly trust an attacking network, they 831 might be convinced to visit an attacking web page and unwittingly 832 provide credentials to an attacker. Browsers can authenticate 833 servers but cannot detect cleverly misspelled domains, for example. 835 Further, the possibility of an on-path attacker in an attacking 836 network introduces some risks. The attacker could redirect traffic 837 to arbitrary destinations. The attacker could analyze the user's 838 traffic leading to loss of confidentiality. Or, the attacker could 839 modify the traffic inline. 841 7.2. Authenticated APIs 843 The solution described here requires that when the User Equipment 844 needs to access the API server, the User Equipment authenticates the 845 server; see Section 2.1. 847 The Captive Portal API URI might change during the Captive Portal 848 Session. The User Equipment can apply the same trust mechanisms to 849 the new URI as it did to the URI it received initially from the 850 network provisioning service. 852 7.3. Secure APIs 854 The solution described here requires that the API be secured using 855 TLS. This is required to allow the User Equipment and API Server to 856 exchange secrets which can be used to validate future interactions. 857 The API MUST ensure the integrity of this information, as well as its 858 confidentiality. 860 An attacker with access to this information might be able to 861 masquerade as a specific User Equipment when interacting with the 862 API, which could then allow them to masquerade as that User Equipment 863 when interacting with the User Portal. This could give them the 864 ability to determine whether the User Equipment has accessed the 865 portal, or deny the User Equipment service by ending their session 866 using mechanisms provided by the User Portal, or consume that User 867 Equipment's quota. An attacker with the ability to modify the 868 information could deny service to the User Equipment, or cause them 869 to appear as a different User Equipment. 871 7.4. Risks Associated with the Signaling Protocol 873 If a Signaling Protocol is implemented, it may be possible for any 874 user on the Internet to send signals in attempt to cause the 875 receiving equipment to communicate with the Captive Portal API. This 876 has been considered, and implementations may address it in the 877 following ways: 879 * The signal only signals to the User Equipment to query the API. 880 It does not carry any information which may mislead or misdirect 881 the User Equipment. 883 * Even when responding to the signal, the User Equipment securely 884 authenticates with API Servers. 886 * Accesses to the Captive Portal API are rate-limited, reducing the 887 impact of an attack attempting to generate excessive load on 888 either User Equipment or API. Note that because there is only one 889 type of signal and one type of API request in response to the 890 signal, this rate-limiting will not cause loss of signalling 891 information. 893 7.5. User Options 895 The Captive Portal Signal could signal to the User Equipment that it 896 is being held captive. There is no requirement that the User 897 Equipment do something about this. Devices MAY permit users to 898 disable automatic reaction to Captive Portal Signals indications for 899 privacy reasons. However, there would be the trade-off that the user 900 doesn't get notified when network access is restricted. Hence, end- 901 user devices MAY allow users to manually control captive portal 902 interactions, possibly on the granularity of Provisioning Domains. 904 7.6. Privacy 906 Section 3 describes a mechanism by which all components within the 907 Captive Portal are designed to use the same identifier to uniquely 908 identify the User Equipment. This identifier could be abused to 909 track the user. Implementers and designers of Captive Portals should 910 take care to ensure that identifiers, if stored, are stored securely. 911 Likewise, if any component communicates the identifier over the 912 network, it should ensure the confidentiality of the identifier on 913 the wire by using encryption such as TLS. 915 There are benefits to choosing mutable anonymous identifiers. For 916 example, User Equipment could cycle through multiple identifiers to 917 help prevent long-term tracking. However, if the components of the 918 network use an internal mapping to map the identity to a stable, 919 long-term value in order to deal with changing identifiers, they need 920 to treat that value as sensitive information: an attacker could use 921 it to tie traffic back to the originating User Equipment, despite the 922 User Equipment having changed identifiers. 924 8. References 926 8.1. Normative References 928 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 929 Requirement Levels", BCP 14, RFC 2119, 930 DOI 10.17487/RFC2119, March 1997, 931 . 933 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 934 DOI 10.17487/RFC2818, May 2000, 935 . 937 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 938 Verification of Domain-Based Application Service Identity 939 within Internet Public Key Infrastructure Using X.509 940 (PKIX) Certificates in the Context of Transport Layer 941 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 942 2011, . 944 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 945 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 946 . 948 [RFC7710bis] 949 Kumari, W. and E. Kline, "Captive-Portal Identification in 950 DHCP / RA", Work in Progress, Internet-Draft, draft-ietf- 951 capport-rfc7710bis-01, 12 January 2020, 952 . 955 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 956 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 957 May 2017, . 959 8.2. Informative References 961 [I-D.ietf-capport-api] 962 Pauly, T. and D. Thakore, "Captive Portal API", Work in 963 Progress, Internet-Draft, draft-ietf-capport-api-06, 31 964 March 2020, 965 . 967 [I-D.pfister-capport-pvd] 968 Pfister, P. and T. Pauly, "Using Provisioning Domains for 969 Captive Portal Discovery", Work in Progress, Internet- 970 Draft, draft-pfister-capport-pvd-00, 30 June 2018, 971 . 974 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 975 Resource Identifier (URI): Generic Syntax", STD 66, 976 RFC 3986, DOI 10.17487/RFC3986, January 2005, 977 . 979 [RFC4213] Nordmark, E. and R. Gilligan, "Basic Transition Mechanisms 980 for IPv6 Hosts and Routers", RFC 4213, 981 DOI 10.17487/RFC4213, October 2005, 982 . 984 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 985 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 986 January 2019, . 988 Appendix A. Existing Captive Portal Detection Implementations 990 Operating systems and user applications may perform various tests 991 when network connectivity is established to determine if the device 992 is attached to a network with a captive portal present. A common 993 method is to attempt to make a HTTP request to a known, vendor-hosted 994 endpoint with a fixed response. Any other response is interpreted as 995 a signal that a captive portal is present. This check is typically 996 not secured with TLS, as a network with a captive portal may 997 intercept the connection, leading to a host name mismatch. This has 998 been referred to as a "canary" request because, like the canary in 999 the coal mine, it can be the first sign that something is wrong. 1001 Another test that can be performed is a DNS lookup to a known address 1002 with an expected answer. If the answer differs from the expected 1003 answer, the equipment detects that a captive portal is present. DNS 1004 queries over TCP or HTTPS are less likely to be modified than DNS 1005 queries over UDP due to the complexity of implementation. 1007 The different tests may produce different conclusions, varying by 1008 whether or not the implementation treats both TCP and UDP traffic, 1009 and by which types of DNS are intercepted. 1011 Malicious or misconfigured networks with a captive portal present may 1012 not intercept these canary requests and choose to pass them through 1013 or decide to impersonate, leading to the device having a false 1014 negative. 1016 Authors' Addresses 1018 Kyle Larose 1019 Agilicus 1021 Email: kyle@agilicus.com 1023 David Dolson 1025 Email: ddolson@acm.org 1027 Heng Liu 1028 Google 1029 Email: liucougar@google.com