idnits 2.17.1 draft-ietf-capport-architecture-08.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 (11 May 2020) is 1438 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) == 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: 1 error (**), 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: 12 November 2020 6 H. Liu 7 Google 8 11 May 2020 10 CAPPORT Architecture 11 draft-ietf-capport-architecture-08 13 Abstract 15 This document describes a CAPPORT architecture. DHCP or Router 16 Advertisements, an optional signaling protocol, and an HTTP API are 17 used to provide the solution. The role of Provisioning Domains 18 (PvDs) is described. 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 12 November 2020. 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 . . . . . . . . . . . . . . . . . . 4 55 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 56 2. Components . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.1. User Equipment . . . . . . . . . . . . . . . . . . . . . 5 58 2.2. Provisioning Service . . . . . . . . . . . . . . . . . . 6 59 2.2.1. DHCP or Router Advertisements . . . . . . . . . . . . 6 60 2.2.2. Provisioning Domains . . . . . . . . . . . . . . . . 6 61 2.3. Captive Portal API Server . . . . . . . . . . . . . . . . 7 62 2.4. Captive Portal Enforcement Device . . . . . . . . . . . . 7 63 2.5. Captive Portal Signal . . . . . . . . . . . . . . . . . . 8 64 2.6. Component Diagram . . . . . . . . . . . . . . . . . . . . 8 65 3. User Equipment Identity . . . . . . . . . . . . . . . . . . . 10 66 3.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 10 67 3.2. Recommended Properties . . . . . . . . . . . . . . . . . 10 68 3.2.1. Uniquely Identify User Equipment . . . . . . . . . . 11 69 3.2.2. Hard to Spoof . . . . . . . . . . . . . . . . . . . . 11 70 3.2.3. Visible to the API Server . . . . . . . . . . . . . . 11 71 3.2.4. Visible to the Enforcement Device . . . . . . . . . . 11 72 3.3. Evaluating Types of Identifiers . . . . . . . . . . . . . 12 73 3.4. Example Identifier Types . . . . . . . . . . . . . . . . 12 74 3.4.1. Physical Interface . . . . . . . . . . . . . . . . . 12 75 3.4.2. IP Address . . . . . . . . . . . . . . . . . . . . . 13 76 3.5. Context-free URI . . . . . . . . . . . . . . . . . . . . 13 77 4. Solution Workflow . . . . . . . . . . . . . . . . . . . . . . 14 78 4.1. Initial Connection . . . . . . . . . . . . . . . . . . . 14 79 4.2. Conditions About to Expire . . . . . . . . . . . . . . . 15 80 4.3. Handling of Changes in Portal URI . . . . . . . . . . . . 15 81 5. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 82 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 83 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 84 7.1. Trusting the Network . . . . . . . . . . . . . . . . . . 16 85 7.2. Authenticated APIs . . . . . . . . . . . . . . . . . . . 16 86 7.3. Secure APIs . . . . . . . . . . . . . . . . . . . . . . . 17 87 7.4. Risks Associated with the Signaling Protocol . . . . . . 17 88 7.5. User Options . . . . . . . . . . . . . . . . . . . . . . 17 89 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 90 8.1. Normative References . . . . . . . . . . . . . . . . . . 17 91 8.2. Informative References . . . . . . . . . . . . . . . . . 18 92 Appendix A. Existing Captive Portal Detection Implementations . 19 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 95 1. Introduction 97 In this document, "Captive Portal" is used to describe a network to 98 which a device may be voluntarily attached, such that network access 99 is limited until some requirements have been fulfilled. Typically a 100 user is required to use a web browser to fulfill requirements imposed 101 by the network operator, such as reading advertisements, accepting an 102 acceptable-use policy, or providing some form of credentials. 104 Implementations generally require a web server, some method to allow/ 105 block traffic, and some method to alert the user. Common methods of 106 alerting the user involve modifying HTTP or DNS traffic. 108 This document standardizes an architecture for implementing captive 109 portals while addressing most of the problems arising for current 110 captive portal mechanisms. The architecture is guided by these 111 principles: 113 * Solutions SHOULD NOT require the forging of responses from DNS or 114 HTTP servers, or any other protocol. In particular, solutions 115 SHOULD NOT require man-in-the-middle proxy of TLS traffic. 117 * Solutions MUST operate at the layer of Internet Protocol (IP) or 118 above, not being specific to any particular access technology such 119 as Cable, WiFi or mobile telecom. 121 * Solutions MAY allow a device to be alerted that it is in a captive 122 network when attempting to use any application on the network. 124 * Solutions SHOULD allow a device to learn that it is in a captive 125 network before any application attempts to use the network. 127 * The state of captivity SHOULD be explicitly available to devices 128 (in contrast to modification of DNS or HTTP, which is only 129 indirectly machine-detectable by the client when it compares 130 responses to well-known queries with expected responses). 132 * The architecture MUST provide a path of incremental migration, 133 acknowledging a huge variety of portals and end-user device 134 implementations and software versions. 136 A side-benefit of the architecture described in this document is that 137 devices without user interfaces are able to identify parameters of 138 captivity. However, this document does not yet describe a mechanism 139 for such devices to escape captivity. 141 The architecture uses the following mechanisms: 143 * Network provisioning protocols provide end-user devices with a 144 Uniform Resource Identifier [RFC3986] (URI) for the API that end- 145 user devices query for information about what is required to 146 escape captivity. DHCP, DHCPv6, and Router-Advertisement options 147 for this purpose are available in [RFC7710bis]. Other protocols 148 (such as RADIUS), Provisioning Domains [I-D.pfister-capport-pvd], 149 or static configuration may also be used. A device MAY query this 150 API at any time to determine whether the network is holding the 151 device in a captive state. 153 * End-user devices can be notified of captivity with Captive Portal 154 Signals in response to traffic. This notification works in 155 response to any Internet protocol, and is not done by modifying 156 protocols in-band. This notification does not carry the portal 157 URI; rather it provides a notification to the User Equipment that 158 it is in a captive state. 160 * Receipt of a Captive Portal Signal informs an end-user device that 161 it could be captive. In response, the device MAY query the 162 provisioned API to obtain information about the network state. 163 The device MAY take immediate action to satisfy the portal 164 (according to its configuration/policy). 166 The architecture attempts to provide confidentiality, authentication, 167 and safety mechanisms to the extent possible. 169 1.1. Requirements Language 171 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 172 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 173 "OPTIONAL" in this document are to be interpreted as described in BCP 174 14 [RFC2119] [RFC8174] when, and only when, they appear in all 175 capitals, as shown here. 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 Device: The network equipment which 188 enforces the traffic restriction. Also known as Enforcement Device. 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 API: Also known as API. An HTTP API allowing User 198 Equipment to query its state of captivity within the Captive Portal. 200 Captive Portal API Server: Also known as API Server. A server 201 hosting the Captive Portal API. 203 Captive Portal Signal: A notification from the network used to inform 204 the User Equipment that the state of its captivity could have 205 changed. 207 Captive Portal Signaling Protocol: Also known as Signaling Protocol. 208 The protocol for communicating Captive Portal Signals. 210 2. Components 212 2.1. User Equipment 214 The User Equipment is the device that a user desires to be attached 215 to a network with full access to all hosts on the network (e.g., to 216 have Internet access). The User Equipment communication is typically 217 restricted by the Enforcement Device, described in Section 2.4, until 218 site-specific requirements have been met. 220 At this time we consider only devices with web browsers, with web 221 applications being the means of satisfying Captive Portal Conditions. 222 An example interactive User Equipment is a smart phone. 224 The User Equipment: 226 * SHOULD support provisioning of the URI for the Captive Portal API 227 (e.g., by DHCP) 229 * SHOULD distinguish Captive Portal API access per network 230 interface, in the manner of Provisioning Domain Architecture 231 [RFC7556]. 233 * SHOULD have a mechanism for notifying the user of the Captive 234 Portal 236 * SHOULD have a web browser so that the user may navigate the 237 Captive Portal user interface. 239 * MAY prevent applications from using networks that do not grant 240 full network access. E.g., a device connected to a mobile network 241 may be connecting to a captive WiFi network; the operating system 242 MAY avoid updating the default route until network access 243 restrictions have been lifted (excepting access to the Captive 244 Portal server) in the new network. This has been termed "make 245 before break". 247 None of the above requirements are mandatory because (a) we do not 248 wish to say users or devices must seek full access to 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 If User Equipment supports the Captive Portal API, it MUST validate 254 the API server's TLS certificate (see [RFC2818]). An Enforcement 255 Device SHOULD allow access to any services that User Equipment could 256 need to contact to perform certificate validation, such as OCSP 257 responders, CRLs, and NTP servers; see Section 4.1 of 258 [I-D.ietf-capport-api] for more information. If certificate 259 validation fails, User Equipment MUST NOT proceed with any of the 260 behavior described above. 262 2.2. Provisioning Service 264 Here we discuss candidate mechanisms for provisioning the User 265 Equipment with the URI of the API to query captive portal state and 266 navigate the portal. 268 2.2.1. DHCP or Router Advertisements 270 A standard for providing a portal URI using DHCP or Router 271 Advertisements is described in [RFC7710bis]. The CAPPORT 272 architecture expects this URI to indicate the API described in 273 Section 2.3. 275 2.2.2. Provisioning Domains 277 Although still a work in progress, [I-D.pfister-capport-pvd] proposes 278 a mechanism for User Equipment to be provided with PvD Bootstrap 279 Information containing the URI for the JSON-based API described in 280 Section 2.3. 282 2.3. Captive Portal API Server 284 The purpose of a Captive Portal API is to permit a query of Captive 285 Portal state without interrupting the user. This API thereby removes 286 the need for User Equipment to perform clear-text "canary" HTTP 287 queries to check for response tampering. 289 The URI of this API will have been provisioned to the User Equipment. 290 (Refer to Section 2.2). 292 This architecture expects the User Equipment to query the API when 293 the User Equipment attaches to the network and multiple times 294 thereafter. Therefore the API MUST support multiple repeated queries 295 from the same User Equipment and return the state of captivity for 296 the equipment. 298 At minimum, the API MUST provide: (1) the state of captivity and (2) 299 a URI for the Captive Portal Server. 301 A caller to the API needs to be presented with evidence that the 302 content it is receiving is for a version of the API that it supports. 303 For an HTTP-based interaction, such as in [I-D.ietf-capport-api] this 304 might be achieved by using a content type that is unique to the 305 protocol. 307 When User Equipment receives Captive Portal Signals, the User 308 Equipment MAY query the API to check the state. The User Equipment 309 SHOULD rate-limit these API queries in the event of the signal being 310 flooded. (See Section 7.) 312 The API MUST be extensible to support future use-cases by allowing 313 extensible information elements. 315 The API MUST use TLS to ensure server authentication. The 316 implementation of the API MUST ensure both confidentiality and 317 integrity of any information provided by or required by it. 319 This document does not specify the details of the API. 321 2.4. Captive Portal Enforcement Device 323 The Enforcement Device component restricts the network access of User 324 Equipment according to site-specific policy. Typically User 325 Equipment is permitted access to a small number of services and is 326 denied general network access until it satisfies the Captive Portal 327 Conditions. 329 The Enforcement Device component: 331 * Allows traffic to pass for User Equipment that is permitted to use 332 the network and has satisfied the Captive Portal Conditions. 334 * Blocks (discards) traffic according to the site-specific policy 335 for User Equipment that has not yet satisfied the Captive Portal 336 Conditions. 338 * May signal User Equipment using the Captive Portal Signaling 339 protocol if certain traffic is blocked. 341 * Permits User Equipment that has not satisfied the Captive Portal 342 Conditions to access necessary APIs and web pages to fulfill 343 requirements for escaping captivity. 345 * Updates allow/block rules per User Equipment in response to 346 operations from the Captive Portal Server. 348 2.5. Captive Portal Signal 350 When User Equipment first connects to a network, or when there are 351 changes in status, the Enforcement Device could generate a signal 352 toward the User Equipment. This signal indicates that the User 353 Equipment might need to contact the API Server to receive updated 354 information. For instance, this signal might be generated when the 355 end of a session is imminent, or when network access was denied. 357 An Enforcement Device MUST rate-limit any signal generated in 358 response to these conditions. See Section 7.4 for a discussion of 359 risks related to a Captive Portal Signal. 361 2.6. Component Diagram 363 The following diagram shows the communication between each component. 365 o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . o 366 . CAPTIVE NETWORK . 367 . +--------------+ . 368 . +------------+ Provision API URI | Provisioning | . 369 . | |<---------------------------+| Service | . 370 . | User | +--------------+ . 371 . | Equipment | Query captivity status +-------------+ . 372 . | |+--------------------------->| API | . 373 . | | Captivity status response | Server | . 374 . | |<---------------------------+| | . 375 . | | +------+------+ . 376 . | | | Status . 377 . | | Portal UI page requests +------+------+ . 378 . | |+--------------------------->| Web Portal | . 379 . | | Portal UI pages | Server | . 380 . | |<---------------------------+| | . 381 . +------------+ | | . 382 . ^ ^ | +-------------+ . 383 . | | | Data to/from ext. network | . 384 . | | +-----------------> +---------------+ Allow/Deny . 385 . | +--------------------+| | Rules . 386 . | | Enforcement | | . 387 . | Captive Portal Signal | Device | <---+ . 388 . +-------------------------+---------------+ . 389 . ^ | . 390 . | | . 391 . Data to/from external network . 392 . | | . 393 o . . . . . . . . . . . . . . . . . . .| |. . . . . . . . . . . o 394 | v 395 EXTERNAL NETWORK 397 Figure 1: Captive Portal Architecture Component Diagram 399 In the diagram: 401 * During provisioning (e.g., DHCP), the User Equipment acquires the 402 URI for the Captive Portal API. 404 * The User Equipment queries the API to learn of its state of 405 captivity. If captive, the User Equipment presents the portal 406 user interface from the Web Portal Server to the user. 408 * Based on user interaction, the Web Portal Server directs the 409 Enforcement Device to either allow or deny external network access 410 for the User Equipment. 412 * The User Equipment attempts to communicate to the external network 413 through the Enforcement Device. 415 * The Enforcement Device either allows the User Equipment's packets 416 to the external network, or blocks the packets. If blocking 417 traffic and a signal has been implemented, it may respond with a 418 Captive Portal Signal. 420 Although the Provisioning Service, API Server, and Web Portal Server 421 functions are shown as discrete blocks, they could of course be 422 combined into a single element. 424 3. User Equipment Identity 426 Multiple components in the architecture interact with both the User 427 Equipment and each other. Since the User Equipment is the focus of 428 these interactions, the components must be able to both identify the 429 User Equipment from their interactions with it, and to agree on the 430 identity of the User Equipment when interacting with each other. 432 The methods by which the components interact restrict the type of 433 information that may be used as an identifying characteristics. This 434 section discusses the identifying characteristics. 436 3.1. Identifiers 438 An Identifier is a characteristic of the User Equipment used by the 439 components of a Captive Portal to uniquely determine which specific 440 User Equipment is interacting with them. An Identifier MAY be a 441 field contained in packets sent by the User Equipment to the External 442 Network. Or, an Identifier MAY be an ephemeral property not 443 contained in packets destined for the External Network, but instead 444 correlated with such information through knowledge available to the 445 different components. 447 3.2. Recommended Properties 449 The set of possible identifiers is quite large. However, in order to 450 be considered a good identifier, an identifier SHOULD meet the 451 following criteria. Note that the optimal identifier will likely 452 change depending on the position of the components in the network as 453 well as the information available to them. An identifier SHOULD: 455 * Uniquely Identify the User Equipment 457 * Be Hard to Spoof 459 * Be Visible to the API Server 460 * Be Visible to the Enforcement Device 462 An identifier might only apply to the current point of network 463 attachment. If the device moves to a different network location its 464 identity could change. 466 3.2.1. Uniquely Identify User Equipment 468 Each instance of User Equipment interacting with the Captive Network 469 MUST be given an identifier that is unique among User Equipment 470 interacting at that time. 472 Over time, the User Equipment assigned to an identifier value MAY 473 change. Allowing the identified device to change over time ensures 474 that the space of possible identifying values need not be overly 475 large. 477 Independent Captive Portals MAY use the same identifying value to 478 identify different User Equipment. Allowing independent captive 479 portals to reuse identifying values allows the identifier to be a 480 property of the local network, expanding the space of possible 481 identifiers. 483 3.2.2. Hard to Spoof 485 A good identifier does not lend itself to being easily spoofed. At 486 no time should it be simple or straightforward for one User Equipment 487 to pretend to be another User Equipment, regardless of whether both 488 are active at the same time. This property is particularly important 489 when the User Equipment is extended externally to devices such as 490 billing systems, or where the identity of the User Equipment could 491 imply liability. 493 3.2.3. Visible to the API Server 495 Since the API Server will need to perform operations which rely on 496 the identity of the User Equipment, such as answering a query about 497 whether the User Equipment is captive, the API Server needs to be 498 able to relate a request to the User Equipment making the request. 500 3.2.4. Visible to the Enforcement Device 502 The Enforcement Device will decide on a per-packet basis whether the 503 packet should be forwarded to the external network. Since this 504 decision depends on which User Equipment sent the packet, the 505 Enforcement Device requires that it be able to map the packet to its 506 concept of the User Equipment. 508 3.3. Evaluating Types of Identifiers 510 To evaluate whether a type of identifier is appropriate, one should 511 consider every recommended property from the perspective of 512 interactions among the components in the architecture. When 513 comparing identifier types, choose the one which best satisfies all 514 of the recommended properties. The architecture does not provide an 515 exact measure of how well an identifier type satisfies a given 516 property; care should be taken in performing the evaluation. 518 3.4. Example Identifier Types 520 This section provides some example identifier types, along with some 521 evaluation of whether they are suitable types. The list of 522 identifier types is not exhaustive. Other types may be used. An 523 important point to note is that whether a given identifier type is 524 suitable depends heavily on the capabilities of the components and 525 where in the network the components exist. 527 3.4.1. Physical Interface 529 The physical interface by which the User Equipment is attached to the 530 network can be used to identify the User Equipment. This identifier 531 type has the property of being extremely difficult to spoof: the User 532 Equipment is unaware of the property; one User Equipment cannot 533 manipulate its interactions to appear as though it is another. 535 Further, if only a single User Equipment is attached to a given 536 physical interface, then the identifier will be unique. If multiple 537 User Equipment is attached to the network on the same physical 538 interface, then this type is not appropriate. 540 Another consideration related to uniqueness of the User Equipment is 541 that if the attached User Equipment changes, both the API Server and 542 the Enforcement Device MUST invalidate their state related to the 543 User Equipment. 545 The Enforcement Device needs to be aware of the physical interface, 546 which constrains the environment: it must either be part of the 547 device providing physical access (e.g., implemented in firmware), or 548 packets traversing the network must be extended to include 549 information about the source physical interface (e.g. a tunnel). 551 The API Server faces a similar problem, implying that it should co- 552 exist with the Enforcement Device, or that the Enforcement Device 553 should extend requests to it with the identifying information. 555 3.4.2. IP Address 557 A natural identifier type to consider is the IP address of the User 558 Equipment. At any given time, no device on the network can have the 559 same IP address without causing the network to malfunction, so it is 560 appropriate from the perspective of uniqueness. 562 However, it may be possible to spoof the IP address, particularly for 563 malicious reasons where proper functioning of the network is not 564 necessary for the malicious actor. Consequently, any solution using 565 the IP address SHOULD proactively try to prevent spoofing of the IP 566 address. Similarly, if the mapping of IP address to User Equipment 567 is changed, the components of the architecture MUST remove or update 568 their mapping to prevent spoofing. Demonstrations of return 569 routeability, such as that required for TCP connection establishment, 570 might be sufficient defense against spoofing, though this might not 571 be sufficient in networks that use broadcast media (such as some 572 wireless networks). 574 Since the IP address may traverse multiple segments of the network, 575 more flexibility is afforded to the Enforcement Device and the API 576 Server: they simply must exist on a segment of the network where the 577 IP address is still unique. However, consider that a NAT may be 578 deployed between the User Equipment and the Enforcement Device. In 579 such cases, it is possible for the components to still uniquely 580 identify the device if they are aware of the port mapping. 582 In some situations, the User Equipment may have multiple IP 583 addresses, while still satisfying all of the recommended properties. 584 This raises some challenges to the components of the network. For 585 example, if the User Equipment tries to access the network with 586 multiple IP addresses, should the Enforcement Device and API Server 587 treat each IP address as a unique User Equipment, or should it tie 588 the multiple addresses together into one view of the subscriber? An 589 implementation MAY do either. Attention should be paid to IPv6 and 590 the fact that it is expected for a device to have multiple IPv6 591 addresses on a single link. In such cases, identification could be 592 performed by subnet, such as the /64 to which the IP belongs. 594 3.5. Context-free URI 596 A Captive Portal API needs to present information to clients that is 597 unique to that client. To do this, some systems use information from 598 the context of a request, such as the source address, to identify the 599 UE. 601 Using information from context rather than information from the URI 602 allows the same URI to be used for different clients. However, it 603 also means that the resource is unable to provide relevant 604 information if the UE makes a request using a different network path. 605 This might happen when UE has multiple network interfaces. It might 606 also happen if the address of the API provided by DNS depends on 607 where the query originates (as in split DNS [RFC8499]). 609 Accessing the API MAY depend on contextual information. However, the 610 URIs provided in the API SHOULD be unique to the UE and not dependent 611 on contextual information to function correctly. 613 Though a URI might still correctly resolve when the UE makes the 614 request from a different network, it is possible that some functions 615 could be limited to when the UE makes requests using the captive 616 network. For example, payment options could be absent or a warning 617 could be displayed to indicate the payment is not for the current 618 connection. 620 URIs could include some means of identifying the User Equipment in 621 the URIs. However, including unauthenticated User Equipment 622 identifiers in the URI may expose the service to spoofing or replay 623 attacks. 625 4. Solution Workflow 627 This section aims to improve understanding by describing a possible 628 workflow of solutions adhering to the architecture. 630 4.1. Initial Connection 632 This section describes a possible workflow when User Equipment 633 initially joins a Captive Network. 635 1. The User Equipment joins the Captive Network by acquiring a DHCP 636 lease, RA, or similar, acquiring provisioning information. 638 2. The User Equipment learns the URI for the Captive Portal API from 639 the provisioning information (e.g., [RFC7710bis]). 641 3. The User Equipment accesses the Captive Portal API to receive 642 parameters of the Captive Network, including web-portal URI. 643 (This step replaces the clear-text query to a canary URI.) 645 4. If necessary, the User navigates the web portal to gain access to 646 the external network. 648 5. The Captive Portal API server indicates to the Enforcement Device 649 that the User Equipment is allowed to access the external 650 network. 652 6. The User Equipment attempts a connection outside the captive 653 network 655 7. If the requirements have been satisfied, the access is permitted; 656 otherwise the "Expired" behavior occurs. 658 8. The User Equipment accesses the network until conditions Expire. 660 4.2. Conditions About to Expire 662 This section describes a possible workflow when access is about to 663 expire. 665 1. Precondition: the API has provided the User Equipment with a 666 duration over which its access is valid 668 2. The User Equipment is communicating with the outside network 670 3. The User Equipment's UI indicates that the length of time left 671 for its access has fallen below a threshold 673 4. The User Equipment visits the API again to validate the expiry 674 time 676 5. If expiry is still imminent, the User Equipment prompts the user 677 to access the web-portal URI again 679 6. The User extends their access through the web-portal 681 7. The User Equipment's access to the outside network continues 682 uninterrupted 684 4.3. Handling of Changes in Portal URI 686 A different Captive Portal API URI could be returned in the following 687 cases: 689 * If DHCP is used, a lease renewal/rebind may return a different 690 Captive Portal API URI. 692 * If RA is used, a new Captive Portal API URI may be specified in a 693 new RA message received by end User Equipment. 695 Whenever a new Portal URI is received by end User Equipment, it 696 SHOULD discard the old URI and use the new one for future requests to 697 the API. 699 5. Acknowledgments 701 The authors thank Lorenzo Colitti for providing the majority of the 702 content for the Captive Portal Signal requirements. 704 The authors thank various individuals for their feedback on the 705 mailing list and during the IETF98 hackathon: David Bird, Erik Kline, 706 Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van 707 Dam. 709 6. IANA Considerations 711 This memo includes no request to IANA. 713 7. Security Considerations 715 7.1. Trusting the Network 717 When joining a network, some trust is placed in the network operator. 718 This is usually considered to be a decision by a user on the basis of 719 the reputation of an organization. However, once a user makes such a 720 decision, protocols can support authenticating that a network is 721 operated by who claims to be operating it. The Provisioning Domain 722 Architecture [RFC7556] provides some discussion on authenticating an 723 operator. 725 Given that a user chooses to visit a Captive Portal URI, the URI 726 location SHOULD be securely provided to the user's device. E.g., the 727 DHCPv6 AUTH option can sign this information. 729 If a user decides to incorrectly trust an attacking network, they 730 might be convinced to visit an attacking web page and unwittingly 731 provide credentials to an attacker. Browsers can authenticate 732 servers but cannot detect cleverly misspelled domains, for example. 734 7.2. Authenticated APIs 736 The solution described here assumes that when the User Equipment 737 needs to trust the API server, server authentication will be 738 performed using TLS mechanisms. 740 7.3. Secure APIs 742 The solution described here requires that the API be secured using 743 TLS. This is required to allow the User Equipment and API Server to 744 exchange secrets which can be used to validate future interactions. 745 The API MUST ensure the integrity of this information, as well as its 746 confidentiality. 748 7.4. Risks Associated with the Signaling Protocol 750 If a Signaling Protocol is implemented, it may be possible for any 751 user on the Internet to send signals in attempt to cause the 752 receiving equipment to communicate with the Captive Portal API. This 753 has been considered, and implementations may address it in the 754 following ways: 756 * The signal only informs the User Equipment to query the API. It 757 does not carry any information which may mislead or misdirect the 758 User Equipment. 760 * Even when responding to the signal, the User Equipment securely 761 authenticates with API Servers. 763 * Accesses to the API Server are rate limited, limiting the impact 764 of a repeated attack. 766 7.5. User Options 768 The Captive Portal Signal could inform the User Equipment that it is 769 being held captive. There is no requirement that the User Equipment 770 do something about this. Devices MAY permit users to disable 771 automatic reaction to Captive Portal Signals indications for privacy 772 reasons. However, there would be the trade-off that the user doesn't 773 get notified when network access is restricted. Hence, end-user 774 devices MAY allow users to manually control captive portal 775 interactions, possibly on the granularity of Provisioning Domains. 777 8. References 779 8.1. Normative References 781 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 782 Requirement Levels", BCP 14, RFC 2119, 783 DOI 10.17487/RFC2119, March 1997, 784 . 786 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 787 DOI 10.17487/RFC2818, May 2000, 788 . 790 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 791 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 792 . 794 [RFC7710bis] 795 Kumari, W. and E. Kline, "Captive-Portal Identification in 796 DHCP / RA", Work in Progress, Internet-Draft, draft-ietf- 797 capport-rfc7710bis-01, 12 January 2020, 798 . 801 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 802 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 803 May 2017, . 805 8.2. Informative References 807 [I-D.ietf-capport-api] 808 Pauly, T. and D. Thakore, "Captive Portal API", Work in 809 Progress, Internet-Draft, draft-ietf-capport-api-06, 31 810 March 2020, 811 . 813 [I-D.pfister-capport-pvd] 814 Pfister, P. and T. Pauly, "Using Provisioning Domains for 815 Captive Portal Discovery", Work in Progress, Internet- 816 Draft, draft-pfister-capport-pvd-00, 30 June 2018, 817 . 820 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 821 Resource Identifier (URI): Generic Syntax", STD 66, 822 RFC 3986, DOI 10.17487/RFC3986, January 2005, 823 . 825 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 826 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 827 January 2019, . 829 Appendix A. Existing Captive Portal Detection Implementations 831 Operating systems and user applications may perform various tests 832 when network connectivity is established to determine if the device 833 is attached to a network with a captive portal present. A common 834 method is to attempt to make a HTTP request to a known, vendor-hosted 835 endpoint with a fixed response. Any other response is interpreted as 836 a signal that a captive portal is present. This check is typically 837 not secured with TLS, as a network with a captive portal may 838 intercept the connection, leading to a host name mismatch. This has 839 been referred to as a "canary" request because, like the canary in 840 the coal mine, it can be the first sign that something is wrong. 842 Another test that can be performed is a DNS lookup to a known address 843 with an expected answer. If the answer differs from the expected 844 answer, the equipment detects that a captive portal is present. DNS 845 queries over TCP or HTTPS are less likely to be modified than DNS 846 queries over UDP due to the complexity of implementation. 848 The different tests may produce different conclusions, varying by 849 whether or not the implementation treats both TCP and UDP traffic, 850 and by which types of DNS are intercepted. 852 Malicious or misconfigured networks with a captive portal present may 853 not intercept these requests and choose to pass them through or 854 decide to impersonate, leading to the device having a false negative. 856 Authors' Addresses 858 Kyle Larose 859 Agilicus 861 Email: kyle@agilicus.com 863 David Dolson 865 Email: ddolson@acm.org 867 Heng Liu 868 Google 870 Email: liucougar@google.com