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]