idnits 2.17.1 draft-donnelly-capport-detection-01.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 (March 13, 2017) is 2595 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-01) exists of draft-larose-capport-architecture-00 == Outdated reference: A later version (-09) exists of draft-newton-json-content-rules-07 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7710 (Obsoleted by RFC 8910) -- Obsolete informational reference (is this intentional?): RFC 7749 (Obsoleted by RFC 7991) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Captive Portal WG M. Donnelly 3 Internet-Draft M. Cullen 4 Intended status: Informational Painless Security 5 Expires: September 14, 2017 March 13, 2017 7 Captive Portal (CAPPORT) API 8 draft-donnelly-capport-detection-01 10 Abstract 12 This document describes an HTTP API that allows User Equipment to 13 detect the existence of a Captive Portal on the local network, 14 determine the properties of the Captive Portal, and satisfy 15 requirements for network access. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 14, 2017. 34 Copyright Notice 36 Copyright (c) 2017 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Requirements Notation . . . . . . . . . . . . . . . . . . . . 3 53 3. Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4. Use of the DHCP Captive-Portal Option . . . . . . . . . . . . 4 55 5. CAPPORT API . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 5.1. URLs and HTTP Methods . . . . . . . . . . . . . . . . . . 4 57 5.1.1. Associating User Equipment with its URL . . . . . . . 4 58 5.1.2. Fallback URL . . . . . . . . . . . . . . . . . . . . 4 59 5.1.3. CAPPORT API POST URL . . . . . . . . . . . . . . . . 5 60 5.1.4. CAPPORT REST API DELETE URL . . . . . . . . . . . . . 5 61 5.2. JSON Data Structures . . . . . . . . . . . . . . . . . . 5 62 5.2.1. CAPPORT Common Elements . . . . . . . . . . . . . . . 5 63 5.2.1.1. Toplevel Object . . . . . . . . . . . . . . . . . 5 64 5.2.1.2. Networks Object . . . . . . . . . . . . . . . . . 6 65 5.2.1.3. Network Object . . . . . . . . . . . . . . . . . 6 66 5.2.1.4. Condition Object . . . . . . . . . . . . . . . . 7 67 5.2.1.5. Session Token Object . . . . . . . . . . . . . . 7 68 5.2.2. User Equipment Request . . . . . . . . . . . . . . . 8 69 5.2.2.1. Satisfaction Details Object . . . . . . . . . . . 8 70 5.2.3. CAPPORT API Server Response . . . . . . . . . . . . . 8 71 5.2.3.1. Requirement Details Object . . . . . . . . . . . 8 72 5.2.3.2. Network State Object . . . . . . . . . . . . . . 9 73 6. Network Access Conditions . . . . . . . . . . . . . . . . . . 9 74 6.1. Terms and Conditions . . . . . . . . . . . . . . . . . . 9 75 6.1.1. Requirements . . . . . . . . . . . . . . . . . . . . 10 76 6.1.2. Satisfaction . . . . . . . . . . . . . . . . . . . . 10 77 6.2. Passcode . . . . . . . . . . . . . . . . . . . . . . . . 10 78 6.2.1. Requirements . . . . . . . . . . . . . . . . . . . . 11 79 6.2.2. Satisfaction . . . . . . . . . . . . . . . . . . . . 11 80 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 81 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 82 8.1. Privacy Considerations . . . . . . . . . . . . . . . . . 11 83 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 84 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 85 10.1. Normative References . . . . . . . . . . . . . . . . . . 12 86 10.2. Informative References . . . . . . . . . . . . . . . . . 12 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 89 1. Introduction 91 This document describes a HyperText Transfer Protocol (HTTP) 92 Application Program Interface (API) that allows User Equipment to 93 detect the existence of a Captive Portal (CAPPORT) on the local 94 network, determine the properties of the Captive Portal, and satisfy 95 requirements for network access. The API defined in this document 96 has been designed to meet the requirements of the CAPPORT API, as 97 discussed in the CAPPORT Architecture 98 [I-D.larose-capport-architecture]. 100 2. Requirements Notation 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in [RFC2119]. 106 3. Workflow 108 The CAPPORT protocol consists of three phases. In the first phase 109 User Equipment acquires an IP address and determines the URL of the 110 local CAPPORT API Server, if any. The second phase consists of the 111 User Equipment querying the CAPPORT API Server for the requirements 112 for accessing its protected networks, and submitting proofs of 113 meeting those requirements. In the third phase, the User Equipment 114 is granted access to the protected network and can query the CAPPORT 115 API Server for status. 117 During the first phase, User Equipment uses the Dynamic Host 118 Configuration Protocol (DHCP) or IPv6 Router Advertisements (RAs) to 119 acquire an IP address and to determine the URL for the local CAPPORT 120 API Server. This details for the first phase are described in RFC 121 7710 [RFC7710], and the rest of this document assumes that the User 122 Equipments already has a URL to reach the CAPPORT API Server. 124 The second phase begins with the User Equipment accessing the URL 125 provided in the first phase. The CAPPORT API Server responds with 126 the current status of the User Equipment's access to the protected 127 networks and any conditions requirements to gain access to the 128 protected networks. The User Equipment then submits proofs of 129 satisfying the access requirements to the CAPPORT API Server. The 130 CAPPORT API Server again responds with the current status of the User 131 Equipment and any additional requirements necessary to gain access to 132 the protected network. The second phase continues until all of the 133 requirements are met; the CAPPORT API Server grants access to the 134 protected network and responds with a status indicating the access. 136 At any point in the second phase, the User Equipment MAY stop 137 communicating over the CAPPORT protocol and instead direct a web 138 browser to access the URL. The web browser then becomes the agent 139 for proving that the User Equipment meets the requirements for access 140 to the protected networks. 142 During the third phase, the User Equipment has access to the 143 protected network. The User Equipment may access the URL provided in 144 the first phase to query the current status. The CAPPORT API Server 145 responds with the current status of the User Equipment. The CAPPORT 146 API Server SHOULD respond with the current status of the User 147 Equipment regardless of whether the User Equipment used the automated 148 CAPPORT protocol or a web browser to complete the second phase. 150 4. Use of the DHCP Captive-Portal Option 152 As decribed above, to use the CAPPORT API, User Equipment needs a URL 153 that can be used to reach the CAPPORT API Server. DHCP Servers and 154 IPv6 Routers should provide, and User Equipment SHOULD obtain, the 155 required URL using the DCHP Captive-Portal Option or the IPv6 RA 156 Captive-Portal Option, as described in [RFC7710]. 158 To provide backwards compatibility with the original use of the DHCP 159 and RA options described in RFC7710, the CAPPORT API defined in this 160 document is exclusively accessed using HTTP Methods with an Accept 161 header value of "application/json". Captive Portals that implement 162 the CAPPORT API SHOULD respond to an HTTP GET that has an Accept 163 header of "text/html" with HTML content that, when displayed in a web 164 browser, will allow the user to interactively meet the Captive Portal 165 requirements for network access. 167 5. CAPPORT API 169 This section defines the CAPPORT API. 171 5.1. URLs and HTTP Methods 173 This section describes the URLs that can be used to access the 174 CAPPORT API. 176 5.1.1. Associating User Equipment with its URL 178 The CAPPORT API Server SHOULD associate an incoming request with a 179 particular User Equipment consistently. [TODO: specify how this 180 would happen.] 182 5.1.2. Fallback URL 184 The CAPPORT API Server SHOULD respond to HTTP GET requests to the 185 provided URL that specify an Accept header value of "text/html" with 186 HTML content instead of this protocol. If the User Equipment 187 determines that it is unable to satisfy the conditions for network 188 access, it SHOULD display this fallback URL in a web browser to allow 189 the user to complete the network access outside of this protocol. 191 5.1.3. CAPPORT API POST URL 193 The CAPPORT API Server SHOULD respond to HTTP POST requests to the 194 provided URL that specify an Accept header value of "application/ 195 json" with the CAPPORT API protocol. 197 5.1.4. CAPPORT REST API DELETE URL 199 The CAPPORT API Server SHOULD respond to HTTP DELETE requests to the 200 provided URL that specify an Accept header value of "application/ 201 json" by revoking any network access to protected networks 202 immediately. The CAPPORT API Server MUST NOT allow any device other 203 than the User Equipment to DELETE the network access of the User 204 Equipment via the CAPPORT API. 206 The CAPPORT API Server MAY delete the session token (Section 5.2.1.5) 207 for this User Equipment as part of the DELETE request. 209 5.2. JSON Data Structures 211 The CAPPORT API data structures are specified in JavaScript Object 212 Notation (JSON) [RFC7159]. This document specifies the structure of 213 the JSON structures and message using the JSON Content Rules (JCR) 214 defined in draft-newton-json-content-rules 215 [I-D.newton-json-content-rules]. 217 5.2.1. CAPPORT Common Elements 219 This section describes structures that are shared between requests 220 and responses. 222 5.2.1.1. Toplevel Object 224 The CAPPORT API will contain JSON-formatted data. The toplevel 225 object contains a networks object whose value is an array of zero or 226 more network objects. 228 $toplevel = { 229 $networks , 230 $session_token ? 231 } 233 The toplevel object MUST contain a networks object. 235 The CAPPORT API Server responses MUST contain a session_token object. 236 The session-token object contains a session token which will be used 237 in ICMP requests as discussed in RFC 7710. 239 _QUESTION:_ Should the session token just be provided by the server, 240 or should it be negotiated between the client and server using 241 something like a DH exchange? 243 5.2.1.2. Networks Object 245 The networks object represents the list of networks being acted on in 246 this CAPPORT session. 248 $networks = { 249 ( "DEFAULT" || // ) = $network + 250 } 252 The networks object is a JSON object whose keys are network names and 253 whose values are network objects. Thus a single response could be 254 used in gaining access to multiple protected networks at once. The 255 first request to the CAPPORT API Server will contain no networks, and 256 acts as a discovery request. 258 The CAPPORT API Server SHOULD use the special name DEFAULT for one 259 network that provides access to the greater Internet. 261 5.2.1.3. Network Object 263 The network object represents a network protected by the Captive 264 Portal. 266 $network = { 267 "conditions" : [ $condition + ] , 268 "state" : $network_state ? , 269 "details" : $network_details ? 270 } 272 The network object MUST contain a 'conditions' key whose value is an 273 array of one or more $condition objects, which represent the unmet 274 conditions for gaining access to this network. The conditions object 275 SHOULD NOT contain conditions that have already been met. 277 CAPPORT API Server responses MUST contain the 'state' key, whose 278 value is the $network_state object, which represents the state of 279 access that the User Equipment has to the network. 281 CAPPORT API Server responses SHOULD contain the 'details' key, whose 282 value is the $network_details object, which provides relevant 283 information about the network. 285 5.2.1.4. Condition Object 287 The condition object describes one of the conditions necessary for 288 access to the protected network. The CAPPORT API Server uses this 289 object to express the requirements for User Equipment to access the 290 protected network. The User Equipment uses this object as proof that 291 it has satisfied the corresponding requirement for access to the 292 protected network. 294 $condition = { 295 "id" : $uuid, 296 "type" : string ? , 297 "requirement_details" : $requirement_details ? , 298 "satisfaction_details" : $satisfaction_details ? 299 } 301 The condition object MUST include an 'id' key whose value is a UUID 302 that uniquely identifies this condition. This ID will be used to 303 match the client condition satisfactions with the server condition 304 requirements. 306 CAPPORT API Server responses MUST contain the 'type' key, whose value 307 is a string that represents the type of condition that permits access 308 to the network. 310 CAPPORT API Server responses MUST contain the 'requirement_details' 311 key, whose value is the $requirement_details object. The 312 $requirement_details object details the requirements that the User 313 Equipment must pass to gain access to the protected network. 315 User Equipment requests MUST contain the 'satisfaction_details' key, 316 whose value is the $satisfaction_details object. The $satisfaction 317 _details object details the proof that the User Equipment has 318 satisfied the conditions of access to the protected network. 320 5.2.1.5. Session Token Object 322 The session_token object describes the CAPPORT session token. 324 $session_token = "session_token" : base64 326 The session_token object MUST include a "session_token" key whose 327 value is a base64-encoded string of a 32-bit session token. This 328 token will be used as proposed in [I-D.larose-capport-architecture]. 329 The CAPPORT API Server SHOULD send the same session token to a given 330 User Equipment in every response, until the User Equipment DELETEs 331 its network access (Section 5.1.4). After a DELETE, the CAPPORT API 332 Server MAY generate a new session token if the User Equipment makes a 333 new request. 335 5.2.2. User Equipment Request 337 For the initial CAPPORT request from the User Equipment, the JSON 338 object will consist of the toplevel object (Section 5.2.1.1) with its 339 required networks (Section 5.2.1.2) and session_token 340 (Section 5.2.1.5) objects. The networks object will contain no 341 networks, and the session_token object will be empty. This acts as a 342 discovery request. 344 { 345 "networks" : {} 346 "session-token" : "" 347 } 349 Figure 1 351 Subsequent CAPPORT requests will contain data to satisfy conditions 352 to access protected networks. 354 5.2.2.1. Satisfaction Details Object 356 The satisfaction_details object details proof that the User Equipment 357 has satisfied one of the conditions of access to a protected network. 359 $satisfaction_details = { // : any + } 361 Like the requirement details (Section 5.2.3.1) in the CAPPORT API 362 Server Response, the list of keys and values for this object will 363 depend on the value of the 'type' key in the enclosing condition 364 (Section 5.2.1.4). Section 6 contains conditions and their 365 Satisfaction Details Objects. 367 5.2.3. CAPPORT API Server Response 369 5.2.3.1. Requirement Details Object 371 The requirement_details object details the requirements of the 372 Captive Portal Enforcement for access to a protected network. 374 $requirement_details = { // : any + } 376 Like the satisfaction details (Section 5.2.2.1), of the User 377 Equipment Request, the list of keys and values for this object will 378 depend on the value of the 'type' key in the enclosing condition 379 (Section 5.2.1.4). Section 6 contains conditions and their 380 Requirements Details Objects. 382 5.2.3.2. Network State Object 384 The network_state object details the current state of the User 385 Equipment access to the protected network. 387 $network_state = { 388 "permitted" : boolean , 389 "expires" : datetime ? , 390 "bytes_remaining" : integer ? 391 } 393 The network_state object MUST contain the "permitted" key, whose 394 boolean value indicates whether the User Equipment is permitted to 395 access the protected network. 397 The network_state object SHOULD contain the "expires" key if the 398 access to the protected network will expire at a known time in the 399 future. The value is a datetime object of the time the access will 400 expire. If there is not a known expiration time, the key SHOULD be 401 omitted. 403 The network_state object SHOULD contain the "bytes_remaining" key if 404 the access to the protected network will expire after the User 405 Equipment transfers a known number of bytes. The value is an integer 406 of the number of bytes remaining. If there is not a known limit for 407 this User Equipment, the key MAY be omitted or its value MAY be -1. 409 6. Network Access Conditions 411 Captive Portal systems will have many conditions for access to their 412 protected networks. The conditions object is open for use in 413 expressing different conditions. Each condition MUST define a "type" 414 string, its requirement_details, and its satisfaction_details. 416 6.1. Terms and Conditions 418 One common use of a Captive Portal is for the User to accept some 419 terms and conditions for the network access. This network access 420 condition will communicate the terms and conditions to the User 421 Equipment, and communicate their acceptance back to the CAPPORT API 422 Server. 424 For this network access condition, the condition object's 'type' 425 value MUST be "t&c" 426 This condition is satisfied by presenting an MD5 sum of the terms and 427 conditions document referenced by the requirements. This has the 428 property that the MD5 sum will not change unless the terms and 429 conditions document itself changes. User Equipment MAY cache values 430 and submit a cached value for the MD5 sum preemptively without 431 retrieving the terms and conditions document. 433 6.1.1. Requirements 435 $requirement_details = { 436 "text" : string ?, 437 "html" : string ? 438 } 440 The requirement_details object for the Terms and Conditions network 441 access condition MUST include the "text" key, whose value is a URL 442 referencing the plaintext terms and conditions which govern the use 443 of the protected network. 445 The requirement_details object for the Terms and Conditions network 446 access condition MUST include the "html" key, whose value is a URL 447 referencing the HTML-fomatted terms and conditions which govern the 448 use of the protected network. 450 6.1.2. Satisfaction 452 $satisfaction_details = { 453 "text" : string ?, 454 "html" : string ? 455 } 457 The satisfaction_details object for the Terms and Conditions network 458 access condition MUST include one of "text" or "html" as a key. The 459 satisfaction_details MAY include both. 461 The "text" key of the satisfaction_details object has a string value 462 that is an MD5 sum of the document referred to by the URL provided in 463 the Requirement Details (Section 6.1.1) "text" key's value. 465 The "html" key of the satisfaction_details object has a string value 466 that is an MD5 sum of the document referred to by the URL provided in 467 the Requirement Details (Section 6.1.1) "html" key's value. 469 6.2. Passcode 471 Another common use of a captive portal is to have a user enter a 472 passcode to gain access to the protected network. The Passcode 473 network access condition will communicate the requirement for that 474 passcode to the User Equipment and satisfy the Captive Portal 475 Enforcement that the User Equipment has the correct passcode. 477 For the Passcode network access condition, the condition object's 478 "type" value must be "passcode". 480 6.2.1. Requirements 482 $requirement_details = { } 484 The requirement_details object of the Passcode network access 485 condition has no elements. 487 6.2.2. Satisfaction 489 $satisfaction_details = { 490 "passcode" : string 491 } 493 The satisfaction_details object of the Passcode network access 494 condition MUST include the "passcode" key, whose value is a string of 495 the passcode that grants access to the protected network. 497 7. IANA Considerations 499 This document does not require any IANA allocations. Please remove 500 this section before RFC publication. 502 8. Security Considerations 504 The CAPPORT API described in this document is intended to automate a 505 process that is currently accomplished by a user filling out a HTML 506 form in a Web Browser. Therefore, this mechanism should meet the 507 requirement of being no less secure than presenting the user with a 508 HTML form for completion in a Web Browser, and submitting that form 509 to a Captive Portal. 511 TBD: Provide complete security requirements and analysis. 513 8.1. Privacy Considerations 515 Information passed in this protocol may include a user's personal 516 information, such as a full name and credit card details. Therefore, 517 it is important that CAPPORT API Servers do not allow access to the 518 CAPPORT API over unecrypted sessions. 520 9. Acknowledgements 522 This document was written using xml2rfc, as described in [RFC7749] 524 10. References 526 10.1. Normative References 528 [I-D.larose-capport-architecture] 529 Larose, K. and D. Dolson, "CAPPORT Architecture", draft- 530 larose-capport-architecture-00 (work in progress), March 531 2017. 533 [I-D.newton-json-content-rules] 534 Newton, A. and P. Cordell, "A Language for Rules 535 Describing JSON Content", draft-newton-json-content- 536 rules-07 (work in progress), September 2016. 538 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 539 Requirement Levels", BCP 14, RFC 2119, 540 DOI 10.17487/RFC2119, March 1997, 541 . 543 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 544 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 545 2014, . 547 [RFC7710] Kumari, W., Gudmundsson, O., Ebersman, P., and S. Sheng, 548 "Captive-Portal Identification Using DHCP or Router 549 Advertisements (RAs)", RFC 7710, DOI 10.17487/RFC7710, 550 December 2015, . 552 10.2. Informative References 554 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 555 RFC 7749, DOI 10.17487/RFC7749, February 2016, 556 . 558 Authors' Addresses 560 Mark Donnelly 561 Painless Security 562 14 Summer Street, Suite 202 563 Malden, MA 02148 564 USA 566 Email: mark@painless-security.com 567 URI: http://www.painless-security.com 568 Margaret Cullen 569 Painless Security 570 14 Summer Street, Suite 202 571 Malden, MA 02148 572 USA 574 Phone: +1 781 405-7464 575 Email: margaret@painless-security.com 576 URI: http://www.painless-security.com