idnits 2.17.1 draft-ietf-capport-architecture-05.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 (December 31, 2019) is 1575 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7710 (Obsoleted by RFC 8910) == Outdated reference: A later version (-11) exists of draft-ietf-intarea-provisioning-domains-09 Summary: 1 error (**), 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: July 3, 2020 December 31, 2019 7 CAPPORT Architecture 8 draft-ietf-capport-architecture-05 10 Abstract 12 This document aims to document consensus on the CAPPORT architecture. 13 DHCP or Router Advertisements, an optional signaling protocol, and an 14 HTTP API are used to provide the solution. The role of Provisioning 15 Domains (PvDs) is described. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on July 3, 2020. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 53 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 54 2. Components . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 2.1. User Equipment . . . . . . . . . . . . . . . . . . . . . 5 56 2.2. Provisioning Service . . . . . . . . . . . . . . . . . . 6 57 2.2.1. DHCP or Router Advertisements . . . . . . . . . . . . 6 58 2.2.2. Provisioning Domains . . . . . . . . . . . . . . . . 6 59 2.3. Captive Portal API Server . . . . . . . . . . . . . . . . 7 60 2.4. Captive Portal Enforcement . . . . . . . . . . . . . . . 7 61 2.5. Captive Portal Signal . . . . . . . . . . . . . . . . . . 8 62 2.6. Component Diagram . . . . . . . . . . . . . . . . . . . . 9 63 3. User Equipment Identity . . . . . . . . . . . . . . . . . . . 11 64 3.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 11 65 3.2. Recommended Properties . . . . . . . . . . . . . . . . . 11 66 3.2.1. Uniquely Identify User Equipment . . . . . . . . . . 12 67 3.2.2. Hard to Spoof . . . . . . . . . . . . . . . . . . . . 12 68 3.2.3. Visible to the API . . . . . . . . . . . . . . . . . 12 69 3.2.4. Visible to the Enforcement Device . . . . . . . . . . 12 70 3.3. Evaluating an Identifier . . . . . . . . . . . . . . . . 13 71 3.4. Examples of an Identifier . . . . . . . . . . . . . . . . 13 72 3.4.1. Physical Interface . . . . . . . . . . . . . . . . . 13 73 3.4.2. IP Address . . . . . . . . . . . . . . . . . . . . . 14 74 4. Solution Workflow . . . . . . . . . . . . . . . . . . . . . . 14 75 4.1. Initial Connection . . . . . . . . . . . . . . . . . . . 15 76 4.2. Conditions About to Expire . . . . . . . . . . . . . . . 15 77 4.3. Handling of Changes in Portal URI . . . . . . . . . . . . 16 78 5. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 79 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 80 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 81 7.1. Trusting the Network . . . . . . . . . . . . . . . . . . 16 82 7.2. Authenticated APIs . . . . . . . . . . . . . . . . . . . 17 83 7.3. Secure APIs . . . . . . . . . . . . . . . . . . . . . . . 17 84 7.4. Risk of Nuisance Captive Portal . . . . . . . . . . . . . 17 85 7.5. User Options . . . . . . . . . . . . . . . . . . . . . . 17 86 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 87 8.1. Normative References . . . . . . . . . . . . . . . . . . 18 88 8.2. Informative References . . . . . . . . . . . . . . . . . 18 89 Appendix A. Existing captive portal detection implementations . 18 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 92 1. Introduction 94 In this document, "Captive Portal" is used to describe a network to 95 which a device may be voluntarily attached, such that network access 96 is limited until some requirements have been fulfilled. Typically a 97 user is required to use a web browser to fulfill requirements imposed 98 by the network operator, such as reading advertisements, accepting an 99 acceptable-use policy, or providing some form of credentials. 101 Implementations generally require a web server, some method to allow/ 102 block traffic, and some method to alert the user. Common methods of 103 alerting the user involve modifying HTTP or DNS traffic. 105 Problems with captive portal implementations have been described in 106 [I-D.nottingham-capport-problem]. [If that document cannot be 107 published, consider putting its best parts into an appendix of this 108 document.] 110 This document standardizes an architecture for implementing captive 111 portals that provides tools for addressing most of those problems. 112 We are guided by these principles: 114 o Solutions SHOULD NOT require the forging of responses from DNS or 115 HTTP servers, or any other protocol. In particular, solutions 116 SHOULD NOT require man-in-the-middle proxy of TLS traffic. 118 o Solutions MUST operate at the layer of Internet Protocol (IP) or 119 above, not being specific to any particular access technology such 120 as Cable, WiFi or 3GPP. 122 o Solutions MAY allow a device to be alerted that it is in a captive 123 network when attempting to use any application on the network. 125 o Solutions SHOULD allow a device to learn that it is in a captive 126 network before any application attempts to use the network. 128 o The state of captivity SHOULD be explicitly available to devices 129 (in contrast to modification of DNS or HTTP, which is only 130 indirectly machine-detectable by the client--by comparing 131 responses to well-known queries with expected responses). 133 o The architecture MUST provide a path of incremental migration, 134 acknowledging a huge variety of portals and end-user device 135 implementations and software versions. 137 A side-benefit of the architecture described in this document is that 138 devices without user interfaces are able to identify parameters of 139 captivity. However, this document does not yet describe a mechanism 140 for such devices to escape captivity. 142 The architecture uses the following mechanisms: 144 o Network provisioning protocols provide end-user devices with a URI 145 for the API that end-user devices query for information about what 146 is required to escape captivity. DHCP, DHCPv6, and Router- 147 Advertisement options for this purpose are available in [RFC7710]. 148 Other protocols (such as RADIUS), Provisioning Domains 149 [I-D.ietf-intarea-provisioning-domains], or static configuration 150 may also be used. A device MAY query this API at any time to 151 determine whether the network is holding the device in a captive 152 state. 154 o End-user devices can be notified of captivity with Captive Portal 155 Signals in response to traffic. This notification should work 156 with any Internet protocol, not just clear-text HTTP. This 157 notification does not carry the portal URI; rather it provides a 158 notification to the User Equipment that it is in a captive state. 159 This document will specify requirements for a signaling protocol 160 which could generate Captive Portal Signals. 162 o Receipt of a Captive Portal Signal informs an end-user device that 163 it could be captive. In response, the device MAY query the 164 provisioned API to obtain information about the network state. 165 The device MAY take immediate action to satisfy the portal 166 (according to its configuration/policy). 168 The architecture attempts to provide privacy, authentication, and 169 safety mechanisms to the extent possible. 171 1.1. Requirements Language 173 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 174 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 175 document are to be interpreted as described in RFC 2119 [RFC2119]. 177 1.2. Terminology 179 Captive Network: A network which limits communication of attached 180 devices to restricted hosts until the user has satisfied Captive 181 Portal Conditions, after which access is permitted to a wider set of 182 hosts (typically the internet). 184 Captive Portal Conditions: site-specific requirements that a user or 185 device must satisfy in order to gain access to the wider network. 187 Captive Portal Enforcement: The network equipment which enforces the 188 traffic restriction. 190 Captive Portal User Equipment: Also known as User Equipment. A 191 device which has voluntarily joined a network for purposes of 192 communicating beyond the constraints of the captive network. 194 Captive Portal Server: The web server providing a user interface for 195 assisting the user in satisfying the conditions to escape captivity. 197 Captive Portal Signal: A notification from the network used to inform 198 the User Equipment that the state of its captivity could have 199 changed. 201 Captive Portal Signaling Protocol: Also known as Signaling Protocol. 202 The protocol for communicating Captive Portal Signals. 204 2. Components 206 2.1. User Equipment 208 The User Equipment is the device that a user desires to be attached 209 to a network with full access to all hosts on the network (e.g., to 210 have Internet access). The User Equipment communication is typically 211 restricted by the Captive Portal Enforcement, described in 212 Section 2.4, until site-specific requirements have been met. 214 At this time we consider only devices with web browsers, with web 215 applications being the means of satisfying Captive Portal Conditions. 217 o An example interactive User Equipment is a smart phone. 219 o SHOULD support provisioning of the URI for the Captive Portal API 220 (e.g., by DHCP) 222 o SHOULD distinguish Captive Portal API access per network 223 interface, in the manner of Provisioning Domain Architecture 224 [RFC7556]. 226 o SHOULD have a mechanism for notifying the user of the Captive 227 Portal 229 o SHOULD have a web browser so that the user may navigate the 230 Captive Portal user interface. 232 o MAY restrict application access to networks not granting full 233 network access. E.g., a device connected to a mobile network may 234 be connecting to a WiFi network; the operating system MAY avoid 235 updating the default route until network access restrictions have 236 been lifted (excepting access to the Captive Portal server). This 237 has been termed "make before break". 239 None of the above requirements are mandatory because (a) we do not 240 wish to say users or devices must seek access beyond the captive 241 network, (b) the requirements may be fulfilled by manually visiting 242 the captive portal web application, and (c) legacy devices must 243 continue to be supported. 245 2.2. Provisioning Service 247 Here we discuss candidate mechanisms for provisioning the User 248 Equipment with the URI of the API to query captive portal state and 249 navigate the portal. 251 2.2.1. DHCP or Router Advertisements 253 A standard for providing a portal URI using DHCP or Router 254 Advertisements is described in [RFC7710]. The CAPPORT architecture 255 expects this URI to indicate the API described in Section 2.3. 257 Although it is not clear from RFC7710 what protocol should be 258 executed at the specified URI, some readers might have assumed it to 259 be an HTML page, and hence there might be User Equipment assuming a 260 browser should open this URI. For backwards compatibility, it is 261 RECOMMENDED that the server check the "Accept" field when serving the 262 URI, and serve HTML pages for "text/html" and serve the API for 263 "application/json". [REVISIT: are these details appropriate?] 265 2.2.2. Provisioning Domains 267 [I-D.ietf-intarea-provisioning-domains] proposes a mechanism for User 268 Equipment to be provided with PvD Bootstrap Information containing 269 the URI for a JSON file containing key-value pairs to be downloaded 270 over HTTPS. This JSON file would fill the role of the Captive Portal 271 API described in Section 2.3. 273 The PvD security model provides secure binding between the 274 information provided by the trusted Router Advertisement and the 275 HTTPS server. 277 One key-value pair can be used to indicate the network has restricted 278 access, requiring captive portal navigation by a user. E.g., 279 key="captivePortal" and value=. The key-value pair 280 should provide a different result when access is not restricted. 281 E.g., key="captivePortal" and value="". 283 This JSON file is extensible, allowing new key-value pairs to 284 indicate such things as network access expiry time, URI for API 285 access by IOT devices, etc. 287 The PvD server MUST support multiple (repeated) queries from each 288 User Equipment, always returning the current captive portal 289 information. The User Equipment is expected to make this query upon 290 receiving (and validating) a Captive Portal Signal (see Section 2.5). 292 2.3. Captive Portal API Server 294 The purpose of a Captive Portal API is to permit a query of Captive 295 Portal state without interrupting the user. This API thereby removes 296 the need for a device to perform clear-text "canary" HTTP queries to 297 check for response tampering. 299 The URI of this API will have been provisioned to the User Equipment. 300 (Refer to Section 2.2). 302 This architecture expects the User Equipment to query the API when 303 the User Equipment attaches to the network and multiple times 304 thereafter. Therefore the API MUST support multiple repeated queries 305 from the same User Equipment, returning the current state of 306 captivity for the equipment. 308 At minimum the API MUST provide: (1) the state of captivity and (2) a 309 URI for a browser to present the portal application to the user. The 310 API SHOULD provide evidence to the caller that it supports the 311 present architecture. 313 When user equipment receives Captive Portal Signals, the user 314 equipment MAY query the API to check the state. The User Equipment 315 SHOULD rate-limit these API queries in the event of the signal being 316 flooded. (See Section 7.) 318 The API MUST be extensible to support future use-cases by allowing 319 extensible information elements. 321 The API MUST use TLS for privacy and server authentication. The 322 implementation of the API MUST ensure both privacy and integrity of 323 any information provided by or required by it. 325 This document does not specify the details of the API. 327 2.4. Captive Portal Enforcement 329 The Captive Portal Enforcement component restricts network access to 330 User Equipment according to site-specific policy. Typically User 331 Equipment is permitted access to a small number of services and is 332 denied general network access until it has performed some action. 334 The Captive Portal Enforcement component: 336 o Allows traffic through for allowed User Equipment. 338 o Blocks (discards) traffic for disallowed User Equipment. 340 o May signal User Equipment using the Captive Portal Signaling 341 protocol if traffic is blocked. 343 o Permits disallowed User Equipment to access necessary APIs and web 344 pages to fulfill requirements of exiting captivity. 346 o Updates allow/block rules per User Equipment in response to 347 operations from the Captive Portal back-end. 349 2.5. Captive Portal Signal 351 User Equipment may send traffic outside the captive network prior to 352 the Enforcement device granting it access. The Enforcement Device 353 rightly blocks or resets these requests. However, lacking a signal 354 from the Enforcement Device or interaction with the API server, the 355 User Equipment can only guess at whether it is captive. 356 Consequently, allowing the Enforcement Device to signal to the User 357 Equipment that there is a problem with its connectivity may improve 358 the user's experience. 360 An Enforcement Device may also want to inform the User Equipment of a 361 pending expiry of its access to the external network, so providing 362 the Enforcement Device the ability to preemptively signal may be 363 desirable. 365 A specific Captive Portal Signaling Protocol is out of scope for this 366 document. However, in order to ensure that future protocols fit into 367 the architecture, requirements for a Captive Portal Signaling 368 Protocol follow: 370 1. The notification SHOULD NOT be easy to spoof. If an attacker can 371 send spoofed notifications to the User Equipment, they can cause 372 the User Equipment to unnecessarily access the API. Rather than 373 relying solely on rate limits to prevent problems, a good 374 protocol will strive to limit the feasibility of such attacks. 376 2. It SHOULD be possible to send the notification before the captive 377 portal closes. This will help ensure seamless connectivity for 378 the user, as the User Equipment will not need to wait for a 379 network failure to refresh its login. On receipt of preemptive 380 notification, the User Equipment can prompt the user to refresh. 382 3. The signal SHOULD NOT include any information other than an 383 indication that traffic is restricted, which can be used as a 384 prompt to contact the API. 386 The Captive Portal Signaling Protocol does not provide any means of 387 indicating that the network prevents access to some destinations. 388 The intent is to rely on the Captive Portal API and the web portal to 389 which it points to communicate local network policies. 391 The Captive Portal Enforcement function MAY send Captive Portal 392 Signals when disallowed User Equipment attempts to send to the 393 network. These signals MUST be rate-limited to a configurable rate. 395 The signals MUST NOT be sent to the Internet devices. The 396 indications are only sent to the User Equipment. 398 2.6. Component Diagram 399 The following diagram shows the communication between each component. 401 o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . o 402 . CAPTIVE NETWORK . 403 . +--------------+ . 404 . +------------+ Provision API URI | Provisioning | . 405 . | |<---------------------------+| Service | . 406 . | User | +--------------+ . 407 . | Equipment | Query CAPPORT status +-------------+ . 408 . | |+--------------------------->| CAPPORT API | . 409 . | | | Server | . 410 . | | +------+------+ . 411 . | | | Status . 412 . | | Portal user interface +------+------+ . 413 . | |+--------------------------->| CAPPORT | . 414 . +------------+ | web portal | . 415 . ^ ^ | +-------------+ . 416 . | | | Data | . 417 . | | +-----------------> +---------------+ Allow/Deny . 418 . | +--------------------+| | Rules . 419 . | | Captive Portal| | . 420 . | CAPPORT Signal | Enforcement | <---+ . 421 . +-------------------------+---------------+ . 422 . ^ | . 423 . | | . 424 . Data to/from external network . 425 . | | . 426 o . . . . . . . . . . . . . . . . . . .| |. . . . . . . . . . . o 427 | v 428 EXTERNAL NETWORK 430 Figure 1: Captive Portal Architecture Component Diagram 432 In the diagram: 434 o During provisioning (e.g., DHCP), the User Equipment acquires the 435 URI for the CAPPORT API. 437 o The User Equipment queries the API to learn of its state of 438 captivity. If captive, the User Equipment presents the portal 439 user interface to the user. 441 o The User Equipment attempts to communicate to the external network 442 through the Captive Portal enforcement device. 444 o The Captive Portal Enforcement device either allows the User 445 Equipment's packets to the external network, or if a signal has 446 been implemented, responds with a Captive Portal Signal. 448 o The CAPPORT web portal server directs the Captive Portal 449 Enforcement device to either allow or deny external network access 450 for the User Equipment. 452 Although the provisioning, API, and web portal functions are shown as 453 discrete blocks, they could of course be combined into a single 454 element. 456 3. User Equipment Identity 458 Multiple components in the architecture interact with both the User 459 Equipment and each other. Since the User Equipment is the focus of 460 these interactions, the components must be able to both identify the 461 user equipment from their interactions with it, and be able to agree 462 on the identity of the user equipment when interacting with each 463 other. 465 The methods by which the components interact restrict the type of 466 information that may be used as an identifying characteristics. This 467 section discusses the identifying characteristics. 469 3.1. Identifiers 471 An Identifier is a characteristic of the User Equipment used by the 472 components of a Captive Portal to uniquely determine which specific 473 User Equipment is interacting with them. An Identifier MAY be a 474 field contained in packets sent by the User Equipment to the External 475 Network. Or, an Identifier MAY be an ephemeral property not 476 contained in packets destined for the External Network, but instead 477 correlated with such information through knowledge available to the 478 different components. 480 3.2. Recommended Properties 482 The set of possible identifiers is quite large. However, in order to 483 be considered a good identifier, an identifier SHOULD meet the 484 following criteria. Note that the optimal identifier will likely 485 change depending on the position of the components in the network as 486 well as the information available to them. An identifier SHOULD: 488 o Uniquely Identify the User Equipment 490 o Be Hard to Spoof 492 o Be Visible to the API 494 o Be Visible to the Enforcement Device 495 An identifier might only apply to the current point of network 496 attachment. If the device moves to a different network location its 497 identity could change. 499 3.2.1. Uniquely Identify User Equipment 501 In order to uniquely identify the User Equipment, at most one user 502 equipment interacting with the other components of the Captive Portal 503 MUST have a given value of the identifier. 505 Over time, the user equipment identified by the value MAY change. 506 Allowing the identified device to change over time ensures that the 507 space of possible identifying values need not be overly large. 509 Independent Captive Portals MAY use the same identifying value to 510 identify different User Equipment. Allowing independent captive 511 portals to reuse identifying values allows the identifier to be a 512 property of the local network, expanding the space of possible 513 identifiers. 515 3.2.2. Hard to Spoof 517 A good identifier does not lend itself to being easily spoofed. At 518 no time should it be simple or straightforward for one User Equipment 519 to pretend to be another User Equipment, regardless of whether both 520 are active at the same time. This property is particularly important 521 when the user equipment is extended externally to devices such as 522 billing systems, or where the identity of the User Equipment could 523 imply liability. 525 3.2.3. Visible to the API 527 Since the API will need to perform operations which rely on the 528 identity of the user equipment, such as query whether it is captive, 529 the API needs to be able to relate requests to the User Equipment 530 making the request. 532 3.2.4. Visible to the Enforcement Device 534 The Enforcement Device will decide on a per packet basis whether it 535 should be permitted to communicate with the external network. Since 536 this decision depends on which User Equipment sent the packet, the 537 Enforcement Device requires that it be able to map the packet to its 538 concept of the User Equipment. 540 3.3. Evaluating an Identifier 542 To evaluate whether an identifier is appropriate, one should consider 543 every recommended property from the perspective of interactions among 544 the components in the architecture. When comparing identifiers, 545 choose the one which best satisfies all of the recommended 546 properties. The architecture does not provide an exact measure of 547 how well an identifier satisfies a given property; care should be 548 taken in performing the evaluation. 550 3.4. Examples of an Identifier 552 This section provides some examples of identifiers, along with some 553 evaluation of whether they are good identifiers. The list of 554 identifiers is not exhaustive. Other identifiers may be used. An 555 important point to note is that whether the identifiers are good 556 depends heavily on the capabilities of the components and where in 557 the network the components exist. 559 3.4.1. Physical Interface 561 The physical interface by which the User Equipment is attached to the 562 network can be used to identify the User Equipment. This identifier 563 has the property of being extremely difficult to spoof: the User 564 Equipment is unaware of the property; one User Equipment cannot 565 manipulate its interactions to appear as though it is another. 567 Further, if only a single User Equipment is attached to a given 568 physical interface, then the identifier will be unique. If multiple 569 User Equipment is attached to the network on the same physical 570 interface, then this property is not appropriate. 572 Another consideration related to uniqueness of the User Equipment is 573 that if the attached User Equipment changes, both the API server and 574 the Enforcement Device must invalidate their state related to the 575 User Equipment. 577 The Enforcement Device needs to be aware of the physical interface, 578 which constrains the environment: it must either be part of the 579 device providing physical access (e.g., implemented in firmware), or 580 packets traversing the network must be extended to include 581 information about the source physical interface (e.g. a tunnel). 583 The API server faces a similar problem, implying that it should co- 584 exist with the Enforcement Device, or that the enforcement device 585 should extend requests to it with the identifying information. 587 3.4.2. IP Address 589 A natural identifier to consider is the IP address of the User 590 Equipment. At any given time, no device on the network can have the 591 same IP address without causing the network to malfunction, so it is 592 appropriate from the perspective of uniqueness. 594 However, it may be possible to spoof the IP address, particularly for 595 malicious reasons where proper functioning of the network is not 596 necessary for the malicious actor. Consequently, any solution using 597 the IP address should proactively try to prevent spoofing of the IP 598 address. Similarly, if the mapping of IP address to User Equipment 599 is changed, the components of the architecture must remove or update 600 their mapping to prevent spoofing. Demonstrations of return 601 routeability, such as that required for TCP connection establishment, 602 might be sufficient defense against spoofing, though this might not 603 be sufficient in networks that use broadcast media (such as some 604 wireless networks). 606 Since the IP address may traverse multiple segments of the network, 607 more flexibility is afforded to the Enforcement Device and the API 608 server: they simply must exist on a segment of the network where the 609 IP address is still unique. However, consider that a NAT may be 610 deployed between the User Equipment and the Enforcement Device. In 611 such cases, it is possible for the components to still uniquely 612 identify the device if they are aware of the port mapping. 614 In some situations, the User Equipment may have multiple IP 615 addresses, while still satisfying all of the recommended properties. 616 This raises some challenges to the components of the network. For 617 example, if the user equipment tries to access the network with 618 multiple IP addresses, should the enforcement device and API server 619 treat each IP address as a unique User Equipment, or should it tie 620 the multiple addresses together into one view of the subscriber? An 621 implementation MAY do either. Attention should be paid to IPv6 and 622 the fact that it is expected for a device to have multiple IPv6 623 addresses on a single link. In such cases, identification could be 624 performed by subnet, such as the /64 to which the IP belongs. 626 4. Solution Workflow 628 This section aims to improve understanding by describing a possible 629 workflow of solutions adhering to the architecture. 631 4.1. Initial Connection 633 This section describes a possible work-flow when User Equipment 634 initially joins a Captive Network. 636 1. The User Equipment joins the Captive Network by acquiring a DHCP 637 lease, RA, or similar, acquiring provisioning information. 639 2. The User Equipment learns the URI for the Captive Portal API from 640 the provisioning information (e.g., [RFC7710]). 642 3. The User Equipment accesses the CAPPORT API to receive parameters 643 of the Captive Network, including web-portal URI. (This step 644 replaces the clear-text query to a canary URL.) 646 4. If necessary, the User navigates the web portal to gain access to 647 the external network. 649 5. The Captive Portal API server indicates to the Captive Portal 650 Enforcement device that the User Equipment is allowed to access 651 the external network. 653 6. The User Equipment attempts a connection outside the captive 654 network 656 7. If the requirements have been satisfied, the access is permitted; 657 otherwise the "Expired" behavior occurs. 659 8. The User Equipment accesses the network until conditions Expire. 661 4.2. Conditions About to Expire 663 This section describes a possible work-flow when access is about to 664 expire. 666 1. Precondition: the API server has provided the User Equipment with 667 a duration over which its access is valid 669 2. The User Equipment is communicating with the outside network 671 3. The User Equipment's UI indicates that the length of time left 672 for its access has fallen below a threshold 674 4. The User Equipment visits the API again to validate the expiry 675 time 677 5. If expiry is still imminent, the User Equipment prompts the user 678 to access the web-portal URI again 680 6. The User extends their access through the web-portal 682 7. The User Equipment's access to the outside network continues 683 uninterrupted 685 4.3. Handling of Changes in Portal URI 687 A different Captive Portal API URI could be returned in the following 688 cases: 690 o If DHCP is used, a lease renewal/rebind may return a different 691 Captive Portal API URI. 693 o If RA is used, a new Captive Portal API URI may be specified in a 694 new RA message received by end user equipment. 696 Whenever a new Portal URI is received by end user equipment, it 697 SHOULD discard the old URI and use the new one for future requests to 698 the API. 700 5. Acknowledgments 702 The authors thank Lorenzo Colitti for providing the majority of the 703 content for the Captive Portal Signal requirements. 705 The authors thank various individuals for their feedback on the 706 mailing list and during the IETF98 hackathon: David Bird, Erik Kline, 707 Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van 708 Dam. 710 6. IANA Considerations 712 This memo includes no request to IANA. 714 7. Security Considerations 716 7.1. Trusting the Network 718 When joining a network, some trust is placed in the network operator. 719 This is usually considered to be a decision by a user on the basis of 720 the reputation of an organization. However, once a user makes such a 721 decision, protocols can support authenticating a network is operated 722 by who claims to be operating it. The Provisioning Domain 723 Architecture [RFC7556] provides some discussion on authenticating an 724 operator. 726 Given that a user chooses to visit a Captive Portal URI, the URI 727 location SHOULD be securely provided to the user's device. E.g., the 728 DHCPv6 AUTH option can sign this information. 730 If a user decides to incorrectly trust an attacking network, they 731 might be convinced to visit an attacking web page and unwittingly 732 provide credentials to an attacker. Browsers can authenticate 733 servers but cannot detect cleverly misspelled domains, for example. 735 7.2. Authenticated APIs 737 The solution described here assumes that when the User Equipment 738 needs to trust the API server, server authentication will be 739 performed using TLS mechanisms. 741 7.3. Secure APIs 743 The solution described here requires that the API be secured using 744 TLS. This is required to allow the user equipment and API server to 745 exchange secrets which can be used to validate future interactions. 746 The API must ensure the integrity of this information, as well as its 747 confidentiality. 749 7.4. Risk of Nuisance Captive Portal 751 If a Signaling Protocol is implemented, it may be possible for any 752 user on the Internet to send signals in attempt to cause the 753 receiving equipment to communicate with the Captive Portal API. This 754 has been considered, and implementations may address it in the 755 following ways: 757 o The signal only informs the User Equipment to query the API. It 758 does not carry any information which may mislead or misdirect the 759 User Equipment. 761 o Even when responding to the signal, the User Equipment securely 762 authenticates with API servers. 764 o Accesses to the API server are rate limited, limiting the impact 765 of a repeated attack. 767 7.5. User Options 769 The Signal could inform the User Equipment that it is being held 770 captive. There is no requirement that the User Equipment do 771 something about this. Devices MAY permit users to disable automatic 772 reaction to captive-portal indications for privacy reasons. However, 773 there is the trade-off that the user doesn't get notified when 774 network access is restricted. Hence, end-user devices MAY allow 775 users to manually control captive portal interactions, possibly on 776 the granularity of Provisioning Domains. 778 8. References 780 8.1. Normative References 782 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 783 Requirement Levels", BCP 14, RFC 2119, 784 DOI 10.17487/RFC2119, March 1997, 785 . 787 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 788 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 789 . 791 [RFC7710] Kumari, W., Gudmundsson, O., Ebersman, P., and S. Sheng, 792 "Captive-Portal Identification Using DHCP or Router 793 Advertisements (RAs)", RFC 7710, DOI 10.17487/RFC7710, 794 December 2015, . 796 8.2. Informative References 798 [I-D.ietf-intarea-provisioning-domains] 799 Pfister, P., Vyncke, E., Pauly, T., Schinazi, D., and W. 800 Shao, "Discovering Provisioning Domain Names and Data", 801 draft-ietf-intarea-provisioning-domains-09 (work in 802 progress), December 2019. 804 [I-D.nottingham-capport-problem] 805 Nottingham, M., "Captive Portals Problem Statement", 806 draft-nottingham-capport-problem-01 (work in progress), 807 April 2016. 809 Appendix A. Existing captive portal detection implementations 811 Operating systems and user applications may perform various tests 812 when network connectivity is established to determine if the device 813 is attached to a network with a captive portal present. A common 814 method is to attempt to make a HTTP request to a known, vendor hosted 815 endpoint with a fixed response. Any other response is interpreted as 816 a signal that a captive portal is present. This check is typically 817 not secured with TLS, as a network with a captive portal may 818 intercept the connection, leading to a host name mismatch. Another 819 test that can be performed is a DNS lookup to a known address with an 820 expected answer. Such tests may be less reliable as the captive 821 portal may only be intercepting TCP traffic and deliberately 822 excluding the interception of DNS queries. DNS queries not using UDP 823 may potentially fail this test if operating over TCP or DNS over 824 HTTP. Malicious or misconfigured networks with a captive portal 825 present may not intercept these requests and choose to pass them 826 through or decide to impersonate, leading to the device having a 827 false negative. 829 Authors' Addresses 831 Kyle Larose 832 Agilicus 834 Email: kyle@agilicus.com 836 David Dolson 838 Email: ddolson@acm.org