idnits 2.17.1 draft-ietf-capport-architecture-07.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 (20 April 2020) is 1466 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: 22 October 2020 6 H. Liu 7 Google 8 20 April 2020 10 CAPPORT Architecture 11 draft-ietf-capport-architecture-07 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 22 October 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 . . . . . . . . . . . . . . . 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 an Identifier . . . . . . . . . . . . . . . . 12 73 3.4. Examples of an Identifier . . . . . . . . . . . . . . . . 12 74 3.4.1. Physical Interface . . . . . . . . . . . . . . . . . 12 75 3.4.2. IP Address . . . . . . . . . . . . . . . . . . . . . 13 76 3.4.3. Context-free URL . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . . . . . . . . . . 16 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 . 18 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 that provides tools for addressing most of those problems. 110 We are guided by these principles: 112 * Solutions SHOULD NOT require the forging of responses from DNS or 113 HTTP servers, or any other protocol. In particular, solutions 114 SHOULD NOT require man-in-the-middle proxy of TLS traffic. 116 * Solutions MUST operate at the layer of Internet Protocol (IP) or 117 above, not being specific to any particular access technology such 118 as Cable, WiFi or 3GPP. 120 * Solutions MAY allow a device to be alerted that it is in a captive 121 network when attempting to use any application on the network. 123 * Solutions SHOULD allow a device to learn that it is in a captive 124 network before any application attempts to use the network. 126 * The state of captivity SHOULD be explicitly available to devices 127 (in contrast to modification of DNS or HTTP, which is only 128 indirectly machine-detectable by the client when it compares 129 responses to well-known queries with expected responses). 131 * The architecture MUST provide a path of incremental migration, 132 acknowledging a huge variety of portals and end-user device 133 implementations and software versions. 135 A side-benefit of the architecture described in this document is that 136 devices without user interfaces are able to identify parameters of 137 captivity. However, this document does not yet describe a mechanism 138 for such devices to escape captivity. 140 The architecture uses the following mechanisms: 142 * Network provisioning protocols provide end-user devices with a URI 143 for the API that end-user devices query for information about what 144 is required to escape captivity. DHCP, DHCPv6, and Router- 145 Advertisement options for this purpose are available in 146 [RFC7710bis]. Other protocols (such as RADIUS), Provisioning 147 Domains [I-D.pfister-capport-pvd], or static configuration may 148 also be used. A device MAY query this API at any time to 149 determine whether the network is holding the device in a captive 150 state. 152 * End-user devices can be notified of captivity with Captive Portal 153 Signals in response to traffic. This notification should work 154 with any Internet protocol, not just clear-text HTTP. This 155 notification does not carry the portal URI; rather it provides a 156 notification to the User Equipment that it is in a captive state. 158 * Receipt of a Captive Portal Signal informs an end-user device that 159 it could be captive. In response, the device MAY query the 160 provisioned API to obtain information about the network state. 161 The device MAY take immediate action to satisfy the portal 162 (according to its configuration/policy). 164 The architecture attempts to provide confidentiality, authentication, 165 and safety mechanisms to the extent possible. 167 1.1. Requirements Language 169 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 170 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 171 "OPTIONAL" in this document are to be interpreted as described in BCP 172 14 [RFC2119] [RFC8174] when, and only when, they appear in all 173 capitals, as shown here. 175 1.2. Terminology 177 Captive Network: A network which limits communication of attached 178 devices to restricted hosts until the user has satisfied Captive 179 Portal Conditions, after which access is permitted to a wider set of 180 hosts (typically the internet). 182 Captive Portal Conditions: site-specific requirements that a user or 183 device must satisfy in order to gain access to the wider network. 185 Captive Portal Enforcement: The network equipment which enforces the 186 traffic restriction. 188 Captive Portal User Equipment: Also known as User Equipment. A 189 device which has voluntarily joined a network for purposes of 190 communicating beyond the constraints of the captive network. 192 Captive Portal Server: The web server providing a user interface for 193 assisting the user in satisfying the conditions to escape captivity. 195 Captive Portal API: Also known as API. An HTTP API allowing User 196 Equipment to query its state of captivity within the Captive Portal. 198 Captive Portal API Server: Also known as API Server. A server 199 hosting the Captive Portal API. 201 Captive Portal Signal: A notification from the network used to inform 202 the User Equipment that the state of its captivity could have 203 changed. 205 Captive Portal Signaling Protocol: Also known as Signaling Protocol. 206 The protocol for communicating Captive Portal Signals. 208 2. Components 210 2.1. User Equipment 212 The User Equipment is the device that a user desires to be attached 213 to a network with full access to all hosts on the network (e.g., to 214 have Internet access). The User Equipment communication is typically 215 restricted by the Captive Portal Enforcement, described in 216 Section 2.4, until site-specific requirements have been met. 218 At this time we consider only devices with web browsers, with web 219 applications being the means of satisfying Captive Portal Conditions. 220 An example interactive User Equipment is a smart phone. 222 The User Equipment: 224 * SHOULD support provisioning of the URI for the Captive Portal API 225 (e.g., by DHCP) 227 * SHOULD distinguish Captive Portal API access per network 228 interface, in the manner of Provisioning Domain Architecture 229 [RFC7556]. 231 * SHOULD have a mechanism for notifying the user of the Captive 232 Portal 234 * SHOULD have a web browser so that the user may navigate the 235 Captive Portal user interface. 237 * MAY prevent applications from using networks that do not grant 238 full network access. E.g., a device connected to a mobile network 239 may be connecting to a captive WiFi network; the operating system 240 MAY avoid updating the default route until network access 241 restrictions have been lifted (excepting access to the Captive 242 Portal server) in the new network. This has been termed "make 243 before break". 245 None of the above requirements are mandatory because (a) we do not 246 wish to say users or devices must seek full access to the captive 247 network, (b) the requirements may be fulfilled by manually visiting 248 the captive portal web application, and (c) legacy devices must 249 continue to be supported. 251 If User Equipment supports the Captive Portal API, it MUST validate 252 API server TLS certificate (see [RFC2818]). An Enforcement device 253 SHOULD allow access to any services that User Equipment could need to 254 contact to perform certificate validation, such as OCSP responders, 255 CRLs, and NTP servers; see Section 4.1 of [I-D.ietf-capport-api] for 256 more information. If certificate validation fails, User Equipment 257 MUST NOT proceed with any of the behavior described above. 259 2.2. Provisioning Service 261 Here we discuss candidate mechanisms for provisioning the User 262 Equipment with the URI of the API to query captive portal state and 263 navigate the portal. 265 2.2.1. DHCP or Router Advertisements 267 A standard for providing a portal URI using DHCP or Router 268 Advertisements is described in [RFC7710bis]. The CAPPORT 269 architecture expects this URI to indicate the API described in 270 Section 2.3. 272 2.2.2. Provisioning Domains 274 Although still a work in progress, [I-D.pfister-capport-pvd] proposes 275 a mechanism for User Equipment to be provided with PvD Bootstrap 276 Information containing the URI for the JSON-based API described in 277 Section 2.3. 279 2.3. Captive Portal API Server 281 The purpose of a Captive Portal API is to permit a query of Captive 282 Portal state without interrupting the user. This API thereby removes 283 the need for User Equipment to perform clear-text "canary" HTTP 284 queries to check for response tampering. 286 The URI of this API will have been provisioned to the User Equipment. 287 (Refer to Section 2.2). 289 This architecture expects the User Equipment to query the API when 290 the User Equipment attaches to the network and multiple times 291 thereafter. Therefore the API MUST support multiple repeated queries 292 from the same User Equipment and return the state of captivity for 293 the equipment. 295 At minimum, the API MUST provide: (1) the state of captivity and (2) 296 a URI for the Captive Portal Server. The API SHOULD provide evidence 297 to the caller that it supports the present architecture. 299 When user equipment receives Captive Portal Signals, the user 300 equipment MAY query the API to check the state. The User Equipment 301 SHOULD rate-limit these API queries in the event of the signal being 302 flooded. (See Section 7.) 304 The API MUST be extensible to support future use-cases by allowing 305 extensible information elements. 307 The API MUST use TLS to ensure server authentication. The 308 implementation of the API MUST ensure both confidentiality and 309 integrity of any information provided by or required by it. 311 This document does not specify the details of the API. 313 2.4. Captive Portal Enforcement 315 The Captive Portal Enforcement component restrict the network access 316 of User Equipment according to site-specific policy. Typically User 317 Equipment is permitted access to a small number of services and is 318 denied general network access until it satisfies the Captive Portal 319 Conditions. 321 The Captive Portal Enforcement component: 323 * Allows traffic through for allowed User Equipment that has 324 satisfied the Captive Portal Conditions. 326 * Blocks (discards) traffic according to the site-specific policy 327 for User Equipment that has not yet satisfied the Captive Portal 328 Conditions. 330 * May signal User Equipment using the Captive Portal Signaling 331 protocol if certain traffic is blocked. 333 * Permits User Equipment that has not satisfied the Captive Portal 334 Conditions to access necessary APIs and web pages to fulfill 335 requirements for escaping captivity. 337 * Updates allow/block rules per User Equipment in response to 338 operations from the Captive Portal Server. 340 2.5. Captive Portal Signal 342 When User Equipment first connects to a network, or when there are 343 changes in status, the Enforcement Device could generate a signal 344 toward the User Equipment. This signal indicates that the User 345 Equipment might need to contact the API Server to receive updated 346 information. For instance, this signal might be generated when the 347 end of a session is imminent, or when network access was denied. 349 An Enforcement Device MUST rate-limit any signal generated in 350 response to these conditions. See Section 7.4 for a discussion of 351 risks related to a Captive Portal Signal. 353 2.6. Component Diagram 355 The following diagram shows the communication between each component. 357 o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . o 358 . CAPTIVE NETWORK . 359 . +--------------+ . 360 . +------------+ Provision API URI | Provisioning | . 361 . | |<---------------------------+| Service | . 362 . | User | +--------------+ . 363 . | Equipment | Query captivity status +-------------+ . 364 . | |+--------------------------->| API | . 365 . | | | Server | . 366 . | | +------+------+ . 367 . | | | Status . 368 . | | Portal user interface +------+------+ . 369 . | |+--------------------------->| Web Portal | . 370 . +------------+ | Server | . 371 . ^ ^ | +-------------+ . 372 . | | | Data | . 373 . | | +-----------------> +---------------+ Allow/Deny . 374 . | +--------------------+| | Rules . 375 . | | Captive Portal| | . 376 . | Captive Portal Signal | Enforcement | <---+ . 377 . +-------------------------+---------------+ . 378 . ^ | . 379 . | | . 380 . Data to/from external network . 381 . | | . 382 o . . . . . . . . . . . . . . . . . . .| |. . . . . . . . . . . o 383 | v 384 EXTERNAL NETWORK 386 Figure 1: Captive Portal Architecture Component Diagram 388 In the diagram: 390 * During provisioning (e.g., DHCP), the User Equipment acquires the 391 URI for the Captive Portal API. 393 * The User Equipment queries the API to learn of its state of 394 captivity. If captive, the User Equipment presents the portal 395 user interface from the Web Portal Server to the user. 397 * Based on user interaction, the Web Portal Server directs the 398 Captive Portal Enforcement device to either allow or deny external 399 network access for the User Equipment. 401 * The User Equipment attempts to communicate to the external network 402 through the Captive Portal enforcement device. 404 * The Captive Portal Enforcement device either allows the User 405 Equipment's packets to the external network, or blocks the 406 packets. If blocking traffic and a signal has been implemented, 407 it may respond with a Captive Portal Signal. 409 Although the Provisioning Service, API Server, and Web Portal Server 410 functions are shown as discrete blocks, they could of course be 411 combined into a single element. 413 3. User Equipment Identity 415 Multiple components in the architecture interact with both the User 416 Equipment and each other. Since the User Equipment is the focus of 417 these interactions, the components must be able to both identify the 418 user equipment from their interactions with it, and be able to agree 419 on the identity of the user equipment when interacting with each 420 other. 422 The methods by which the components interact restrict the type of 423 information that may be used as an identifying characteristics. This 424 section discusses the identifying characteristics. 426 3.1. Identifiers 428 An Identifier is a characteristic of the User Equipment used by the 429 components of a Captive Portal to uniquely determine which specific 430 User Equipment is interacting with them. An Identifier MAY be a 431 field contained in packets sent by the User Equipment to the External 432 Network. Or, an Identifier MAY be an ephemeral property not 433 contained in packets destined for the External Network, but instead 434 correlated with such information through knowledge available to the 435 different components. 437 3.2. Recommended Properties 439 The set of possible identifiers is quite large. However, in order to 440 be considered a good identifier, an identifier SHOULD meet the 441 following criteria. Note that the optimal identifier will likely 442 change depending on the position of the components in the network as 443 well as the information available to them. An identifier SHOULD: 445 * Uniquely Identify the User Equipment 447 * Be Hard to Spoof 449 * Be Visible to the API Server 451 * Be Visible to the Enforcement Device 452 An identifier might only apply to the current point of network 453 attachment. If the device moves to a different network location its 454 identity could change. 456 3.2.1. Uniquely Identify User Equipment 458 In order to uniquely identify the User Equipment, at most one user 459 equipment interacting with the other components of the Captive Portal 460 MUST have a given value of the identifier. 462 Over time, the user equipment identified by the value MAY change. 463 Allowing the identified device to change over time ensures that the 464 space of possible identifying values need not be overly large. 466 Independent Captive Portals MAY use the same identifying value to 467 identify different User Equipment. Allowing independent captive 468 portals to reuse identifying values allows the identifier to be a 469 property of the local network, expanding the space of possible 470 identifiers. 472 3.2.2. Hard to Spoof 474 A good identifier does not lend itself to being easily spoofed. At 475 no time should it be simple or straightforward for one User Equipment 476 to pretend to be another User Equipment, regardless of whether both 477 are active at the same time. This property is particularly important 478 when the user equipment is extended externally to devices such as 479 billing systems, or where the identity of the User Equipment could 480 imply liability. 482 3.2.3. Visible to the API Server 484 Since the API Server will need to perform operations which rely on 485 the identity of the user equipment, such as query whether it is 486 captive, the API Server needs to be able to relate requests to the 487 User Equipment making the request. 489 3.2.4. Visible to the Enforcement Device 491 The Enforcement Device will decide on a per packet basis whether it 492 should be permitted to communicate with the external network. Since 493 this decision depends on which User Equipment sent the packet, the 494 Enforcement Device requires that it be able to map the packet to its 495 concept of the User Equipment. 497 3.3. Evaluating an Identifier 499 To evaluate whether an identifier is appropriate, one should consider 500 every recommended property from the perspective of interactions among 501 the components in the architecture. When comparing identifiers, 502 choose the one which best satisfies all of the recommended 503 properties. The architecture does not provide an exact measure of 504 how well an identifier satisfies a given property; care should be 505 taken in performing the evaluation. 507 3.4. Examples of an Identifier 509 This section provides some examples of identifiers, along with some 510 evaluation of whether they are good identifiers. The list of 511 identifiers is not exhaustive. Other identifiers may be used. An 512 important point to note is that whether the identifiers are good 513 depends heavily on the capabilities of the components and where in 514 the network the components exist. 516 3.4.1. Physical Interface 518 The physical interface by which the User Equipment is attached to the 519 network can be used to identify the User Equipment. This identifier 520 has the property of being extremely difficult to spoof: the User 521 Equipment is unaware of the property; one User Equipment cannot 522 manipulate its interactions to appear as though it is another. 524 Further, if only a single User Equipment is attached to a given 525 physical interface, then the identifier will be unique. If multiple 526 User Equipment is attached to the network on the same physical 527 interface, then this property is not appropriate. 529 Another consideration related to uniqueness of the User Equipment is 530 that if the attached User Equipment changes, both the API Server and 531 the Enforcement Device MUST invalidate their state related to the 532 User Equipment. 534 The Enforcement Device needs to be aware of the physical interface, 535 which constrains the environment: it must either be part of the 536 device providing physical access (e.g., implemented in firmware), or 537 packets traversing the network must be extended to include 538 information about the source physical interface (e.g. a tunnel). 540 The API Server faces a similar problem, implying that it should co- 541 exist with the Enforcement Device, or that the enforcement device 542 should extend requests to it with the identifying information. 544 3.4.2. IP Address 546 A natural identifier to consider is the IP address of the User 547 Equipment. At any given time, no device on the network can have the 548 same IP address without causing the network to malfunction, so it is 549 appropriate from the perspective of uniqueness. 551 However, it may be possible to spoof the IP address, particularly for 552 malicious reasons where proper functioning of the network is not 553 necessary for the malicious actor. Consequently, any solution using 554 the IP address SHOULD proactively try to prevent spoofing of the IP 555 address. Similarly, if the mapping of IP address to User Equipment 556 is changed, the components of the architecture MUST remove or update 557 their mapping to prevent spoofing. Demonstrations of return 558 routeability, such as that required for TCP connection establishment, 559 might be sufficient defense against spoofing, though this might not 560 be sufficient in networks that use broadcast media (such as some 561 wireless networks). 563 Since the IP address may traverse multiple segments of the network, 564 more flexibility is afforded to the Enforcement Device and the API 565 Server: they simply must exist on a segment of the network where the 566 IP address is still unique. However, consider that a NAT may be 567 deployed between the User Equipment and the Enforcement Device. In 568 such cases, it is possible for the components to still uniquely 569 identify the device if they are aware of the port mapping. 571 In some situations, the User Equipment may have multiple IP 572 addresses, while still satisfying all of the recommended properties. 573 This raises some challenges to the components of the network. For 574 example, if the user equipment tries to access the network with 575 multiple IP addresses, should the enforcement device and API Server 576 treat each IP address as a unique User Equipment, or should it tie 577 the multiple addresses together into one view of the subscriber? An 578 implementation MAY do either. Attention should be paid to IPv6 and 579 the fact that it is expected for a device to have multiple IPv6 580 addresses on a single link. In such cases, identification could be 581 performed by subnet, such as the /64 to which the IP belongs. 583 3.4.3. Context-free URL 585 The URLs provided in the API SHOULD contain all the information 586 necessary to render the resources requested: the resources should not 587 depend on ambient information, such as remote address on the 588 connection. This is to ensure that the content served from these 589 URLs is correct and meaningful to the User Equipment, even when 590 accessed from a network other than the one that contains the captive 591 portal. One consequence of this is that URLs provided in the API are 592 expected to be resolved using public global DNS (as defined in 593 Section 2 of [RFC8499]). 595 Though a URL might still correctly resolve when the UE makes the 596 request from a different network, it is possible that some functions 597 could be limited to when the UE makes requests using the captive 598 network. For example, payment options could be absent or a warning 599 could be displayed to indicate the payment is not for the current 600 connection. 602 URLs could include some means of identifying the User Equipment in 603 the URLs. However, including unauthenticated User Equipment 604 identifiers in the URL may expose the service to spoofing or replay 605 attacks. 607 4. Solution Workflow 609 This section aims to improve understanding by describing a possible 610 workflow of solutions adhering to the architecture. 612 4.1. Initial Connection 614 This section describes a possible work-flow when User Equipment 615 initially joins a Captive Network. 617 1. The User Equipment joins the Captive Network by acquiring a DHCP 618 lease, RA, or similar, acquiring provisioning information. 620 2. The User Equipment learns the URI for the Captive Portal API from 621 the provisioning information (e.g., [RFC7710bis]). 623 3. The User Equipment accesses the Captive Portal API to receive 624 parameters of the Captive Network, including web-portal URI. 625 (This step replaces the clear-text query to a canary URL.) 627 4. If necessary, the User navigates the web portal to gain access to 628 the external network. 630 5. The Captive Portal API server indicates to the Captive Portal 631 Enforcement device that the User Equipment is allowed to access 632 the external network. 634 6. The User Equipment attempts a connection outside the captive 635 network 637 7. If the requirements have been satisfied, the access is permitted; 638 otherwise the "Expired" behavior occurs. 640 8. The User Equipment accesses the network until conditions Expire. 642 4.2. Conditions About to Expire 644 This section describes a possible work-flow when access is about to 645 expire. 647 1. Precondition: the API has provided the User Equipment with a 648 duration over which its access is valid 650 2. The User Equipment is communicating with the outside network 652 3. The User Equipment's UI indicates that the length of time left 653 for its access has fallen below a threshold 655 4. The User Equipment visits the API again to validate the expiry 656 time 658 5. If expiry is still imminent, the User Equipment prompts the user 659 to access the web-portal URI again 661 6. The User extends their access through the web-portal 663 7. The User Equipment's access to the outside network continues 664 uninterrupted 666 4.3. Handling of Changes in Portal URI 668 A different Captive Portal API URI could be returned in the following 669 cases: 671 * If DHCP is used, a lease renewal/rebind may return a different 672 Captive Portal API URI. 674 * If RA is used, a new Captive Portal API URI may be specified in a 675 new RA message received by end user equipment. 677 Whenever a new Portal URI is received by end user equipment, it 678 SHOULD discard the old URI and use the new one for future requests to 679 the API. 681 5. Acknowledgments 683 The authors thank Lorenzo Colitti for providing the majority of the 684 content for the Captive Portal Signal requirements. 686 The authors thank various individuals for their feedback on the 687 mailing list and during the IETF98 hackathon: David Bird, Erik Kline, 688 Alexis La Goulette, Alex Roscoe, Darshak Thakore, and Vincent van 689 Dam. 691 6. IANA Considerations 693 This memo includes no request to IANA. 695 7. Security Considerations 697 7.1. Trusting the Network 699 When joining a network, some trust is placed in the network operator. 700 This is usually considered to be a decision by a user on the basis of 701 the reputation of an organization. However, once a user makes such a 702 decision, protocols can support authenticating that a network is 703 operated by who claims to be operating it. The Provisioning Domain 704 Architecture [RFC7556] provides some discussion on authenticating an 705 operator. 707 Given that a user chooses to visit a Captive Portal URI, the URI 708 location SHOULD be securely provided to the user's device. E.g., the 709 DHCPv6 AUTH option can sign this information. 711 If a user decides to incorrectly trust an attacking network, they 712 might be convinced to visit an attacking web page and unwittingly 713 provide credentials to an attacker. Browsers can authenticate 714 servers but cannot detect cleverly misspelled domains, for example. 716 7.2. Authenticated APIs 718 The solution described here assumes that when the User Equipment 719 needs to trust the API server, server authentication will be 720 performed using TLS mechanisms. 722 7.3. Secure APIs 724 The solution described here requires that the API be secured using 725 TLS. This is required to allow the user equipment and API Server to 726 exchange secrets which can be used to validate future interactions. 727 The API MUST ensure the integrity of this information, as well as its 728 confidentiality. 730 7.4. Risks Associated with the Signaling Protocol 732 If a Signaling Protocol is implemented, it may be possible for any 733 user on the Internet to send signals in attempt to cause the 734 receiving equipment to communicate with the Captive Portal API. This 735 has been considered, and implementations may address it in the 736 following ways: 738 * The signal only informs the User Equipment to query the API. It 739 does not carry any information which may mislead or misdirect the 740 User Equipment. 742 * Even when responding to the signal, the User Equipment securely 743 authenticates with API Servers. 745 * Accesses to the API Server are rate limited, limiting the impact 746 of a repeated attack. 748 7.5. User Options 750 The Captive Portal Signal could inform the User Equipment that it is 751 being held captive. There is no requirement that the User Equipment 752 do something about this. Devices MAY permit users to disable 753 automatic reaction to Captive Portal Signals indications for privacy 754 reasons. However, there would be the trade-off that the user doesn't 755 get notified when network access is restricted. Hence, end-user 756 devices MAY allow users to manually control captive portal 757 interactions, possibly on the granularity of Provisioning Domains. 759 8. References 761 8.1. Normative References 763 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 764 Requirement Levels", BCP 14, RFC 2119, 765 DOI 10.17487/RFC2119, March 1997, 766 . 768 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 769 DOI 10.17487/RFC2818, May 2000, 770 . 772 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 773 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 774 . 776 [RFC7710bis] 777 Kumari, W. and E. Kline, "Captive-Portal Identification in 778 DHCP / RA", Work in Progress, Internet-Draft, draft-ietf- 779 capport-rfc7710bis-01, 12 January 2020, 780 . 783 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 784 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 785 May 2017, . 787 8.2. Informative References 789 [I-D.ietf-capport-api] 790 Pauly, T. and D. Thakore, "Captive Portal API", Work in 791 Progress, Internet-Draft, draft-ietf-capport-api-06, 31 792 March 2020, 793 . 795 [I-D.pfister-capport-pvd] 796 Pfister, P. and T. Pauly, "Using Provisioning Domains for 797 Captive Portal Discovery", Work in Progress, Internet- 798 Draft, draft-pfister-capport-pvd-00, 30 June 2018, 799 . 802 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 803 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 804 January 2019, . 806 Appendix A. Existing Captive Portal Detection Implementations 808 Operating systems and user applications may perform various tests 809 when network connectivity is established to determine if the device 810 is attached to a network with a captive portal present. A common 811 method is to attempt to make a HTTP request to a known, vendor hosted 812 endpoint with a fixed response. Any other response is interpreted as 813 a signal that a captive portal is present. This check is typically 814 not secured with TLS, as a network with a captive portal may 815 intercept the connection, leading to a host name mismatch. This has 816 been referred to as a "canary" request because, like the canary in 817 the coal mine, it can be the first sign that something is wrong. 819 Another test that can be performed is a DNS lookup to a known address 820 with an expected answer. Such tests may be less reliable as the 821 captive 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. 826 Malicious or misconfigured networks with a captive portal present may 827 not intercept these requests and choose to pass them through or 828 decide to impersonate, leading to the device having a false negative. 830 Authors' Addresses 832 Kyle Larose 833 Agilicus 835 Email: kyle@agilicus.com 837 David Dolson 839 Email: ddolson@acm.org 841 Heng Liu 842 Google 844 Email: liucougar@google.com