JSON Web Service Binding
draft-hallambaker-json-web-service-00

Network Working Group                                    P. Hallam-Baker
Internet-Draft                                         Comodo Group Inc.
Intended status: Standards Track                        January 14, 2016
Expires: July 17, 2016

                        JSON Web Service Binding
                 draft-hallambaker-json-web-service-00

Abstract

   The JSON Web Binding describes a standardized approach to
   implementing Web Services.  Services are advertised using the DNS SRV
   and HTTP Well Known Service conventions.  Messages may be
   authenticated or authenticated and encrypted at the message layer in
   addition to any transport and/or network layer security.  Service
   messages are encoded in JSON using Internet time format for Date-Time
   fields and Base64urlencoding for binary objects.

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 July 17, 2016.

Copyright Notice

   Copyright (c) 2016 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

Hallam-Baker              Expires July 17, 2016                 [Page 1]
Internet-Draft          JSON Web Service Binding            January 2016

   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

1.  Introduction

   The JSON Web Binding (JWB) specifies one approach to using DNS
   Discovery [RFC1035], the HTTP [RFC7230] protocol and the JSON data
   encoding [RFC7159] in a Web Service.

   JWB is not the only approach possible, but developing a standard
   means making choices that don?t matter to developers that build on
   it.  While there are infinitely many ways that a Web Service might
   employ HTTP and JSON to implement a Web Service, a client and a
   server can only interoperate if they both agree to use the same one.

      Discovery  Beginning with a DNS address of the service (e.g.
         example.com), the client identifies a specific HTTP URL at
         which to access the service.  The DNS SRV record [RFC2782] and
         Well Known Service [RFC5785] mechanisms are used for this
         purpose.

      Authentication and Encryption  Web Services MAY require
         authentication and encryption services at the message level
         even if transport layer security (e.g.  TLS [RFC5264]) is used.
         Use of such enhancements is signaled using the HTTP Content-
         Encoding header.

      Content Mapping  The mapping of data types described in the
         specification (integer, string, etc.) to JSON data types.
         [RFC3339] Date time encoding and BASE64-url encoding [RFC4648]
         are used to map date-time and binary data types to JSON
         encoding values.

   A key architectural principle that guides the design of JWB is that
   the Web Service application should be as independent of the HTTP
   presentation layer as is possible.  Thus:

   Message semantics are not affected by HTTP headers or the request
   line URL.

   The use of HTTP response codes is limited to reporting errors and
   warnings that arise from the HTTP transport.

   If message layer authentication or authenticated encryption are used,
   this is applied within the HTTP content payload and not through a
   combination of payload and header data.

Hallam-Baker              Expires July 17, 2016                 [Page 2]
Internet-Draft          JSON Web Service Binding            January 2016

2.  Definitions

2.1.  Requirements Language

   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 RFC 2119 [RFC2119].

3.  Service Discovery

   Service discovery is the process of resolving the address of a Web
   Service to a Web Service Endpoint, a URI [RFC3986] at which the
   service is provided.

   A JWB Web Service is specified by giving the DNS Address of the
   service (e.g. example.com), the protocol name (e.g. mmm) and the
   transport (usually tcp).

3.1.  SRV Lookup

   A client attempting to connect to the service first attempts to
   locate an SRV record [RFC2782] for the specified service.

   To resolve the web service in the previous example, the client
   attempts to resolve the DNS SRV records for _mmm._tcp.example.com.

   If a match is found, the client uses the mechanism specified in
   [RFC2782] to choose hosts and attempts to contact each host in turn
   until a successful HTTP connection is established or the maximum
   number of attempts threshold is reached.

3.2.  DNS Fallback

   If no SRV record is found, a client MAY perform fallback discovery if
   explicitly authorized to do so by the corresponding Web Service
   protocol specification.  The client attempts to connect to the host .

   In the previous example, the client would attempt to connect to
   mmm.example.com.

3.3.  .well-known

   A Web Service host typically supports multiple Web Services.  The
   Well Known Services convention is used to specify the URL stem at the
   site.

   Note that in theory a Web Service could have a Well Known Services
   entry that is different to the SRV extension.  Particularly as the

Hallam-Baker              Expires July 17, 2016                 [Page 3]
Internet-Draft          JSON Web Service Binding            January 2016

   requirements for registration in the SRV registry are considerably
   looser (first come first served) than for the Well Known Services
   registry (expert review).  This is of course utterly ridiculous.

4.  HTTP Messages

   JWB makes

4.1.  Request

4.2.  Response

5.  Content Encoding

   The HTTP Content-Encoding header specifies transformations performed
   on the content before the HTTP Transfer encoding was applied.  This
   is commonly used for specifying compression.  In JWB,

   May be direct or include cryptographic enhancement.

   The ASCII Record Separator Character (%x1E) is used to separate
   segments in a multipart encoding.  This follows the practice
   established for JSON log files [RFC7464].

5.1.  Direct

5.2.  Authenticated

5.3.  Authenticated Encryption

6.  Content Type

6.1.  JSON

7.  Normative References

   [RFC1035]  Mockapetris, P., "Domain names - implementation and
              specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
              November 1987.

   [RFC7230]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Message Syntax and Routing", RFC 7230,
              DOI 10.17487/RFC7230, June 2014.

   [RFC7159]  Bray, T., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014.

Hallam-Baker              Expires July 17, 2016                 [Page 4]
Internet-Draft          JSON Web Service Binding            January 2016

   [RFC2782]  Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
              specifying the location of services (DNS SRV)", RFC 2782,
              DOI 10.17487/RFC2782, February 2000.

   [RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
              Uniform Resource Identifiers (URIs)", RFC 5785,
              DOI 10.17487/RFC5785, April 2010.

   [RFC5264]  Niemi, A., Lonnfors, M., and E. Leppanen, "Publication of
              Partial Presence Information", RFC 5264,
              DOI 10.17487/RFC5264, September 2008.

   [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
              Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002.

   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005.

   [RFC7464]  Williams, N., "JavaScript Object Notation (JSON) Text
              Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015.

Author's Address

   Phillip Hallam-Baker
   Comodo Group Inc.

   Email: philliph@comodo.com

Hallam-Baker              Expires July 17, 2016                 [Page 5]