idnits 2.17.1 draft-ietf-capport-api-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 : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 124: '...the API endpoint MUST be accessed usin...' RFC 2119 keyword, line 125: '... (HTTPS) and SHOULD be served on port 443 [RFC2818]. The client...' RFC 2119 keyword, line 126: '... SHOULD NOT assume that the URI for ...' RFC 2119 keyword, line 127: '...ay the same, and SHOULD rely on the di...' RFC 2119 keyword, line 149: '...tname of the API SHOULD be displayed t...' (9 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 11, 2019) is 1871 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC5785' is defined on line 324, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-10) exists of draft-ietf-capport-architecture-03 Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Captive Portal Interaction T. Pauly, Ed. 3 Internet-Draft Apple Inc. 4 Intended status: Standards Track D. Thakore, Ed. 5 Expires: September 12, 2019 CableLabs 6 March 11, 2019 8 Captive Portal API 9 draft-ietf-capport-api-02 11 Abstract 13 This document describes an HTTP API that allows clients to interact 14 with a Captive Portal system. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on September 12, 2019. 33 Copyright Notice 35 Copyright (c) 2019 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 52 3. Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 4. API Details . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4.1. URI of Captive Portal API endpoint . . . . . . . . . . . 3 55 4.1.1. Server Authentication . . . . . . . . . . . . . . . . 4 56 4.2. JSON Keys . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4.3. An Example Interaction . . . . . . . . . . . . . . . . . 5 58 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 59 5.1. Privacy Considerations . . . . . . . . . . . . . . . . . 6 60 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 61 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 7 62 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 8.1. Normative References . . . . . . . . . . . . . . . . . . 7 64 8.2. Informative References . . . . . . . . . . . . . . . . . 8 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 67 1. Introduction 69 This document describes a HyperText Transfer Protocol (HTTP) 70 Application Program Interface (API) that allows clients to interact 71 with a Captive Portal system. The API defined in this document has 72 been designed to meet the requirements in the Captive Portal 73 Architecture [I-D.ietf-capport-architecture]. Specifically, the API 74 provides: 76 o The state of captivity (whether or not the client has access to 77 the Internet) 79 o A URI that a client browser can present to a user to get out of 80 captivity 82 o An encrypted connection (TLS for both the API and portal URI) 84 2. Terminology 86 This document leverages the terminology and components described in 87 [I-D.ietf-capport-architecture] and additionally uses the following 88 association: 90 o Captive Portal Client: The client that interacts with the captive 91 portal API is typically some application running on the User 92 Equipment that is connected to the Captive Network. This is also 93 referred to as the "client" in this document. 95 o Captive Portal API Server: The server exposing the API's defined 96 in this document to the client. This is also referred to as the 97 "API server" in this document. 99 3. Workflow 101 The Captive Portal Architecture defines three steps of interaction 102 between clients and a Captive Portal service: 104 1. Provisioning, in which a client discovers that a network has a 105 captive portal, and learns the URI of the API server 107 2. API Server interaction, in which a client queries the state of 108 the captive portal and retrieves the necessary information to get 109 out of captivity 111 3. Enforcement, in which the enforcement device in the network 112 blocks disallowed traffic, and sends ICMP messages to let clients 113 know they are blocked by the captive portal 115 This document is focused on the second step. It is assumed that the 116 location of the Captive Portal API server has been discovered by the 117 client as part of the first step. The mechanism for discovering the 118 API Server endpoint is not covered by this document. 120 4. API Details 122 4.1. URI of Captive Portal API endpoint 124 The URI of the API endpoint MUST be accessed using HTTP over TLS 125 (HTTPS) and SHOULD be served on port 443 [RFC2818]. The client 126 SHOULD NOT assume that the URI for a given network attachment will 127 stay the same, and SHOULD rely on the discovery or provisioning 128 process each time it joins the network. Depending on how the Captive 129 Portal system is configured, the URI might be unique for each client 130 host and between sessions for the same client host. 132 For example, if the Captive Portal API server is hosted at 133 example.org, the URI's of the API could be: 135 o "https://example.org/captive-portal/api" 137 o "https://example.org/captive-portal/api/X54PD" 139 4.1.1. Server Authentication 141 The purpose of accessing the Captive Portal API over an HTTPS 142 connection is twofold: first, the encrypted connection protects the 143 integrity and confidentiality of the API exchange from other parties 144 on the local network; and second, it provides the client of the API 145 an opportunity to authenticate the server that is hosting the API. 146 This authentication is aimed at allowing a user to be reasonably 147 confident that the entity providing the Captive Portal API has a 148 valid certificate for the hostname in the URI (such as 149 "example.com"). The hostname of the API SHOULD be displayed to the 150 user in order to indicate the entity which is providing the API 151 service. 153 Clients performing revocation checking will need some means of 154 accessing revocation information for certificates presented by the 155 API server. Online Certificate Status Protocol [RFC6960] (OCSP) 156 stapling, using the TLS Certificate Status Request extension 157 [RFC6066] SHOULD be used. OCSP stapling allows a client to perform 158 revocation checks without initiating new connections. To allow for 159 other forms of revocation checking, a captive network could permit 160 connections to OCSP responders or Certificate Revocation Lists (CRLs) 161 that are referenced by certificates provided by the API server. In 162 addition to connections to OCSP responders and CRLs, a captive 163 network SHOULD also permit connections to Network Time Protocol (NTP) 164 [RFC5905] servers or other time-sync mechnisms to allow clients to 165 accurately validate certificates. 167 Certificates with missing intermediate certificates that rely on 168 clients validating the certificate chain using the URI specified in 169 the Authority Information Access (AIA) extension [RFC5280] SHOULD NOT 170 be used by the Captive Portal API server. If the certificates do 171 require the use of AIA, the captive network will need to allow client 172 access to the host specified in the URI. 174 If the client is unable to validate the certificate presented by the 175 API server, it MUST NOT proceed with any of the behavior for API 176 interaction described in this document. The client will proceed to 177 interact with the captive network as if the API capabilities were not 178 present. It may still be possible for the user to access the network 179 by being redirected to a web portal. 181 4.2. JSON Keys 183 The Captive Portal API data structures are specified in JavaScript 184 Object Notation (JSON) [RFC7159]. Requests and responses for the 185 Captive Portal API use the "application/captive+json" media type. 186 Clients SHOULD include this media type as an Accept header in their 187 GET requests, and servers MUST mark this media type as their Content- 188 Type header in responses. 190 The following keys are defined at the top-level of the JSON structure 191 returned by the API server: 193 o "captive" (required, boolean): indicates whether the client is in 194 a state of captivity, i.e it has not satisfied the conditions to 195 access the external network. If the client is captive (i.e. 196 captive=true), it can still be allowed enough access for it to 197 perform server authentication Section 4.1.1. 199 o "user-portal-url" (required, string): provides the URL of a web 200 portal with which a user can interact. 202 o "vendor-info-url" (optional, string): provides the URL of a 203 webpage or site on which the operator of the network has 204 information that it wishes to share with the user (e.g. store 205 info, maps, flight status, or entertainment). 207 o "expire-date" (optional, string formatted as [RFC3339] datetime): 208 indicates the date and time after which the client will be in a 209 captive state. The API server SHOULD include this value if the 210 client is not captive (i.e. captive=false) and SHOULD omit this 211 value for captive clients. 213 o "bytes-remaining" (optional, integer): indicates the number of 214 bytes remaining, after which the client will be in placed into a 215 captive state. 217 4.3. An Example Interaction 219 A client connected to a captive network upon discovering the URI of 220 the API server will query the API server to retrieve information 221 about its captive state and conditions to escape captivity. To 222 request the Captive Portal JSON content, a client sends an HTTP GET 223 request: 225 GET /captive-portal/api/X54PD 226 Host: example.org 227 Accept: application/captive+json 229 The server then responds with the JSON content for that client: 231 HTTP/1.1 200 OK 232 Cache-Control: private 233 Date: Mon, 04 Dec 2013 05:07:35 GMT 234 Content-Type: application/captive+json 236 { 237 "captive": true, 238 "user-portal-url": "https://example.org/portal.html", 239 "vendor-info-url": "https://flight.example.com/entertainment", 240 "expire-date": "2014-01-01T23:28:56.782Z" 241 } 243 Upon receiving this information the client will provide this 244 information to the user so that they may navigate the web portal (as 245 specified by the user-portal-url value) to enable access to the 246 external network. Once the user satisfies the requirements for 247 extenal network access, the client SHOULD query the API server again 248 to verify that it is no longer captive. 250 5. Security Considerations 252 TBD: Provide complete security requirements and analysis. 254 5.1. Privacy Considerations 256 Information passed in this protocol may include a user's personal 257 information, such as a full name and credit card details. Therefore, 258 it is important that Captive Portal API Servers do not allow access 259 to the Captive Portal API over unencrypted sessions. 261 6. IANA Considerations 263 This document registers the media type for Captive Portal API JSON 264 text, "application/captive+json". 266 Type name: application 268 Subtype name: captive+json 270 Required parameters: None 272 Optional parameters: None 274 Encoding considerations: Encoding considerations are identical to 275 those specified for the "application/json" media type. 277 Security considerations: See Section 5 278 Interoperability considerations: This document specifies format of 279 conforming messages and the interpretation thereof. 281 Published specification: This document 283 Applications that use this media type: This media type is intended 284 to be used by servers presenting the Captive Portal API, and 285 clients connecting to such captive networks. 287 Additional information: None 289 Person & email address to contact for further information: See 290 Authors' Addresses section. 292 Intended usage: COMMON 294 Restrictions on usage: None 296 Author: CAPPORT IETF WG 298 Change controller: IETF 300 7. Acknowledgments 302 This work in this document was started by Mark Donnelly and Margaret 303 Cullen. Thanks to everyone in the CAPPORT Working Group who has 304 given input. 306 8. References 308 8.1. Normative References 310 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 311 DOI 10.17487/RFC2818, May 2000, 312 . 314 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 315 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 316 . 318 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 319 Housley, R., and W. Polk, "Internet X.509 Public Key 320 Infrastructure Certificate and Certificate Revocation List 321 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 322 . 324 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 325 Uniform Resource Identifiers (URIs)", RFC 5785, 326 DOI 10.17487/RFC5785, April 2010, 327 . 329 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 330 "Network Time Protocol Version 4: Protocol and Algorithms 331 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 332 . 334 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 335 Extensions: Extension Definitions", RFC 6066, 336 DOI 10.17487/RFC6066, January 2011, 337 . 339 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 340 Galperin, S., and C. Adams, "X.509 Internet Public Key 341 Infrastructure Online Certificate Status Protocol - OCSP", 342 RFC 6960, DOI 10.17487/RFC6960, June 2013, 343 . 345 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 346 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 347 2014, . 349 8.2. Informative References 351 [I-D.ietf-capport-architecture] 352 Larose, K. and D. Dolson, "CAPPORT Architecture", draft- 353 ietf-capport-architecture-03 (work in progress), December 354 2018. 356 Authors' Addresses 358 Tommy Pauly (editor) 359 Apple Inc. 360 One Apple Park Way 361 Cupertino, California 95014 362 United States of America 364 Email: tpauly@apple.com 365 Darshak Thakore (editor) 366 CableLabs 367 858 Coal Creek Circle 368 Louisville, CO 80027 369 United States of America 371 Email: d.thakore@cablelabs.com