draft-ietf-capport-api-03.txt   draft-ietf-capport-api-04.txt 
Captive Portal Interaction T. Pauly, Ed. Captive Portal Interaction T. Pauly, Ed.
Internet-Draft Apple Inc. Internet-Draft Apple Inc.
Intended status: Standards Track D. Thakore, Ed. Intended status: Standards Track D. Thakore, Ed.
Expires: January 7, 2020 CableLabs Expires: 5 July 2020 CableLabs
July 06, 2019 2 January 2020
Captive Portal API Captive Portal API
draft-ietf-capport-api-03 draft-ietf-capport-api-04
Abstract Abstract
This document describes an HTTP API that allows clients to interact This document describes an HTTP API that allows clients to interact
with a Captive Portal system. with a Captive Portal system.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
skipping to change at page 1, line 32 skipping to change at page 1, line 32
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 7, 2020. This Internet-Draft will expire on 5 July 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents (https://trustee.ietf.org/
(https://trustee.ietf.org/license-info) in effect on the date of license-info) in effect on the date of publication of this document.
publication of this document. Please review these documents Please review these documents carefully, as they describe your rights
carefully, as they describe your rights and restrictions with respect and restrictions with respect to this document. Code Components
to this document. Code Components extracted from this document must extracted from this document must include Simplified BSD License text
include Simplified BSD License text as described in Section 4.e of as described in Section 4.e of the Trust Legal Provisions and are
the Trust Legal Provisions and are provided without warranty as provided without warranty as described in the Simplified BSD License.
described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. API Details . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. API Details . . . . . . . . . . . . . . . . . . . . . . . . . 3
4.1. URI of Captive Portal API endpoint . . . . . . . . . . . 3 4.1. URI of Captive Portal API endpoint . . . . . . . . . . . 3
4.1.1. Server Authentication . . . . . . . . . . . . . . . . 4 4.1.1. Server Authentication . . . . . . . . . . . . . . . . 4
4.2. JSON Keys . . . . . . . . . . . . . . . . . . . . . . . . 4 4.2. JSON Keys . . . . . . . . . . . . . . . . . . . . . . . . 5
4.3. Example Interaction . . . . . . . . . . . . . . . . . . . 5 4.3. Example Interaction . . . . . . . . . . . . . . . . . . . 6
5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6
5.1. Privacy Considerations . . . . . . . . . . . . . . . . . 7 5.1. Privacy Considerations . . . . . . . . . . . . . . . . . 7
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
6.1. Captive Portal API JSON Media Type Registration . . . . . 7 6.1. Captive Portal API JSON Media Type Registration . . . . . 7
6.2. Captive Portal API Keys Registry . . . . . . . . . . . . 8 6.2. Captive Portal API Keys Registry . . . . . . . . . . . . 8
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 8 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
8.1. Normative References . . . . . . . . . . . . . . . . . . 9 8.1. Normative References . . . . . . . . . . . . . . . . . . 9
8.2. Informative References . . . . . . . . . . . . . . . . . 9 8.2. Informative References . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10
1. Introduction 1. Introduction
This document describes a HyperText Transfer Protocol (HTTP) This document describes a HyperText Transfer Protocol (HTTP)
Application Program Interface (API) that allows clients to interact Application Program Interface (API) that allows clients to interact
with a Captive Portal system. The API defined in this document has with a Captive Portal system. The API defined in this document has
been designed to meet the requirements in the Captive Portal been designed to meet the requirements in the Captive Portal
Architecture [I-D.ietf-capport-architecture]. Specifically, the API Architecture [I-D.ietf-capport-architecture]. Specifically, the API
provides: provides:
o The state of captivity (whether or not the client has access to * The state of captivity (whether or not the client has access to
the Internet) the Internet)
o A URI that a client browser can present to a user to get out of * A URI that a client browser can present to a user to get out of
captivity captivity
o An encrypted connection (TLS for both the API and portal URI) * An encrypted connection (TLS for both the API and portal URI)
2. Terminology 2. Terminology
This document leverages the terminology and components described in This document leverages the terminology and components described in
[I-D.ietf-capport-architecture] and additionally uses the following [I-D.ietf-capport-architecture] and additionally uses the following
association: association:
o Captive Portal Client: The client that interacts with the Captive * Captive Portal Client: The client that interacts with the Captive
Portal API is typically some application running on the User Portal API is typically some application running on the User
Equipment that is connected to the Captive Network. This is also Equipment that is connected to the Captive Network. This is also
referred to as the "client" in this document. referred to as the "client" in this document.
o Captive Portal API Server: The server exposing the API's defined * Captive Portal API Server: The server exposing the API's defined
in this document to the client. This is also referred to as the in this document to the client. This is also referred to as the
"API server" in this document. "API server" in this document.
3. Workflow 3. Workflow
The Captive Portal Architecture defines several categories of The Captive Portal Architecture defines several categories of
interaction between clients and Captive Portal systems: interaction between clients and Captive Portal systems:
1. Provisioning, in which a client discovers that a network has a 1. Provisioning, in which a client discovers that a network has a
captive portal, and learns the URI of the API server. captive portal, and learns the URI of the API server.
skipping to change at page 3, line 45 skipping to change at page 3, line 45
(HTTPS) and SHOULD be served on port 443 [RFC2818]. The client (HTTPS) and SHOULD be served on port 443 [RFC2818]. The client
SHOULD NOT assume that the URI for a given network attachment will SHOULD NOT assume that the URI for a given network attachment will
stay the same, and SHOULD rely on the discovery or provisioning stay the same, and SHOULD rely on the discovery or provisioning
process each time it joins the network. Depending on how the Captive process each time it joins the network. Depending on how the Captive
Portal system is configured, the URI might be unique for each client Portal system is configured, the URI might be unique for each client
host and between sessions for the same client host. host and between sessions for the same client host.
For example, if the Captive Portal API server is hosted at For example, if the Captive Portal API server is hosted at
example.org, the URI's of the API could be: example.org, the URI's of the API could be:
o "https://example.org/captive-portal/api" * "https://example.org/captive-portal/api"
o "https://example.org/captive-portal/api/X54PD" * "https://example.org/captive-portal/api/X54PD"
4.1.1. Server Authentication 4.1.1. Server Authentication
The purpose of accessing the Captive Portal API over an HTTPS The purpose of accessing the Captive Portal API over an HTTPS
connection is twofold: first, the encrypted connection protects the connection is twofold: first, the encrypted connection protects the
integrity and confidentiality of the API exchange from other parties integrity and confidentiality of the API exchange from other parties
on the local network; and second, it provides the client of the API on the local network; and second, it provides the client of the API
an opportunity to authenticate the server that is hosting the API. an opportunity to authenticate the server that is hosting the API.
This authentication is aimed at allowing a user to be reasonably This authentication is aimed at allowing a user to be reasonably
confident that the entity providing the Captive Portal API has a confident that the entity providing the Captive Portal API has a
skipping to change at page 5, line 10 skipping to change at page 5, line 17
The Captive Portal API data structures are specified in JavaScript The Captive Portal API data structures are specified in JavaScript
Object Notation (JSON) [RFC8259]. Requests and responses for the Object Notation (JSON) [RFC8259]. Requests and responses for the
Captive Portal API use the "application/captive+json" media type. Captive Portal API use the "application/captive+json" media type.
Clients SHOULD include this media type as an Accept header in their Clients SHOULD include this media type as an Accept header in their
GET requests, and servers MUST mark this media type as their Content- GET requests, and servers MUST mark this media type as their Content-
Type header in responses. Type header in responses.
The following keys are defined at the top-level of the JSON structure The following keys are defined at the top-level of the JSON structure
returned by the API server: returned by the API server:
o "captive" (required, boolean): indicates whether the client is in * "captive" (required, boolean): indicates whether the client is in
a state of captivity, i.e it has not satisfied the conditions to a state of captivity, i.e it has not satisfied the conditions to
access the external network. If the client is captive (i.e. access the external network. If the client is captive (i.e.
captive=true), it can still be allowed enough access for it to captive=true), it can still be allowed enough access for it to
perform server authentication Section 4.1.1. perform server authentication Section 4.1.1.
o "user-portal-url" (optional, string): provides the URL of a web * "user-portal-url" (optional, string): provides the URL of a web
portal with which a user can interact. portal with which a user can interact.
o "venue-info-url" (optional, string): provides the URL of a webpage * "venue-info-url" (optional, string): provides the URL of a webpage
or site on which the operator of the network has information that or site on which the operator of the network has information that
it wishes to share with the user (e.g., store info, maps, flight it wishes to share with the user (e.g., store info, maps, flight
status, or entertainment). status, or entertainment).
o "expire-date" (optional, string formatted as [RFC3339] datetime): * "seconds-remaining" (optional, integer): indicates the number of
indicates the date and time after which the client will be in a seconds remaining, after which the client will be placed into a
captive state. The API server SHOULD include this value if the captive state. The API server SHOULD include this value if the
client is not captive (i.e. captive=false) and SHOULD omit this client is not captive (i.e. captive=false) and SHOULD omit this
value for captive clients. value for captive clients.
o "bytes-remaining" (optional, integer): indicates the number of * "bytes-remaining" (optional, integer): indicates the number of
bytes remaining, after which the client will be in placed into a bytes remaining, after which the client will be in placed into a
captive state. The byte count represents the total number of IP captive state. The byte count represents the total number of IP
packet (layer 3) bytes sent and received by the client. Captive packet (layer 3) bytes sent and received by the client. Captive
portal systems might not count traffic to whitelisted servers, portal systems might not count traffic to whitelisted servers,
such as the API server, but clients cannot rely on such behavior. such as the API server, but clients cannot rely on such behavior.
The valid JSON keys can be extended by adding entries to the Captive The valid JSON keys can be extended by adding entries to the Captive
Portal API Keys Registry Section 6. If a client receives a key that Portal API Keys Registry Section 6. If a client receives a key that
it does not recognize, it MUST ignore the key and any associated it does not recognize, it MUST ignore the key and any associated
values. All keys other than the ones defined in this document as values. All keys other than the ones defined in this document as
skipping to change at page 9, line 4 skipping to change at page 9, line 12
ones that are not specified as part of an IETF document, are ones that are not specified as part of an IETF document, are
encouraged to use a domain-specific prefix. encouraged to use a domain-specific prefix.
7. Acknowledgments 7. Acknowledgments
This work in this document was started by Mark Donnelly and Margaret This work in this document was started by Mark Donnelly and Margaret
Cullen. Thanks to everyone in the CAPPORT Working Group who has Cullen. Thanks to everyone in the CAPPORT Working Group who has
given input. given input.
8. References 8. References
8.1. Normative References 8.1. Normative References
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
DOI 10.17487/RFC2818, May 2000, DOI 10.17487/RFC2818, May 2000,
<https://www.rfc-editor.org/info/rfc2818>. <https://www.rfc-editor.org/info/rfc2818>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
<https://www.rfc-editor.org/info/rfc5280>. <https://www.rfc-editor.org/info/rfc5280>.
[RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch,
"Network Time Protocol Version 4: Protocol and Algorithms "Network Time Protocol Version 4: Protocol and Algorithms
Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010,
<https://www.rfc-editor.org/info/rfc5905>. <https://www.rfc-editor.org/info/rfc5905>.
skipping to change at page 9, line 49 skipping to change at page 10, line 6
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
8.2. Informative References 8.2. Informative References
[I-D.ietf-capport-architecture] [I-D.ietf-capport-architecture]
Larose, K. and D. Dolson, "CAPPORT Architecture", draft- Larose, K. and D. Dolson, "CAPPORT Architecture", Work in
ietf-capport-architecture-04 (work in progress), June Progress, Internet-Draft, draft-ietf-capport-architecture-
2019. 05, 31 December 2019, <http://www.ietf.org/internet-
drafts/draft-ietf-capport-architecture-05.txt>.
Authors' Addresses Authors' Addresses
Tommy Pauly (editor) Tommy Pauly (editor)
Apple Inc. Apple Inc.
One Apple Park Way One Apple Park Way
Cupertino, California 95014 Cupertino, California 95014,
United States of America United States of America
Email: tpauly@apple.com Email: tpauly@apple.com
Darshak Thakore (editor) Darshak Thakore (editor)
CableLabs CableLabs
858 Coal Creek Circle 858 Coal Creek Circle
Louisville, CO 80027 Louisville, CO 80027,
United States of America United States of America
Email: d.thakore@cablelabs.com Email: d.thakore@cablelabs.com
 End of changes. 24 change blocks. 
39 lines changed or deleted 36 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/