draft-ietf-capport-api-06.txt   draft-ietf-capport-api-07.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: 2 October 2020 CableLabs Expires: 29 October 2020 CableLabs
31 March 2020 27 April 2020
Captive Portal API Captive Portal API
draft-ietf-capport-api-06 draft-ietf-capport-api-07
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 this API, clients can discover with a Captive Portal system. With this API, clients can discover
how to get out of captivity and fetch state about their Captive how to get out of captivity and fetch state about their Captive
Portal sessions. Portal sessions.
Status of This Memo Status of This Memo
skipping to change at page 1, line 34 skipping to change at page 1, line 34
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 2 October 2020. This Internet-Draft will expire on 29 October 2020.
Copyright Notice Copyright Notice
Copyright (c) 2020 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 (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 2, line 15 skipping to change at page 2, line 15
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 Connection Details . . . . . . . . . . . . . . . . . . . 3 4. API Connection Details . . . . . . . . . . . . . . . . . . . 3
4.1. Server Authentication . . . . . . . . . . . . . . . . . . 4 4.1. Server Authentication . . . . . . . . . . . . . . . . . . 4
5. API State Structure . . . . . . . . . . . . . . . . . . . . . 5 5. API State Structure . . . . . . . . . . . . . . . . . . . . . 5
6. Example Interaction . . . . . . . . . . . . . . . . . . . . . 6 6. Example Interaction . . . . . . . . . . . . . . . . . . . . . 6
7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7
7.1. Privacy Considerations . . . . . . . . . . . . . . . . . 7 7.1. Privacy Considerations . . . . . . . . . . . . . . . . . 8
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
8.1. Captive Portal API JSON Media Type Registration . . . . . 7 8.1. Captive Portal API JSON Media Type Registration . . . . . 8
8.2. Captive Portal API Keys Registry . . . . . . . . . . . . 8 8.2. Captive Portal API Keys Registry . . . . . . . . . . . . 9
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
10.1. Normative References . . . . . . . . . . . . . . . . . . 9 10.1. Normative References . . . . . . . . . . . . . . . . . . 10
10.2. Informative References . . . . . . . . . . . . . . . . . 10 10.2. Informative References . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
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:
skipping to change at page 3, line 5 skipping to change at page 3, line 5
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 defines the [I-D.ietf-capport-architecture] and additionally defines the
following terms: following terms:
* 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.
* Captive Portal API Server: The server exposing the API's defined * Captive Portal API Server: The server exposing the APIs defined in
in this document to the client. This is also referred to as the this document to the client. This is also referred to as the "API
"API server" in this document. server" in this document.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
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.
2. API Server interaction, in which a client queries the state of 2. API Server interaction, in which a client queries the state of
skipping to change at page 4, line 20 skipping to change at page 4, line 30
4.1. Server Authentication 4.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
valid certificate for the hostname in the URI (such as valid certificate for the hostname in the URI ("example.org", in the
"example.com"). The hostname of the API SHOULD be displayed to the example above). The hostname of the API SHOULD be displayed to the
user in order to indicate the entity which is providing the API user in order to indicate the entity which is providing the API
service. service.
Clients performing revocation checking will need some means of Clients performing revocation checking will need some means of
accessing revocation information for certificates presented by the accessing revocation information for certificates presented by the
API server. Online Certificate Status Protocol [RFC6960] (OCSP) API server. Online Certificate Status Protocol [RFC6960] (OCSP)
stapling, using the TLS Certificate Status Request extension stapling, using the TLS Certificate Status Request extension
[RFC6066] SHOULD be used. OCSP stapling allows a client to perform [RFC6066] SHOULD be used. OCSP stapling allows a client to perform
revocation checks without initiating new connections. To allow for revocation checks without initiating new connections. To allow for
other forms of revocation checking, a captive network could permit other forms of revocation checking, a captive network could permit
skipping to change at page 5, line 45 skipping to change at page 6, line 10
as "user-portal-url" allows the user to extend a session once the as "user-portal-url" allows the user to extend a session once the
client is no longer in a state of captivity. This provides a hint client is no longer in a state of captivity. This provides a hint
that a client system can suggest accessing the portal URL to the that a client system can suggest accessing the portal URL to the
user when the session is near its limit in terms of time or bytes. user when the session is near its limit in terms of time or bytes.
* "seconds-remaining" (integer): indicates the number of seconds * "seconds-remaining" (integer): indicates the number of seconds
remaining, after which the client will be placed into a captive remaining, after which the client will be placed into a captive
state. The API server SHOULD include this value if the client is state. The API server SHOULD include this value if the client is
not captive (i.e. captive=false) and the client session is time- not captive (i.e. captive=false) and the client session is time-
limited, and SHOULD omit this value for captive clients (i.e. limited, and SHOULD omit this value for captive clients (i.e.
captive=true). captive=true) or when the session is not time-limited.
* "bytes-remaining" (integer): indicates the number of bytes * "bytes-remaining" (integer): indicates the number of bytes
remaining, after which the client will be in placed into a captive remaining, after which the client will be in placed into a captive
state. The byte count represents the sum of the total number of state. The byte count represents the sum of the total number of
IP packet (layer 3) bytes sent and received by the client. IP packet (layer 3) bytes sent and received by the client.
Captive portal systems might not count traffic to whitelisted Captive portal systems might not count traffic to whitelisted
servers, such as the API server, but clients cannot rely on such servers, such as the API server, but clients cannot rely on such
behavior. The API server SHOULD include this value if the client behavior. The API server SHOULD include this value if the client
is not captive (i.e. captive=false) and the client session is is not captive (i.e. captive=false) and the client session is
byte-limited, and SHOULD omit this value for captive clients (i.e. byte-limited, and SHOULD omit this value for captive clients (i.e.
captive=true). captive=true) or when the session is not byte-limited.
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 8. If a client receives a key that Portal API Keys Registry Section 8. 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
"required" will be considered optional. "required" will be considered optional.
6. Example Interaction 6. Example Interaction
A client connected to a captive network upon discovering the URI of A client connected to a captive network upon discovering the URI of
skipping to change at page 6, line 36 skipping to change at page 6, line 50
The server then responds with the JSON content for that client: The server then responds with the JSON content for that client:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Cache-Control: private Cache-Control: private
Date: Mon, 02 Mar 2020 05:07:35 GMT Date: Mon, 02 Mar 2020 05:07:35 GMT
Content-Type: application/captive+json Content-Type: application/captive+json
{ {
"captive": true, "captive": true,
"user-portal-url": "https://example.org/portal.html"
}
Upon receiving this information the client will use this information
direct the user to the the web portal (as specified by the user-
portal-url value) to enable access to the external network. Once the
user satisfies the requirements for extenal network access, the
client SHOULD query the API server again to verify that it is no
longer captive.
When the client requests the Captive Portal JSON content after
gaining external network access, the server responds with updated
JSON content:
HTTP/1.1 200 OK
Cache-Control: private
Date: Mon, 02 Mar 2020 05:08:13 GMT
Content-Type: application/captive+json
{
"captive": false,
"user-portal-url": "https://example.org/portal.html", "user-portal-url": "https://example.org/portal.html",
"venue-info-url": "https://flight.example.com/entertainment", "venue-info-url": "https://flight.example.com/entertainment",
"seconds-remaining": 326, "seconds-remaining": 326,
"can-extend-session": true "can-extend-session": true
} }
Upon receiving this information the client will provide this
information to the user so that they may navigate the web portal (as
specified by the user-portal-url value) to enable access to the
external network. Once the user satisfies the requirements for
extenal network access, the client SHOULD query the API server again
to verify that it is no longer captive.
Captive Portal JSON content can contain per-client data that is not Captive Portal JSON content can contain per-client data that is not
appropriate to store in an intermediary cache. Captive Portal API appropriate to store in an intermediary cache. Captive Portal API
servers SHOULD set the Cache-Control header in any responses to servers SHOULD set the Cache-Control header in any responses to
"private", or a more restrictive value [RFC7234]. "private", or a more restrictive value [RFC7234].
7. Security Considerations 7. Security Considerations
One of the goals of this protocol is to improve the security of the One of the goals of this protocol is to improve the security of the
communication between client hosts and Captive Portal systems. communication between client hosts and Captive Portal systems.
Client traffic is protected from passive listeners on the local Client traffic is protected from passive listeners on the local
skipping to change at page 8, line 5 skipping to change at page 8, line 32
IANA is requested to create a registration for an "application/ IANA is requested to create a registration for an "application/
captive+json" media type (Section 8.1) and a registry for fields in captive+json" media type (Section 8.1) and a registry for fields in
that format (Section 8.2). that format (Section 8.2).
8.1. Captive Portal API JSON Media Type Registration 8.1. Captive Portal API JSON Media Type Registration
This document registers the media type for Captive Portal API JSON This document registers the media type for Captive Portal API JSON
text, "application/captive+json". text, "application/captive+json".
Type name: application Type name: application
Subtype name: captive+json Subtype name: captive+json
Required parameters: None Required parameters: N/A
Optional parameters: None Optional parameters: N/A
Encoding considerations: Encoding considerations are identical to Encoding considerations: Encoding considerations are identical to
those specified for the "application/json" media type. those specified for the "application/json" media type.
Security considerations: See Section 7 Security considerations: See Section 7
Interoperability considerations: This document specifies format of Interoperability considerations: This document specifies format of
conforming messages and the interpretation thereof. conforming messages and the interpretation thereof.
Published specification: This document Published specification: This document
Applications that use this media type: This media type is intended Applications that use this media type: This media type is intended to
to be used by servers presenting the Captive Portal API, and be used by servers presenting the Captive Portal API, and clients
clients connecting to such captive networks. connecting to such captive networks.
Additional information: None Fragment identifier considerations: N/A
Person & email address to contact for further information: See Additional information: N/A
Authors' Addresses section.
Intended usage: COMMON Person and email address to contact for further information: See
Authors' Addresses section
Restrictions on usage: None Intended usage: COMMON
Author: CAPPORT IETF WG Restrictions on usage: N/A
Change controller: IETF Author: CAPPORT IETF WG
Change controller: IETF
8.2. Captive Portal API Keys Registry 8.2. Captive Portal API Keys Registry
IANA is asked to create and maintain a new registry called "Captive IANA is asked to create and maintain a new registry called "Captive
Portal API Keys", which will reserve JSON keys for use in Captive Portal API Keys", which will reserve JSON keys for use in Captive
Portal API data structures. The initial contents of this registry Portal API data structures. The initial contents of this registry
are provided in Section 5. are provided in Section 5.
Each entry in the registry contains the following fields: Each entry in the registry contains the following fields:
Key: The JSON key being registered, in string format. Key: The JSON key being registered, in string format.
Type: The type of the JSON value to be stored, as one of the value Type: The type of the JSON value to be stored, as one of the value
types defined in [RFC8259]. types defined in [RFC8259].
Description: A brief description explaining the meaning of the Description: A brief description explaining the meaning of the
value, how it might be used, and/or how it should be interpreted value, how it might be used, and/or how it should be interpreted
by clients. by clients.
New assignments for Captive Portal API Keys Registry will be New assignments for Captive Portal API Keys Registry will be
administered by IANA through Expert Review [RFC8126]. The Designated administered by IANA using the Specification Required policy
Expert is expected to validate the existence of documentation [RFC8126]. The Designated Expert is expected to validate the
describing new keys in a permanent publicly available specification. existence of documentation describing new keys in a permanent
The expert is expected to validate that new keys have a clear meaning publicly available specification. The expert is expected to validate
and do not create unnecessary confusion or overlap with existing that new keys have a clear meaning and do not create unnecessary
keys. Keys that are specific to non-generic use cases, particularly confusion or overlap with existing keys. Keys that are specific to
ones that are not specified as part of an IETF document, are non-generic use cases, particularly ones that are not specified as
encouraged to use a domain-specific prefix. part of an IETF document, are encouraged to use a domain-specific
prefix.
9. Acknowledgments 9. 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.
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-capport-rfc7710bis] [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Kumari, W. and E. Kline, "Captive-Portal Identification in Requirement Levels", BCP 14, RFC 2119,
DHCP / RA", Work in Progress, Internet-Draft, draft-ietf- DOI 10.17487/RFC2119, March 1997,
capport-rfc7710bis-03, 30 March 2020, <https://www.rfc-editor.org/info/rfc2119>.
<http://www.ietf.org/internet-drafts/draft-ietf-capport-
rfc7710bis-03.txt>.
[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>.
[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>.
skipping to change at page 10, line 23 skipping to change at page 11, line 10
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
RFC 7234, DOI 10.17487/RFC7234, June 2014, RFC 7234, DOI 10.17487/RFC7234, June 2014,
<https://www.rfc-editor.org/info/rfc7234>. <https://www.rfc-editor.org/info/rfc7234>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[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>.
10.2. Informative References 10.2. Informative References
[I-D.ietf-capport-architecture] [I-D.ietf-capport-architecture]
Larose, K., Dolson, D., and H. Liu, "CAPPORT Larose, K., Dolson, D., and H. Liu, "CAPPORT
Architecture", Work in Progress, Internet-Draft, draft- Architecture", Work in Progress, Internet-Draft, draft-
ietf-capport-architecture-06, 15 February 2020, ietf-capport-architecture-07, 20 April 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-capport- <http://www.ietf.org/internet-drafts/draft-ietf-capport-
architecture-06.txt>. architecture-07.txt>.
[I-D.ietf-capport-rfc7710bis]
Kumari, W. and E. Kline, "Captive-Portal Identification in
DHCP / RA", Work in Progress, Internet-Draft, draft-ietf-
capport-rfc7710bis-03, 30 March 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-capport-
rfc7710bis-03.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
 End of changes. 30 change blocks. 
63 lines changed or deleted 94 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/