[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02

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]


Html markup produced by rfcmarkup 1.124, available from https://tools.ietf.org/tools/rfcmarkup/