idnits 2.17.1 draft-wkumari-capport-icmp-unreach-02.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 71 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: The Validity time, in seconds, that this result should be considered valid and the OS SHOULD not attempt to access the same resource in the meantime. During the Validity time, the NAS MAY chose to silently drop the packets of the same flow 5-tuple to selectively cause legacy clients to time-out connections. -- The document date (April 2, 2017) is 2579 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC0792' is defined on line 414, but no explicit reference was found in the text == Unused Reference: 'RFC1122' is defined on line 418, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 428, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-sidr-iana-objects' is defined on line 445, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7710 (Obsoleted by RFC 8910) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 template D. Bird 3 Internet-Draft W. Kumari 4 Intended status: Informational Google 5 Expires: October 4, 2017 April 2, 2017 7 Captive Portal ICMP Messages 8 draft-wkumari-capport-icmp-unreach-02 10 Abstract 12 This document defines a new ICMP Type for Captive Portal Messages. 13 The ICMP Type will only be known to clients supporting this 14 specification and provides both generic and flow 5-tuple specific 15 notifications from the Captive Portal NAS. 17 Further, This document defines a multi-part ICMP extension to ICMP 18 Destination Unreachable messages to signal, not only that the packet 19 was dropped, but that it was dropped due to an Access Policy 20 requiring Captive Portal interaction. Legacy clients will only be 21 processing the ICMP Destination Unreachable. 23 [ Editor note: The IETF is currently discussing improvements in 24 captive portal interactions and user experience improvements. See: 25 https://www.ietf.org/mailman/listinfo/captive-portals ] 27 [RFC Editor: Please remove this before publication. This document is 28 being stored in github at https://github.com/wlanmac/draft-wkumari- 29 capport-icmp-unreach . Authors gratefully accept pull requests, and 30 keep the latest (edit buffer) versions there, so commenters can 31 follow along at home.] 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on October 4, 2017. 50 Copyright Notice 52 Copyright (c) 2017 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 3 69 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 70 2. Captive Portal ICMP . . . . . . . . . . . . . . . . . . . . . 4 71 2.1. Session-ID . . . . . . . . . . . . . . . . . . . . . . . 4 72 2.2. Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 4 73 2.3. Validity . . . . . . . . . . . . . . . . . . . . . . . . 5 74 2.4. Delay . . . . . . . . . . . . . . . . . . . . . . . . . . 5 75 2.5. Policy Class . . . . . . . . . . . . . . . . . . . . . . 5 76 2.6. Message Code/C-Type . . . . . . . . . . . . . . . . . . . 6 77 2.7. Message Type . . . . . . . . . . . . . . . . . . . . . . 6 78 2.8. Extension Object . . . . . . . . . . . . . . . . . . . . 7 79 3. Captive Portal URL Formatting . . . . . . . . . . . . . . . . 8 80 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 81 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 82 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 83 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 84 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 85 7.2. Informative References . . . . . . . . . . . . . . . . . 10 86 Appendix A. Changes / Author Notes. . . . . . . . . . . . . . . 10 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 89 1. Introduction 91 Captive Portals work by blocking (or redirecting) communications 92 outside of a "walled garden" until the user has either authenticated, 93 acknowledged an Acceptable Use Policy (AUP), or otherwise satisfied 94 the requirements of the Captive Portal. Depending on the captive 95 portal implementation, connections other than HTTP will either 96 timeout (silently packets dropped) or meet with a different, 97 inaccurate, error condition (like a TCP reset, for TCP connections, 98 or ICMP Destination Unreachable with existing codes). 100 A current option for captive portal networks is to reject traffic not 101 in the walled garden by returning the Destination Unreachable either 102 Host or Network Administratively Prohibited. However, these codes 103 are typically permanent policies and do not specifically indicate a 104 captive portal is in use. 106 This document defines a new ICMP Type for Captive Portal. The 107 Captive Portal ICMP Type can be used to send flow 5-tuple specific or 108 general notifications to user devices. As a new ICMP type, it is 109 expected to be ignored by legacy devices. 111 This document also defines an Extension Object that can be appended 112 to selected multi-part ICMP messages to inform the user device that 113 they are behind a captive portal, in addition to the underlying ICMP 114 information. Devices able to understand the extension get extra 115 information about the captive portal access policy, whereas legacy 116 devices just understand the underlying ICMP message. 118 The Captive Portal and Destination Unreachable types provide the 119 Captive Portal NAS options in terms of what notifications legacy 120 devices can and should understand. 122 The Captive Portal ICMP Messages only provide notification. They do 123 not provide any configuration. For that, we use [RFC7710] and the 124 Captive Portal URI it provides. 126 1.1. Requirements notation 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 130 document are to be interpreted as described in [RFC2119]. 132 1.2. Terminology 134 Capport ICMP device Device or operating system compliant to this 135 specification. 137 CP-NAS Network Access Server implementing Captive Portal 138 enforcement. 140 Legacy device Device or operating system not compliant to this 141 specification. 143 2. Captive Portal ICMP 145 Captive Portal ICMP messages come in two flavors. Messages can be 146 sent using the Captive Portal ICMP Type or they can be sent as an 147 ICMP Extension to an existing ICMP Type, such as Destination 148 Unreachable. Data is encoded into the packet slightly differently in 149 each case, however, the field formats remain consistent. All fields 150 are in network byte order. 152 Capport ICMP devices MUST support [RFC7710]. 154 2.1. Session-ID 156 An unsigned short session identifier that groups ICMP messages. ICMP 157 messages containing the same value MUST be assumed to be part of the 158 same access policy. Any change in this value between ICMP messages 159 from the same source IP address MUST be considered by the client to 160 mean a change in access policy has occurred and previous 161 notifications are no longer valid. 163 0 1 164 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 165 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 166 | Session-ID | 167 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 169 2.2. Flags 171 In Captive Portal ICMP Messages, a flags field contains bit flags for 172 optional payload data fields. All data fields are unsigned 32bit 173 integers. 175 Bit flags and their (optional) respective data fields: 177 0 1 2 3 4 5 6 7 178 +-+-+-+-+-+-+-+-+ 179 |V|D|P| zero | 180 +-+-+-+-+-+-+-+-+ 182 V - 1 bit Validity 184 D - 1 bit Delay 186 P - 1 bit Policy Class 188 Optional fields included in flags appear in the ICMP payload in the 189 same order as the respective bits. 191 0 1 2 3 192 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 193 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 194 | Validity (optional) | 195 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 196 | Delay (optional) | 197 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 198 | Policy-Class (optional) | 199 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 201 2.3. Validity 203 The Validity time, in seconds, that this result should be considered 204 valid and the OS SHOULD not attempt to access the same resource in 205 the meantime. During the Validity time, the NAS MAY chose to 206 silently drop the packets of the same flow 5-tuple to selectively 207 cause legacy clients to time-out connections. 209 0 1 2 3 210 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 211 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 212 | Validity (seconds as uint32) | 213 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 215 2.4. Delay 217 The Delay time, in seconds, is the time in future when this result 218 should be considered valid. This is used to give advanced notice 219 that a change in access policy is about to happen. 221 0 1 2 3 222 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 223 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 224 | Delay (seconds as uint32) | 225 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 227 2.5. Policy Class 229 The Policy Class is an unsigned integer that provides a "hint" to the 230 captive portal. When a client is specifically responding to a 231 Captive Portal ICMP message and is launching a browser, the Policy 232 Class is given to the portal as a reason for the visitor to visit the 233 portal. 235 0 1 2 3 236 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 237 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 238 | Policy Class (uint32) | 239 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 241 2.6. Message Code/C-Type 243 Captive Portal Message Code and C-Types: 245 0 General Change of Authorization (change in policy) 247 1 Packet/flow Error (dropped) 249 2 Packet/flow Overflow (dropped) 251 3 Packet/flow Warning (not dropped) 253 2.7. Message Type 255 The Captive Portal ICMP Type message is specifically for Capport ICMP 256 Compliant devices. It is expected that Legacy devices will ignore 257 such messages. 259 0 1 2 3 260 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 261 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 262 | Type | Code | Checksum | 263 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 264 |V|D|P| zero | Length | Session-ID | 265 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 266 | Internet Header + leading octets of original datagram | 267 | | 268 | // | 269 | | 270 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 271 | Validity (optional) | 272 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 273 | Delay (optional) | 274 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 275 | Policy-Class (optional) | 276 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 278 As shown in the figure above, the Captive Portal Flags and Session-ID 279 and part of the ICMP header. The optional fields are in the ICMP 280 payload, past the (optional) original datagram headers of a length 281 defined by Length. 283 Length Number of 4 byte words of original datagram. 285 2.8. Extension Object 287 This document defines an extension object that can be appended to 288 selected multi-part ICMP messages ([RFC4884]). This extension 289 permits the CP-NAS to inform Capport ICMP Compliant devices that 290 their connection has been blocked due to an Access Policy requiring 291 interaction with the Captive Portal. 293 The Captive Portal Extension Object can be appended to the ICMP 294 Destination Unreachable messages. When Legacy devices receive such 295 messages, they will only understand the Destination Unreachable, 296 ignoring the extensions. 298 When used in an Extension Object, the Captive Portal ICMP data fields 299 are packed into an extension structure as shown below. 301 0 1 2 3 302 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 303 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 304 |V|D|P| Reserved | Session-ID | 305 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 306 | Validity (optional) | 307 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 308 | Delay (optional) | 309 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 310 | Policy-Class (optional) | 311 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 313 The following figure depicts the Destination Unreachable message with 314 Captive Portal Extension. It must be preceded by an ICMP Extension 315 Structure Header and an ICMP Object Header. Both are defined in 316 [RFC4884]. 318 0 1 2 3 319 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 320 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 321 | Type | Code | Checksum | 322 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 323 | unused | Length-A | Next-Hop MTU* | 324 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 325 | Internet Header + leading octets of original datagram | 326 | | 327 | // | 328 | | 329 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 330 |Version| (Reserved) | Checksum | 331 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 332 | Length-B | Class-Num | C-Type | 333 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 334 |V|D|P| Reserved | Session-ID | 335 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 336 | Validity (optional) | 337 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 338 | Delay (optional) | 339 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 340 | Policy-Class (optional) | 341 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 343 Type Set to 3 for Destination Unreachable. 345 Code Can be any value Code value for Type. 347 Length-A Length, in 4 byte words, of original datagram. 349 Version Set to version 2, per RFC 4884. 351 Length-B Length of extension. 353 Class-Num Set to Captive Portal Class-Num. 355 C-Type See section 2.6. 357 3. Captive Portal URL Formatting 359 The Session-ID and Policy Class is used along with the RFC 7710 URI 360 received from DHCP or IPv6 RA to send the user to the captive portal. 362 RFC_7710_URI . SEP . 363 'icmp_session=' . SESSION_ID . '&' . 364 'policy_class=' . [POLICY_CLASS[,POLICY_CLASS]] 366 RFC_7710_URI The URI received from DHCP or IPv6 RA per RFC 7710. 368 SEP If the RFC_7710_URI contains a '?', then SEP equals ampersand, 369 otherwise a question mark. 371 SESSION_ID The Session-ID value in integer format. 373 POLICY_CLASS Zero or more Policy Class values gathers for the same 374 Session-ID leading to the user notification.. 376 Examples: 378 https://wifi.domain.com/portal?icmp_session=10&policy_class=100 379 https://my.domain.com/?do=login&icmp_session=10&policy_class=100,20 381 4. IANA Considerations 383 The IANA is requested to assign a Captive Portal ICMP Message Type, 384 as well as Code values defined in section 2.6.. 386 The IANA is also requested to assign a Class-Num identifier for the 387 Captive Portal Extension Object from the ICMP Extension Object 388 Classes and Class Sub-types registry. 390 The IANA is also requested to form and administer the corresponding 391 class sub-type (C-Type) space per section 2.6. 393 5. Security Considerations 395 This method simply annotates existing ICMP Destination Unreachable 396 messages to inform users why their connection was blocked. This 397 technique can be used to inform captive portal detection probe 398 software that there is a captive portal present (and potentially to 399 connect to the URL handed out using draft-wkumari-dhc-capport. We 400 anticipate that there will be a new solution devised (such as a well 401 known URL / URI on captive portals) to allow the user / captive 402 portal probe to do something more useful with this information. 404 6. Acknowledgements 406 The authors wish to thank the authors of RFC4950 (especially Ron 407 Bonica ) - I stole much of his text when writing the extension 408 definition. 410 7. References 412 7.1. Normative References 414 [RFC0792] Postel, J., "Internet Control Message Protocol", STD 5, 415 RFC 792, DOI 10.17487/RFC0792, September 1981, 416 . 418 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 419 Communication Layers", STD 3, RFC 1122, 420 DOI 10.17487/RFC1122, October 1989, 421 . 423 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 424 Requirement Levels", BCP 14, RFC 2119, 425 DOI 10.17487/RFC2119, March 1997, 426 . 428 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 429 Resource Identifier (URI): Generic Syntax", STD 66, 430 RFC 3986, DOI 10.17487/RFC3986, January 2005, 431 . 433 [RFC4884] Bonica, R., Gan, D., Tappan, D., and C. Pignataro, 434 "Extended ICMP to Support Multi-Part Messages", RFC 4884, 435 DOI 10.17487/RFC4884, April 2007, 436 . 438 [RFC7710] Kumari, W., Gudmundsson, O., Ebersman, P., and S. Sheng, 439 "Captive-Portal Identification Using DHCP or Router 440 Advertisements (RAs)", RFC 7710, DOI 10.17487/RFC7710, 441 December 2015, . 443 7.2. Informative References 445 [I-D.ietf-sidr-iana-objects] 446 Manderson, T., Vegoda, L., and S. Kent, "RPKI Objects 447 issued by IANA", draft-ietf-sidr-iana-objects-03 (work in 448 progress), May 2011. 450 Appendix A. Changes / Author Notes. 452 [RFC Editor: Please remove this section before publication ] 454 From -01 to 02. 456 o Added a new ICMP Type, redefined message payload and flags, and 457 introduces Codes/C-Types. 459 From -00 to 01. 461 o Changed the Captive Portal URL to a URI, and specificed that this 462 can ONLY contain a path element, which is appended to 463 http://. This is to prevent hijacking connections to 464 other addresses. 466 o Then removed the entire URL / URI scheme entirely. 468 From -genesis to -00. 470 o Initial text. 472 Authors' Addresses 474 David Bird 475 Google 476 1600 Amphitheatre Parkway 477 Mountain View, CA 94043 478 US 480 Email: dbird@google.com 482 Warren Kumari 483 Google 484 1600 Amphitheatre Parkway 485 Mountain View, CA 94043 486 US 488 Email: warren@kumari.net