idnits 2.17.1 draft-ietf-capport-architecture-06.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 (15 February 2020) is 1503 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-11) exists of draft-ietf-capport-rfc7710bis-01 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). 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: 18 August 2020 6 H. Liu 7 15 February 2020 9 CAPPORT Architecture 10 draft-ietf-capport-architecture-06 12 Abstract 14 This document aims to document consensus on the CAPPORT architecture. 15 DHCP or Router Advertisements, an optional signaling protocol, and an 16 HTTP API are used to provide the solution. The role of Provisioning 17 Domains (PvDs) is described. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 18 August 2020. 36 Copyright Notice 38 Copyright (c) 2020 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 54 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Components . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 2.1. User Equipment . . . . . . . . . . . . . . . . . . . . . 5 57 2.2. Provisioning Service . . . . . . . . . . . . . . . . . . 6 58 2.2.1. DHCP or Router Advertisements . . . . . . . . . . . . 6 59 2.2.2. Provisioning Domains . . . . . . . . . . . . . . . . 6 60 2.3. Captive Portal API Server . . . . . . . . . . . . . . . . 6 61 2.4. Captive Portal Enforcement . . . . . . . . . . . . . . . 7 62 2.5. Captive Portal Signal . . . . . . . . . . . . . . . . . . 8 63 2.6. Component Diagram . . . . . . . . . . . . . . . . . . . . 9 64 3. User Equipment Identity . . . . . . . . . . . . . . . . . . . 10 65 3.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 10 66 3.2. Recommended Properties . . . . . . . . . . . . . . . . . 10 67 3.2.1. Uniquely Identify User Equipment . . . . . . . . . . 11 68 3.2.2. Hard to Spoof . . . . . . . . . . . . . . . . . . . . 11 69 3.2.3. Visible to the API Server . . . . . . . . . . . . . . 11 70 3.2.4. Visible to the Enforcement Device . . . . . . . . . . 11 71 3.3. Evaluating an Identifier . . . . . . . . . . . . . . . . 12 72 3.4. Examples of an Identifier . . . . . . . . . . . . . . . . 12 73 3.4.1. Physical Interface . . . . . . . . . . . . . . . . . 12 74 3.4.2. IP Address . . . . . . . . . . . . . . . . . . . . . 13 75 3.4.3. Context-free URL . . . . . . . . . . . . . . . . . . 14 76 4. Solution Workflow . . . . . . . . . . . . . . . . . . . . . . 14 77 4.1. Initial Connection . . . . . . . . . . . . . . . . . . . 14 78 4.2. Conditions About to Expire . . . . . . . . . . . . . . . 15 79 4.3. Handling of Changes in Portal URI . . . . . . . . . . . . 15 80 5. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 81 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 82 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 83 7.1. Trusting the Network . . . . . . . . . . . . . . . . . . 16 84 7.2. Authenticated APIs . . . . . . . . . . . . . . . . . . . 16 85 7.3. Secure APIs . . . . . . . . . . . . . . . . . . . . . . . 17 86 7.4. Risks Associated with the Signaling Protocol . . . . . . 17 87 7.5. User Options . . . . . . . . . . . . . . . . . . . . . . 17 88 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 89 8.1. Normative References . . . . . . . . . . . . . . . . . . 17 90 8.2. Informative References . . . . . . . . . . . . . . . . . 18 91 Appendix A. Existing captive portal detection implementations . 18 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 94 1. Introduction 96 In this document, "Captive Portal" is used to describe a network to 97 which a device may be voluntarily attached, such that network access 98 is limited until some requirements have been fulfilled. Typically a 99 user is required to use a web browser to fulfill requirements imposed 100 by the network operator, such as reading advertisements, accepting an 101 acceptable-use policy, or providing some form of credentials. 103 Implementations generally require a web server, some method to allow/ 104 block traffic, and some method to alert the user. Common methods of 105 alerting the user involve modifying HTTP or DNS traffic. 107 Problems with captive portal implementations have been described in 108 [I-D.nottingham-capport-problem]. [If that document cannot be 109 published, consider putting its best parts into an appendix of this 110 document.] 112 This document standardizes an architecture for implementing captive 113 portals that provides tools for addressing most of those problems. 114 We are guided by these principles: 116 * Solutions SHOULD NOT require the forging of responses from DNS or 117 HTTP servers, or any other protocol. In particular, solutions 118 SHOULD NOT require man-in-the-middle proxy of TLS traffic. 120 * Solutions MUST operate at the layer of Internet Protocol (IP) or 121 above, not being specific to any particular access technology such 122 as Cable, WiFi or 3GPP. 124 * Solutions MAY allow a device to be alerted that it is in a captive 125 network when attempting to use any application on the network. 127 * Solutions SHOULD allow a device to learn that it is in a captive 128 network before any application attempts to use the network. 130 * The state of captivity SHOULD be explicitly available to devices 131 (in contrast to modification of DNS or HTTP, which is only 132 indirectly machine-detectable by the client--by comparing 133 responses to well-known queries with expected responses). 135 * The architecture MUST provide a path of incremental migration, 136 acknowledging a huge variety of portals and end-user device 137 implementations and software versions. 139 A side-benefit of the architecture described in this document is that 140 devices without user interfaces are able to identify parameters of 141 captivity. However, this document does not yet describe a mechanism 142 for such devices to escape captivity. 144 The architecture uses the following mechanisms: 146 * Network provisioning protocols provide end-user devices with a URI 147 for the API that end-user devices query for information about what 148 is required to escape captivity. DHCP, DHCPv6, and Router- 149 Advertisement options for this purpose are available in 150 [RFC7710bis]. Other protocols (such as RADIUS), Provisioning 151 Domains [I-D.pfister-capport-pvd], or static configuration may 152 also be used. A device MAY query this API at any time to 153 determine whether the network is holding the device in a captive 154 state. 156 * End-user devices can be notified of captivity with Captive Portal 157 Signals in response to traffic. This notification should work 158 with any Internet protocol, not just clear-text HTTP. This 159 notification does not carry the portal URI; rather it provides a 160 notification to the User Equipment that it is in a captive state. 161 This document will specify requirements for a signaling protocol 162 which could generate Captive Portal Signals. 164 * Receipt of a Captive Portal Signal informs an end-user device that 165 it could be captive. In response, the device MAY query the 166 provisioned API to obtain information about the network state. 167 The device MAY take immediate action to satisfy the portal 168 (according to its configuration/policy). 170 The architecture attempts to provide privacy, authentication, and 171 safety mechanisms to the extent possible. 173 1.1. Requirements Language 175 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 176 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 177 document are to be interpreted as described in RFC 2119 [RFC2119]. 179 1.2. Terminology 181 Captive Network: A network which limits communication of attached 182 devices to restricted hosts until the user has satisfied Captive 183 Portal Conditions, after which access is permitted to a wider set of 184 hosts (typically the internet). 186 Captive Portal Conditions: site-specific requirements that a user or 187 device must satisfy in order to gain access to the wider network. 189 Captive Portal Enforcement: The network equipment which enforces the 190 traffic restriction. 192 Captive Portal User Equipment: Also known as User Equipment. A 193 device which has voluntarily joined a network for purposes of 194 communicating beyond the constraints of the captive network. 196 Captive Portal Server: The web server providing a user interface for 197 assisting the user in satisfying the conditions to escape captivity. 199 Captive Portal API: Also known as API. An HTTP API allowing User 200 Equipment to query its state of captivity within the Captive Portal. 202 Captive Portal API Server: Also known as API Server. A server 203 hosting the Captive Portal API. 205 Captive Portal Signal: A notification from the network used to inform 206 the User Equipment that the state of its captivity could have 207 changed. 209 Captive Portal Signaling Protocol: Also known as Signaling Protocol. 210 The protocol for communicating Captive Portal Signals. 212 2. Components 214 2.1. User Equipment 216 The User Equipment is the device that a user desires to be attached 217 to a network with full access to all hosts on the network (e.g., to 218 have Internet access). The User Equipment communication is typically 219 restricted by the Captive Portal Enforcement, described in 220 Section 2.4, until site-specific requirements have been met. 222 At this time we consider only devices with web browsers, with web 223 applications being the means of satisfying Captive Portal Conditions. 225 * An example interactive User Equipment is a smart phone. 227 * SHOULD support provisioning of the URI for the Captive Portal API 228 (e.g., by DHCP) 230 * SHOULD distinguish Captive Portal API access per network 231 interface, in the manner of Provisioning Domain Architecture 232 [RFC7556]. 234 * SHOULD have a mechanism for notifying the user of the Captive 235 Portal 237 * SHOULD have a web browser so that the user may navigate the 238 Captive Portal user interface. 240 * MAY restrict application access to networks not granting full 241 network access. E.g., a device connected to a mobile network may 242 be connecting to a WiFi network; the operating system MAY avoid 243 updating the default route until network access restrictions have 244 been lifted (excepting access to the Captive Portal server). This 245 has been termed "make before break". 247 None of the above requirements are mandatory because (a) we do not 248 wish to say users or devices must seek access beyond the captive 249 network, (b) the requirements may be fulfilled by manually visiting 250 the captive portal web application, and (c) legacy devices must 251 continue to be supported. 253 2.2. Provisioning Service 255 Here we discuss candidate mechanisms for provisioning the User 256 Equipment with the URI of the API to query captive portal state and 257 navigate the portal. 259 2.2.1. DHCP or Router Advertisements 261 A standard for providing a portal URI using DHCP or Router 262 Advertisements is described in [RFC7710bis]. The CAPPORT 263 architecture expects this URI to indicate the API described in 264 Section 2.3. 266 2.2.2. Provisioning Domains 268 Although still a work in progress, [I-D.pfister-capport-pvd] proposes 269 a mechanism for User Equipment to be provided with PvD Bootstrap 270 Information containing the URI for the JSON-based API described in 271 Section 2.3. 273 2.3. Captive Portal API Server 275 The purpose of a Captive Portal API is to permit a query of Captive 276 Portal state without interrupting the user. This API thereby removes 277 the need for a device to perform clear-text "canary" HTTP queries to 278 check for response tampering. 280 The URI of this API will have been provisioned to the User Equipment. 281 (Refer to Section 2.2). 283 This architecture expects the User Equipment to query the API when 284 the User Equipment attaches to the network and multiple times 285 thereafter. Therefore the API MUST support multiple repeated queries 286 from the same User Equipment, returning the current state of 287 captivity for the equipment. 289 At minimum the API MUST provide: (1) the state of captivity and (2) a 290 URI for a browser to present the portal application to the user. The 291 API SHOULD provide evidence to the caller that it supports the 292 present architecture. 294 When user equipment receives Captive Portal Signals, the user 295 equipment MAY query the API to check the state. The User Equipment 296 SHOULD rate-limit these API queries in the event of the signal being 297 flooded. (See Section 7.) 299 The API MUST be extensible to support future use-cases by allowing 300 extensible information elements. 302 The API MUST use TLS for privacy and server authentication. The 303 implementation of the API MUST ensure both privacy and integrity of 304 any information provided by or required by it. 306 This document does not specify the details of the API. 308 2.4. Captive Portal Enforcement 310 The Captive Portal Enforcement component restricts network access to 311 User Equipment according to site-specific policy. Typically User 312 Equipment is permitted access to a small number of services and is 313 denied general network access until it has performed some action. 315 The Captive Portal Enforcement component: 317 * Allows traffic through for allowed User Equipment. 319 * Blocks (discards) traffic for disallowed User Equipment. 321 * May signal User Equipment using the Captive Portal Signaling 322 protocol if traffic is blocked. 324 * Permits disallowed User Equipment to access necessary APIs and web 325 pages to fulfill requirements of exiting captivity. 327 * Updates allow/block rules per User Equipment in response to 328 operations from the Captive Portal back-end. 330 2.5. Captive Portal Signal 332 User Equipment may send traffic outside the captive network prior to 333 the Enforcement device granting it access. The Enforcement Device 334 rightly blocks or resets these requests. However, lacking a signal 335 from the Enforcement Device or interaction with the API server, the 336 User Equipment can only guess at whether it is captive. 337 Consequently, allowing the Enforcement Device to signal to the User 338 Equipment that there is a problem with its connectivity may improve 339 the user's experience. 341 An Enforcement Device may also want to inform the User Equipment of a 342 pending expiry of its access to the external network, so providing 343 the Enforcement Device the ability to preemptively signal may be 344 desirable. 346 A specific Captive Portal Signaling Protocol is out of scope for this 347 document. However, in order to ensure that future protocols fit into 348 the architecture, requirements for a Captive Portal Signaling 349 Protocol follow: 351 1. The notification SHOULD NOT be easy to spoof. If an attacker can 352 send spoofed notifications to the User Equipment, they can cause 353 the User Equipment to unnecessarily access the API. Rather than 354 relying solely on rate limits to prevent problems, a good 355 protocol will strive to limit the feasibility of such attacks. 357 2. It SHOULD be possible to send the notification before the captive 358 portal closes. This will help ensure seamless connectivity for 359 the user, as the User Equipment will not need to wait for a 360 network failure to refresh its login. On receipt of preemptive 361 notification, the User Equipment can prompt the user to refresh. 363 3. The signal SHOULD NOT include any information other than an 364 indication that traffic is restricted, which can be used as a 365 prompt to contact the API. 367 The Captive Portal Signaling Protocol does not provide any means of 368 indicating that the network prevents access to some destinations. 369 The intent is to rely on the Captive Portal API and the web portal to 370 which it points to communicate local network policies. 372 The Captive Portal Enforcement function MAY send Captive Portal 373 Signals when disallowed User Equipment attempts to send to the 374 network. These signals MUST be rate-limited to a configurable rate. 376 The signals MUST NOT be sent to the Internet devices. The 377 indications are only sent to the User Equipment. 379 2.6. Component Diagram 381 The following diagram shows the communication between each component. 383 o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . o 384 . CAPTIVE NETWORK . 385 . +--------------+ . 386 . +------------+ Provision API URI | Provisioning | . 387 . | |<---------------------------+| Service | . 388 . | User | +--------------+ . 389 . | Equipment | Query captivity status +-------------+ . 390 . | |+--------------------------->| API | . 391 . | | | Server | . 392 . | | +------+------+ . 393 . | | | Status . 394 . | | Portal user interface +------+------+ . 395 . | |+--------------------------->| Web Portal | . 396 . +------------+ | Server | . 397 . ^ ^ | +-------------+ . 398 . | | | Data | . 399 . | | +-----------------> +---------------+ Allow/Deny . 400 . | +--------------------+| | Rules . 401 . | | Captive Portal| | . 402 . | Captive Portal Signal | Enforcement | <---+ . 403 . +-------------------------+---------------+ . 404 . ^ | . 405 . | | . 406 . Data to/from external network . 407 . | | . 408 o . . . . . . . . . . . . . . . . . . .| |. . . . . . . . . . . o 409 | v 410 EXTERNAL NETWORK 412 Figure 1: Captive Portal Architecture Component Diagram 414 In the diagram: 416 * During provisioning (e.g., DHCP), the User Equipment acquires the 417 URI for the Captive Portal API. 419 * The User Equipment queries the API to learn of its state of 420 captivity. If captive, the User Equipment presents the portal 421 user interface to the user. 423 * The User Equipment attempts to communicate to the external network 424 through the Captive Portal enforcement device. 426 * The Captive Portal Enforcement device either allows the User 427 Equipment's packets to the external network, or if a signal has 428 been implemented, responds with a Captive Portal Signal. 430 * The Web Portal Server directs the Captive Portal Enforcement 431 device to either allow or deny external network access for the 432 User Equipment. 434 Although the Provisioning Service, API Server, and Web Portal Server 435 functions are shown as discrete blocks, they could of course be 436 combined into a single element. 438 3. User Equipment Identity 440 Multiple components in the architecture interact with both the User 441 Equipment and each other. Since the User Equipment is the focus of 442 these interactions, the components must be able to both identify the 443 user equipment from their interactions with it, and be able to agree 444 on the identity of the user equipment when interacting with each 445 other. 447 The methods by which the components interact restrict the type of 448 information that may be used as an identifying characteristics. This 449 section discusses the identifying characteristics. 451 3.1. Identifiers 453 An Identifier is a characteristic of the User Equipment used by the 454 components of a Captive Portal to uniquely determine which specific 455 User Equipment is interacting with them. An Identifier MAY be a 456 field contained in packets sent by the User Equipment to the External 457 Network. Or, an Identifier MAY be an ephemeral property not 458 contained in packets destined for the External Network, but instead 459 correlated with such information through knowledge available to the 460 different components. 462 3.2. Recommended Properties 464 The set of possible identifiers is quite large. However, in order to 465 be considered a good identifier, an identifier SHOULD meet the 466 following criteria. Note that the optimal identifier will likely 467 change depending on the position of the components in the network as 468 well as the information available to them. An identifier SHOULD: 470 * Uniquely Identify the User Equipment 472 * Be Hard to Spoof 473 * Be Visible to the API Server 475 * Be Visible to the Enforcement Device 477 An identifier might only apply to the current point of network 478 attachment. If the device moves to a different network location its 479 identity could change. 481 3.2.1. Uniquely Identify User Equipment 483 In order to uniquely identify the User Equipment, at most one user 484 equipment interacting with the other components of the Captive Portal 485 MUST have a given value of the identifier. 487 Over time, the user equipment identified by the value MAY change. 488 Allowing the identified device to change over time ensures that the 489 space of possible identifying values need not be overly large. 491 Independent Captive Portals MAY use the same identifying value to 492 identify different User Equipment. Allowing independent captive 493 portals to reuse identifying values allows the identifier to be a 494 property of the local network, expanding the space of possible 495 identifiers. 497 3.2.2. Hard to Spoof 499 A good identifier does not lend itself to being easily spoofed. At 500 no time should it be simple or straightforward for one User Equipment 501 to pretend to be another User Equipment, regardless of whether both 502 are active at the same time. This property is particularly important 503 when the user equipment is extended externally to devices such as 504 billing systems, or where the identity of the User Equipment could 505 imply liability. 507 3.2.3. Visible to the API Server 509 Since the API Server will need to perform operations which rely on 510 the identity of the user equipment, such as query whether it is 511 captive, the API Server needs to be able to relate requests to the 512 User Equipment making the request. 514 3.2.4. Visible to the Enforcement Device 516 The Enforcement Device will decide on a per packet basis whether it 517 should be permitted to communicate with the external network. Since 518 this decision depends on which User Equipment sent the packet, the 519 Enforcement Device requires that it be able to map the packet to its 520 concept of the User Equipment. 522 3.3. Evaluating an Identifier 524 To evaluate whether an identifier is appropriate, one should consider 525 every recommended property from the perspective of interactions among 526 the components in the architecture. When comparing identifiers, 527 choose the one which best satisfies all of the recommended 528 properties. The architecture does not provide an exact measure of 529 how well an identifier satisfies a given property; care should be 530 taken in performing the evaluation. 532 3.4. Examples of an Identifier 534 This section provides some examples of identifiers, along with some 535 evaluation of whether they are good identifiers. The list of 536 identifiers is not exhaustive. Other identifiers may be used. An 537 important point to note is that whether the identifiers are good 538 depends heavily on the capabilities of the components and where in 539 the network the components exist. 541 3.4.1. Physical Interface 543 The physical interface by which the User Equipment is attached to the 544 network can be used to identify the User Equipment. This identifier 545 has the property of being extremely difficult to spoof: the User 546 Equipment is unaware of the property; one User Equipment cannot 547 manipulate its interactions to appear as though it is another. 549 Further, if only a single User Equipment is attached to a given 550 physical interface, then the identifier will be unique. If multiple 551 User Equipment is attached to the network on the same physical 552 interface, then this property is not appropriate. 554 Another consideration related to uniqueness of the User Equipment is 555 that if the attached User Equipment changes, both the API Server and 556 the Enforcement Device must invalidate their state related to the 557 User Equipment. 559 The Enforcement Device needs to be aware of the physical interface, 560 which constrains the environment: it must either be part of the 561 device providing physical access (e.g., implemented in firmware), or 562 packets traversing the network must be extended to include 563 information about the source physical interface (e.g. a tunnel). 565 The API Server faces a similar problem, implying that it should co- 566 exist with the Enforcement Device, or that the enforcement device 567 should extend requests to it with the identifying information. 569 3.4.2. IP Address 571 A natural identifier to consider is the IP address of the User 572 Equipment. At any given time, no device on the network can have the 573 same IP address without causing the network to malfunction, so it is 574 appropriate from the perspective of uniqueness. 576 However, it may be possible to spoof the IP address, particularly for 577 malicious reasons where proper functioning of the network is not 578 necessary for the malicious actor. Consequently, any solution using 579 the IP address should proactively try to prevent spoofing of the IP 580 address. Similarly, if the mapping of IP address to User Equipment 581 is changed, the components of the architecture must remove or update 582 their mapping to prevent spoofing. Demonstrations of return 583 routeability, such as that required for TCP connection establishment, 584 might be sufficient defense against spoofing, though this might not 585 be sufficient in networks that use broadcast media (such as some 586 wireless networks). 588 Since the IP address may traverse multiple segments of the network, 589 more flexibility is afforded to the Enforcement Device and the API 590 Server: they simply must exist on a segment of the network where the 591 IP address is still unique. However, consider that a NAT may be 592 deployed between the User Equipment and the Enforcement Device. In 593 such cases, it is possible for the components to still uniquely 594 identify the device if they are aware of the port mapping. 596 In some situations, the User Equipment may have multiple IP 597 addresses, while still satisfying all of the recommended properties. 598 This raises some challenges to the components of the network. For 599 example, if the user equipment tries to access the network with 600 multiple IP addresses, should the enforcement device and API Server 601 treat each IP address as a unique User Equipment, or should it tie 602 the multiple addresses together into one view of the subscriber? An 603 implementation MAY do either. Attention should be paid to IPv6 and 604 the fact that it is expected for a device to have multiple IPv6 605 addresses on a single link. In such cases, identification could be 606 performed by subnet, such as the /64 to which the IP belongs. 608 3.4.3. Context-free URL 610 The URLs provided in the API SHOULD contain all the information 611 necessary to render the resources requested: the resources should not 612 depend on ambient information, such as remote address on the 613 connection. This is to ensure that the content served from these 614 URLs is correct and meaningful to the User Equipment, even when 615 accessed from a network other than the one that contains the captive 616 portal. One consequence of this is that URLs provided in the API are 617 expected to be resolved using public DNS. 619 Though a URL might still correctly resolve when the UE makes the 620 request from a different network, it is possible that some functions 621 could be limited to when the UE makes requests using the captive 622 network. For example, payment options could be absent or a warning 623 could be displayed to indicate the payment is not for the current 624 connection. 626 URLs could include some means of identifying the User Equipment in 627 the URLs. However, including unauthenticated User Equipment 628 identifiers in the URL may expose the service to spoofing or replay 629 attacks. 631 4. Solution Workflow 633 This section aims to improve understanding by describing a possible 634 workflow of solutions adhering to the architecture. 636 4.1. Initial Connection 638 This section describes a possible work-flow when User Equipment 639 initially joins a Captive Network. 641 1. The User Equipment joins the Captive Network by acquiring a DHCP 642 lease, RA, or similar, acquiring provisioning information. 644 2. The User Equipment learns the URI for the Captive Portal API from 645 the provisioning information (e.g., [RFC7710bis]). 647 3. The User Equipment accesses the Captive Portal API to receive 648 parameters of the Captive Network, including web-portal URI. 649 (This step replaces the clear-text query to a canary URL.) 651 4. If necessary, the User navigates the web portal to gain access to 652 the external network. 654 5. The Captive Portal API server indicates to the Captive Portal 655 Enforcement device that the User Equipment is allowed to access 656 the external network. 658 6. The User Equipment attempts a connection outside the captive 659 network 661 7. If the requirements have been satisfied, the access is permitted; 662 otherwise the "Expired" behavior occurs. 664 8. The User Equipment accesses the network until conditions Expire. 666 4.2. Conditions About to Expire 668 This section describes a possible work-flow when access is about to 669 expire. 671 1. Precondition: the API has provided the User Equipment with a 672 duration over which its access is valid 674 2. The User Equipment is communicating with the outside network 676 3. The User Equipment's UI indicates that the length of time left 677 for its access has fallen below a threshold 679 4. The User Equipment visits the API again to validate the expiry 680 time 682 5. If expiry is still imminent, the User Equipment prompts the user 683 to access the web-portal URI again 685 6. The User extends their access through the web-portal 687 7. The User Equipment's access to the outside network continues 688 uninterrupted 690 4.3. Handling of Changes in Portal URI 692 A different Captive Portal API URI could be returned in the following 693 cases: 695 * If DHCP is used, a lease renewal/rebind may return a different 696 Captive Portal API URI. 698 * If RA is used, a new Captive Portal API URI may be specified in a 699 new RA message received by end user equipment. 701 Whenever a new Portal URI is received by end user equipment, it 702 SHOULD discard the old URI and use the new one for future requests to 703 the API. 705 5. Acknowledgments 707 The authors thank Lorenzo Colitti for providing the majority of the 708 content for the Captive Portal Signal requirements. 710 The authors thank various individuals for their feedback on the 711 mailing list and during the IETF98 hackathon: David Bird, Erik Kline, 712 Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van 713 Dam. 715 6. IANA Considerations 717 This memo includes no request to IANA. 719 7. Security Considerations 721 7.1. Trusting the Network 723 When joining a network, some trust is placed in the network operator. 724 This is usually considered to be a decision by a user on the basis of 725 the reputation of an organization. However, once a user makes such a 726 decision, protocols can support authenticating a network is operated 727 by who claims to be operating it. The Provisioning Domain 728 Architecture [RFC7556] provides some discussion on authenticating an 729 operator. 731 Given that a user chooses to visit a Captive Portal URI, the URI 732 location SHOULD be securely provided to the user's device. E.g., the 733 DHCPv6 AUTH option can sign this information. 735 If a user decides to incorrectly trust an attacking network, they 736 might be convinced to visit an attacking web page and unwittingly 737 provide credentials to an attacker. Browsers can authenticate 738 servers but cannot detect cleverly misspelled domains, for example. 740 7.2. Authenticated APIs 742 The solution described here assumes that when the User Equipment 743 needs to trust the API server, server authentication will be 744 performed using TLS mechanisms. 746 7.3. Secure APIs 748 The solution described here requires that the API be secured using 749 TLS. This is required to allow the user equipment and API Server to 750 exchange secrets which can be used to validate future interactions. 751 The API must ensure the integrity of this information, as well as its 752 confidentiality. 754 7.4. Risks Associated with the Signaling Protocol 756 If a Signaling Protocol is implemented, it may be possible for any 757 user on the Internet to send signals in attempt to cause the 758 receiving equipment to communicate with the Captive Portal API. This 759 has been considered, and implementations may address it in the 760 following ways: 762 * The signal only informs the User Equipment to query the API. It 763 does not carry any information which may mislead or misdirect the 764 User Equipment. 766 * Even when responding to the signal, the User Equipment securely 767 authenticates with API Servers. 769 * Accesses to the API Server are rate limited, limiting the impact 770 of a repeated attack. 772 7.5. User Options 774 The Signal could inform the User Equipment that it is being held 775 captive. There is no requirement that the User Equipment do 776 something about this. Devices MAY permit users to disable automatic 777 reaction to captive-portal indications for privacy reasons. However, 778 there is the trade-off that the user doesn't get notified when 779 network access is restricted. Hence, end-user devices MAY allow 780 users to manually control captive portal interactions, possibly on 781 the granularity of Provisioning Domains. 783 8. References 785 8.1. Normative References 787 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 788 Requirement Levels", BCP 14, RFC 2119, 789 DOI 10.17487/RFC2119, March 1997, 790 . 792 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 793 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 794 . 796 [RFC7710bis] 797 Kumari, W. and E. Kline, "Captive-Portal Identification in 798 DHCP / RA", Work in Progress, Internet-Draft, draft-ietf- 799 capport-rfc7710bis-01, 12 January 2020, 800 . 803 8.2. Informative References 805 [I-D.nottingham-capport-problem] 806 Nottingham, M., "Captive Portals Problem Statement", Work 807 in Progress, Internet-Draft, draft-nottingham-capport- 808 problem-01, 4 April 2016, . 811 [I-D.pfister-capport-pvd] 812 Pfister, P. and T. Pauly, "Using Provisioning Domains for 813 Captive Portal Discovery", Work in Progress, Internet- 814 Draft, draft-pfister-capport-pvd-00, 30 June 2018, 815 . 818 Appendix A. Existing captive portal detection implementations 820 Operating systems and user applications may perform various tests 821 when network connectivity is established to determine if the device 822 is attached to a network with a captive portal present. A common 823 method is to attempt to make a HTTP request to a known, vendor hosted 824 endpoint with a fixed response. Any other response is interpreted as 825 a signal that a captive portal is present. This check is typically 826 not secured with TLS, as a network with a captive portal may 827 intercept the connection, leading to a host name mismatch. Another 828 test that can be performed is a DNS lookup to a known address with an 829 expected answer. Such tests may be less reliable as the captive 830 portal may only be intercepting TCP traffic and deliberately 831 excluding the interception of DNS queries. DNS queries not using UDP 832 may potentially fail this test if operating over TCP or DNS over 833 HTTP. Malicious or misconfigured networks with a captive portal 834 present may not intercept these requests and choose to pass them 835 through or decide to impersonate, leading to the device having a 836 false negative. 838 Authors' Addresses 839 Kyle Larose 840 Agilicus 842 Email: kyle@agilicus.com 844 David Dolson 846 Email: ddolson@acm.org 848 Heng Liu 850 Email: liucougar@google.com