Internet DRAFT - draft-donnelly-capport-detection
draft-donnelly-capport-detection
Captive Portal WG M. Donnelly
Internet-Draft M. Cullen
Intended status: Informational Painless Security
Expires: January 4, 2018 July 3, 2017
Captive Portal (CAPPORT) API
draft-donnelly-capport-detection-02
Abstract
This document describes an HTTP API that allows User Equipment to
detect the existence of a Captive Portal on the local network and
determine the properties of the Captive Portal.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 4, 2018.
Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Donnelly & Cullen Expires January 4, 2018 [Page 1]
Internet-Draft Captive Portal (CAPPORT) API July 2017
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Requirements Notation . . . . . . . . . . . . . . . . . . . . 2
3. Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Use of the DHCP Captive-Portal Option . . . . . . . . . . . . 3
5. CAPPORT API . . . . . . . . . . . . . . . . . . . . . . . . . 3
5.1. URLs and HTTP Methods . . . . . . . . . . . . . . . . . . 4
5.1.1. Associating User Equipment with its URL . . . . . . . 4
5.1.2. Interactive URL . . . . . . . . . . . . . . . . . . . 4
5.1.3. CAPPORT API POST URL . . . . . . . . . . . . . . . . 4
5.2. JSON Data Structures . . . . . . . . . . . . . . . . . . 4
5.2.1. CAPPORT Common Elements . . . . . . . . . . . . . . . 4
5.2.1.1. Toplevel Object . . . . . . . . . . . . . . . . . 4
5.2.1.2. Networks Object . . . . . . . . . . . . . . . . . 5
5.2.1.3. Network Object . . . . . . . . . . . . . . . . . 5
5.2.2. User Equipment Request . . . . . . . . . . . . . . . 6
5.2.2.1. CAPPORT API Server Response . . . . . . . . . . . 6
5.2.2.1.1. Network State Object . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
7. Security Considerations . . . . . . . . . . . . . . . . . . . 7
7.1. Privacy Considerations . . . . . . . . . . . . . . . . . 7
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
9.1. Normative References . . . . . . . . . . . . . . . . . . 7
9.2. Informative References . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8
1. Introduction
This document describes a HyperText Transfer Protocol (HTTP)
Application Program Interface (API) that allows User Equipment to
detect the existence of a Captive Portal (CAPPORT) on the local
network and determine the properties of the Captive Portal. The API
defined in this document has been designed to meet the requirements
of the CAPPORT API, as discussed in the CAPPORT Architecture
[I-D.larose-capport-architecture].
2. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in[RFC2119].
Donnelly & Cullen Expires January 4, 2018 [Page 2]
Internet-Draft Captive Portal (CAPPORT) API July 2017
3. Workflow
The CAPPORT protocol consists of two phases. In the first phase User
Equipment acquires an IP address and determines the URL of the local
CAPPORT API Server, if any. The second phase consists of the User
Equipment querying the CAPPORT API Server for the requirements for
accessing its protected networks.
During the first phase, User Equipment uses the Dynamic Host
Configuration Protocol (DHCP) or IPv6 Router Advertisements (RAs) to
acquire an IP address and to determine the URL for the local CAPPORT
API Server. This details for the first phase are described in RFC
7710[RFC7710], and the rest of this document assumes that the User
Equipments already has a URL to reach the CAPPORT API Server.
The second phase begins with the User Equipment accessing the URL
provided in the first phase with JSON content type. The CAPPORT API
Server responds with the current status of the User Equipment's
access to the protected networks.
The User Equipment SHOULD request the same URL with an HTML content
type to start the process to gain access to the Captive Portal.
4. Use of the DHCP Captive-Portal Option
As decribed above, to use the CAPPORT API, User Equipment needs a URL
that can be used to reach the CAPPORT API Server. DHCP Servers and
IPv6 Routers SHOULD provide, and User Equipment SHOULD obtain, the
required URL using the DCHP Captive-Portal Option or the IPv6 RA
Captive-Portal Option, as described in [RFC7710].
To provide backwards compatibility with the original use of the DHCP
and RA options described in RFC7710, the CAPPORT API defined in this
document is exclusively accessed using HTTP with an Accept header
value of "application/json". Captive Portals that implement the
CAPPORT API SHOULD respond to an HTTP GET that has an Accept header
of "text/html" with HTML content that, when displayed in a web
browser, will allow the user to interactively meet the Captive Portal
requirements for network access.
5. CAPPORT API
This section defines the CAPPORT API.
Donnelly & Cullen Expires January 4, 2018 [Page 3]
Internet-Draft Captive Portal (CAPPORT) API July 2017
5.1. URLs and HTTP Methods
This section describes the URLs that can be used to access the
CAPPORT API.
5.1.1. Associating User Equipment with its URL
The CAPPORT API Server SHOULD associate an incoming request with a
particular User Equipment consistently. [TODO: specify how this
would happen.]
5.1.2. Interactive URL
The CAPPORT API Server SHOULD respond to HTTP GET requests to the
provided URL that specify an Accept header value of "text/html" with
HTML content instead of this protocol. When the User Equipment wants
to satisfy the conditions for network access, it SHOULD display this
interactive URL in a web browser to allow the user to complete the
network access outside of this protocol.
5.1.3. CAPPORT API POST URL
The CAPPORT API Server SHOULD respond to HTTP POST requests to the
provided URL that specify an Accept header value of "application/
json" with the CAPPORT API protocol.
5.2. JSON Data Structures
The CAPPORT API data structures are specified in JavaScript Object
Notation (JSON)[RFC7159]. This document specifies the structure of
the JSON structures and message using the JSON Content Rules (JCR)
defined in draft-newton-json-content-rules
[I-D.newton-json-content-rules].
5.2.1. CAPPORT Common Elements
This section describes structures that are shared between requests
and responses.
5.2.1.1. Toplevel Object
The CAPPORT API will contain JSON-formatted data. The toplevel
object contains a networks object whose value is an array of zero or
more network objects.
Donnelly & Cullen Expires January 4, 2018 [Page 4]
Internet-Draft Captive Portal (CAPPORT) API July 2017
$toplevel = {
$networks ,
$session_token ?
}
The toplevel object MUST contain a networks object.
The CAPPORT API Server responses MUST contain a session_token object.
The session-token object contains a session token which will be used
in ICMP requests as discussed in RFC 7710.
_QUESTION:_ Should the session token just be provided by the server,
or should it be negotiated between the client and server using
something like a DH exchange?
5.2.1.2. Networks Object
The networks object represents the list of networks being acted on in
this CAPPORT session.
$networks = {
( "DEFAULT" || // ) = $network +
}
The networks object is a JSON object whose keys are network names and
whose values are network objects. Thus a single response could be
used in gaining access to multiple protected networks at once. The
first request to the CAPPORT API Server will contain no networks, and
acts as a discovery request.
The CAPPORT API Server SHOULD use the special name DEFAULT for one
network that provides access to the greater Internet.
5.2.1.3. Network Object
The network object represents a network protected by the Captive
Portal.
$network = {
"conditions" : [ $condition + ] ,
"state" : $network_state ? ,
"details" : $network_details ?
}
The network object MUST contain a 'conditions' key whose value is an
array of one or more $condition objects, which represent the unmet
conditions for gaining access to this network. The conditions object
SHOULD NOT contain conditions that have already been met.
Donnelly & Cullen Expires January 4, 2018 [Page 5]
Internet-Draft Captive Portal (CAPPORT) API July 2017
CAPPORT API Server responses MUST contain the 'state' key, whose
value is the $network_state object, which represents the state of
access that the User Equipment has to the network.
CAPPORT API Server responses SHOULD contain the 'details' key, whose
value is the $network_details object, which provides relevant
information about the network.
5.2.2. User Equipment Request
For the initial CAPPORT request from the User Equipment, the JSON
object will consist of the toplevel object (Section 5.2.1.1) with its
required networks (Section 5.2.1.2) objects. The networks object
will contain no networks, and the session_token object will be empty.
This acts as a discovery request.
{
"networks" : {}
"session-token" : ""
}
Figure 1
5.2.2.1. CAPPORT API Server Response
5.2.2.1.1. Network State Object
The network_state object details the current state of the User
Equipment access to the protected network.
$network_state = {
"permitted" : boolean ,
"expires" : datetime ? ,
"bytes_remaining" : integer ?
}
The network_state object MUST contain the "permitted" key, whose
boolean value indicates whether the User Equipment is permitted to
access the protected network.
The network_state object SHOULD contain the "expires" key if the
access to the protected network will expire at a known time in the
future. The value is a datetime object of the time the access will
expire. If there is not a known expiration time, the key SHOULD be
omitted.
The network_state object SHOULD contain the "bytes_remaining" key if
the access to the protected network will expire after the User
Donnelly & Cullen Expires January 4, 2018 [Page 6]
Internet-Draft Captive Portal (CAPPORT) API July 2017
Equipment transfers a known number of bytes. The value is an integer
of the number of bytes remaining. If there is not a known limit for
this User Equipment, the key MAY be omitted or its value MAY be -1.
6. IANA Considerations
This document does not require any IANA allocations. Please remove
this section before RFC publication.
7. Security Considerations
The CAPPORT API described in this document is intended to automate a
process that is currently accomplished by a user filling out a HTML
form in a Web Browser. Therefore, this mechanism should meet the
requirement of being no less secure than presenting the user with a
HTML form for completion in a Web Browser, and submitting that form
to a Captive Portal.
TBD: Provide complete security requirements and analysis.
7.1. Privacy Considerations
Information passed in this protocol may include a user's personal
information, such as a full name and credit card details. Therefore,
it is important that CAPPORT API Servers do not allow access to the
CAPPORT API over unecrypted sessions.
8. Acknowledgements
This document was written using xml2rfc, as described in [RFC7749]
9. References
9.1. Normative References
[I-D.larose-capport-architecture]
Larose, K. and D. Dolson, "CAPPORT Architecture", draft-
larose-capport-architecture-01 (work in progress), June
2017.
[I-D.newton-json-content-rules]
Newton, A. and P. Cordell, "A Language for Rules
Describing JSON Content", draft-newton-json-content-
rules-08 (work in progress), March 2017.
Donnelly & Cullen Expires January 4, 2018 [Page 7]
Internet-Draft Captive Portal (CAPPORT) API July 2017
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <http://www.rfc-editor.org/info/rfc7159>.
[RFC7710] Kumari, W., Gudmundsson, O., Ebersman, P., and S. Sheng,
"Captive-Portal Identification Using DHCP or Router
Advertisements (RAs)", RFC 7710, DOI 10.17487/RFC7710,
December 2015, <http://www.rfc-editor.org/info/rfc7710>.
9.2. Informative References
[RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary",
RFC 7749, DOI 10.17487/RFC7749, February 2016,
<http://www.rfc-editor.org/info/rfc7749>.
Authors' Addresses
Mark Donnelly
Painless Security
14 Summer Street, Suite 202
Malden, MA 02148
USA
Email: mark@painless-security.com
URI: http://www.painless-security.com
Margaret Cullen
Painless Security
14 Summer Street, Suite 202
Malden, MA 02148
USA
Phone: +1 781 405-7464
Email: margaret@painless-security.com
URI: http://www.painless-security.com
Donnelly & Cullen Expires January 4, 2018 [Page 8]