idnits 2.17.1 draft-larose-capport-architecture-00.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 : ---------------------------------------------------------------------------- ** There are 20 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 9, 2017) is 2598 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 (-02) exists of draft-wkumari-capport-icmp-unreach-01 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force K. Larose 3 Internet-Draft D. Dolson 4 Intended status: Informational Sandvine 5 Expires: September 10, 2017 March 9, 2017 7 CAPPORT Architecture 8 draft-larose-capport-architecture-00 10 Abstract 12 This document aims to document concensus on the CAPPORT architecture. 13 DHCP, ICMP, and an HTTP API are used to provide the solution. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on September 10, 2017. 32 Copyright Notice 34 Copyright (c) 2017 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 51 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Components . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2.1. User Equipment . . . . . . . . . . . . . . . . . . . . . 3 54 2.2. DHCP Server . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.3. Captive Portal API Server . . . . . . . . . . . . . . . . 4 56 2.4. Captive Portal Enforcement . . . . . . . . . . . . . . . 5 57 2.5. ICMP/ICMP6 . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.6. Component Diagram . . . . . . . . . . . . . . . . . . . . 6 59 3. Solution Workflow . . . . . . . . . . . . . . . . . . . . . . 7 60 3.1. Initial Connection . . . . . . . . . . . . . . . . . . . 7 61 3.2. Connection About to Expire . . . . . . . . . . . . . . . 8 62 3.3. Connection expired . . . . . . . . . . . . . . . . . . . 8 63 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 5.1. Authenticated APIs . . . . . . . . . . . . . . . . . . . 9 66 5.2. Risk of Nuisance Captive Portal . . . . . . . . . . . . . 9 67 5.3. User Options . . . . . . . . . . . . . . . . . . . . . . 9 68 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 69 6.1. Normative References . . . . . . . . . . . . . . . . . . 9 70 6.2. Informative References . . . . . . . . . . . . . . . . . 10 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 73 1. Introduction 75 Problems with captive portals have been described in 76 [I-D.nottingham-capport-problem]. 78 This document standardizes an architecture for implementing captive 79 portals that provides tools for addressing most of those problems. 81 The architecture also attempts to enable IoT devices, in particular 82 devices without user interfaces, to navigate a captive portal. 84 The architecture uses the following mechanisms: 86 o DHCP/DHCP6 providing end-user devices with a URI in the Captive- 87 Portal Router Advertisement option [RFC7710]. This URI is an API 88 that the end-user devices access for information about what is 89 required to escape captivity. 91 o Notifying end-user devices of captivity with ICMP/ICMP6 92 "unreachable" messages. This notification can work with any 93 Internet protocol, not just clear-text HTTP. This notification 94 does not carry the portal URI, rather triggers the DHCP- 95 provisioned portal to be accessed. This notification carries a 96 "reason" that allows the devices to receive customized work-flows 97 at the portal. 99 o Receipt of the ICMP/ICMP6 messages inform an end-user device that 100 it is captive. This permits the device to take immediate action 101 to satisfy the portal (according to its configuration/policy). 102 The architecture recommends the device to query the DHCP- 103 provisioned CAPPORT URI with the specified "reason". This API 104 returns a status and a menu for navigating the captive portal. 105 Typically one of the menu items is a web page suitable for 106 browsing. 108 The architecture attempts to provide privacy, authentication, and 109 safety mechanisms to the extent possible. 111 1.1. Requirements Language 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in RFC 2119 [RFC2119]. 117 1.2. Terminology 119 Captive Network: A network for which communication outside of it is 120 subject to a captive portal 122 Captive Portal Enforcement: The device which enforces the captive 123 portal in the captive netowrk 125 Captive Portal User Equipment: Also known as User Equipment. A 126 device which wants to communicate outside the captive network 128 2. Components 130 2.1. User Equipment 132 The User Equipment is the device that a user desires to communicate 133 with a network. The User Equipment communication is typically 134 restricted by the Captive Portal Enforcement, described in 135 Section 2.4, until site-specific requirements have been met. 137 o May be interactive or non-iteractive 139 o May have different mechanisms for notifying the user of the 140 captive portal 142 o Needs to recognize the ICMP unreachable message, and to invoke its 143 captive portal handling in response to it. 145 o Needs to cache the URI for the captive portal API from the DHCP 146 lease. 148 o May cache credentials to automatically respond to captive portal 149 notifications 151 o Interactive User Equipment typically ask their users how to 152 proceed through interacting with the captive portal. Interactions 153 may be as simple as accepting a terms of agreement, or as 154 complicated as filling out some forms. 156 o An example interactive User Equipment is a smart phone. 158 o Non interactive User Equipment may be provisioned with credentials 159 out of band (e.g., via USB programming) in order to automatically 160 gain access. 162 o An example non interactive User Equipment is an IoT device such as 163 a smart thermostat. 165 o May need to distinguish between types of User Equipment here. 167 2.2. DHCP Server 169 A standard for providing a portal URI is described in [RFC7710]. The 170 CAPPORT architecture expects this URI to access the API described in 171 Section 2.3. 173 Although it is not clear from RFC7710 what protocol should be 174 executed at the specified URI, it may have been assumed to be an HTML 175 page, and hence there may be User Equipment assuming a browser should 176 open this URI. For backwards compatibility, it might be necessary 177 for the server to check Agent-Id when serving the URI. 179 2.3. Captive Portal API Server 181 The User Equipment performs GET at the DHCP-specified URI. The API 182 is implemented at the CAPPORT API Server. The response is a JSON 183 document. The following information should be available in the 184 response document, allowing User Equipment devices to choose the next 185 step: 187 o Quota information (remaining time/bytes/etc.) 189 o Whether the device is allowed through captive portal or blocked. 191 o Method of providing credentials to gain access. 193 o Describe the required credentials to gain access. 195 o URL of a web page for devices with browsers and humans. 197 o A token used to verify later ICMP messages are valid. 199 The CAPPORT API is intended to provide information and a menu of 200 choices to support options for interactive or non-interactive User 201 Equipment. 203 The CAPPORT API should support TLS for privacy. [Does this API need 204 to be secure, or do we place security at the interfaces it points 205 to?] 207 2.4. Captive Portal Enforcement 209 The Captive Portal Enforcement component restricts network access to 210 User Equipment according to site-specific policy. Typically User 211 Equipment is denied network access until it has performed some 212 action. 214 The Captive Portal Enforcement component: 216 o Allows traffic through for allowed User Equipment. 218 o Blocks traffic and sends ICMP notifications for disallowed User 219 Equipment. 221 o Permits disallowed User Equipment to access necessary APIs and web 222 pages to fulfill requirements of exiting captivity. 224 o May modify responses to canary URLs, or perform other methods of 225 notification. 227 o Updates policy per User Equipment in response to operations from 228 the Captive Portal API. 230 2.5. ICMP/ICMP6 232 A mechanism to trigger captive portal work-flows in the User 233 Equipment is proposed earlier in [I-D.wkumari-capport-icmp-unreach]. 234 Additionally, the Unreachable message carries a token to prove it is 235 a valid notification. 237 The Captive Portal Enforcement function is required to send such ICMP 238 messages when disallowed User Equipment attempts to send to the 239 network. 241 The ICMP messages MUST NOT be sent to the Internet devices. The 242 indications are only sent to the User Equipment. 244 The User Equipment MUST verify that the token matches the token 245 received earlier via the CAPPORT API. If tokens do not match, the 246 ICMP message MUST be discarded with no further impact. (It MAY be 247 counted.) 249 The User Equipment does not necessarily deliver the impact of the 250 ICMP message to the application that triggered it. The User 251 Equipment may be able to satisfy the Captive Portal requirements 252 quickly enough that existing transport connections are not impacted. 254 2.6. Component Diagram 256 The following diagram shows the communication between each component. 258 o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . o 259 . CAPTIVE NETWORK . 260 . +---------------+ . 261 . +-------------+ CAPPORT API URI | DHCP Server | . 262 . | | <-------------------------+ +---------------+ . 263 . | User | . 264 . | Equipment | Request Access/Information +--------------------+ . 265 . | | +--------------------------> | CAPPORT API Server | . 266 . +-------------+ +--------------------+ . 267 . ^ | Connection Attempt | . 268 . | +-------------------> +---------------+ Allow/Deny Access . 269 . | | | | . 270 . | ICMP Unreachable | Captive Portal| | . 271 . +----------------------+ | Enforcement | <---+ . 272 . +---------------+ . 273 . | . 274 . To/from external network . 275 . | . 276 . | . 277 o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . o 278 EXTERNAL NETWORK 280 Figure 1: Captive Portal Architecture Component Diagram 282 In the diagram: 284 o The User Equipment communicates with the DHCP Server to get access 285 to the captive network, and learn about the CAPPORT API URI. 287 o The User Equipment attempts to communicate through the captive 288 portal enforcement device. 290 o The Captive Portal Enforcement device either lets the User 291 Equipment's traffic through, or responds with an ICMP Unreachable 293 o The User Equipment requests access to outside the captive network, 294 or requests more information, from the CAPPORT API server 296 o The CAPPORT API server directs the Captive Portal Enforcement 297 device to either allow or deny access in response to requests from 298 the User Equipment or quota/timing restrictions. 300 3. Solution Workflow 302 This section describes the general workflow of solutions adhering to 303 the architecture. 305 3.1. Initial Connection 307 1. The User Equipment joins the captive network by acquiring a DHCP 308 lease 310 2. The User Equipment learns the URI for the Captive Portal API from 311 the DHCP response ([RFC7710]). 313 3. The User Equipment accesses the CAPPORT API to receive parameters 314 of the Captive Network, including the token. 316 4. The User Equipment communicates with the CAPPORT API to gain 317 access to the outside network. 319 5. The Captive Portal API server indicates to the Captive Portal 320 Enforcement device that the User Equipment is allowed through 322 6. The User Equipment attempts a connection outside the captive 323 network 325 7. If the requirements have been satisfied, the access is permitted; 326 otherwise the "Expired" behavior occurs 328 8. The User Equipment accesses the network until conditions Expire 330 3.2. Connection About to Expire 332 1. The User Equipment sends a packet to the outside network. 334 2. The Captive Portal Enforcement detects that the User Equipment's 335 access is about to expire (low quota/time/etc) 337 3. The Captive Portal Enforcement sends an ICMP unreachable to the 338 User Equipment indicating that it needs to refresh its access. 339 [I-D.wkumari-capport-icmp-unreach]. The message contains the 340 token given to the User Equipment earlier. 342 4. The User Equipment verifies the message, including the token 344 5. The User Equipment handles this message by invoking its captive 345 portal handling infrsatructure. 347 6. The captive portal handling infrastructure communicates with the 348 Captive Portal API to gain access to outside the captive network 350 7. The Captive Portal API Server gives more quota (time, bytes, 351 etc.) to the User Equipment by indicating to the Captive Portal 352 Enforcement the new, extended quota. 354 8. The User Equipment continues unaffected. 356 3.3. Connection expired 358 1. The User Equipment sends a packet to the outside network. 360 2. The Captive Portal Enforcement device detects that the User 361 Equipment's access has expired. 363 3. The remaining workflow is that same as for the initial 364 connection. 366 User Equipment may attempt to maintain transport connections, leaving 367 it to the application to determine timeouts. 369 User Equipment may preemptively invoke its captive portal handling 370 infrastructure when receiving the DHCP response indicating that it is 371 behind a captive portal, rather than waiting for the ICMP unreachable 372 message. 374 4. IANA Considerations 376 This memo includes no request to IANA. 378 5. Security Considerations 380 5.1. Authenticated APIs 382 The solution described here assumes that when the User Equipment 383 needs to trust the API server, server authentication will be 384 utilized. 386 TODO: this document has not specified the authentication mechanism. 388 5.2. Risk of Nuisance Captive Portal 390 It is possible for any user on the Internet to send ICMP packets in 391 an attempt to cause the receiving equipment to go to the captive 392 portal. This has been considered and addressed in the following 393 ways: 395 The ICMP packet does not carry the URL, making this method safer 396 than 307-redirect methods currently in use. 398 The ICMP packet carries a token that would not be available, even 399 to an on-path attacker. Although possible to guess by brute 400 force, the impact is nuisance due to other precautions. We 401 suggest a 32-bit token would be sufficient to deter nuisance 402 attacks. 404 Even when redirected, the User Equipment securely authenticates 405 with API servers. 407 5.3. User Options 409 The ICMP messaging informs the end-user device it is being held 410 captive. There is no requirement that the device do something about 411 this. Devices may permit users to disable automatic reaction to 412 captive-portal indications. Hence, end-user devices may allow users 413 to manually control captive portal interactions. 415 6. References 417 6.1. Normative References 419 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 420 Requirement Levels", BCP 14, RFC 2119, 421 DOI 10.17487/RFC2119, March 1997, 422 . 424 [RFC7710] Kumari, W., Gudmundsson, O., Ebersman, P., and S. Sheng, 425 "Captive-Portal Identification Using DHCP or Router 426 Advertisements (RAs)", RFC 7710, DOI 10.17487/RFC7710, 427 December 2015, . 429 6.2. Informative References 431 [I-D.nottingham-capport-problem] 432 Nottingham, M., "Captive Portals Problem Statement", 433 draft-nottingham-capport-problem-01 (work in progress), 434 April 2016. 436 [I-D.wkumari-capport-icmp-unreach] 437 Bird, D. and W. Kumari, "Captive Portal ICMP Destination 438 Unreachable", draft-wkumari-capport-icmp-unreach-01 (work 439 in progress), April 2015. 441 Authors' Addresses 443 Kyle Larose 444 Sandvine 445 408 Albert Street 446 Waterloo, ON N2L 3V3 447 Canada 449 Phone: +1 519 880 2400 450 Email: klarose@sandvine.com 452 David Dolson 453 Sandvine 454 408 Albert Street 455 Waterloo, ON N2L 3V3 456 Canada 458 Phone: +1 519 880 2400 459 Email: ddolson@sandvine.com