Internet Engineering Task Force A. Rundgren, Ed. Internet-Draft WebPKI.org Intended status: Informational November 4, 2015 Expires: May 7, 2016 Predictable Serialization for JSON Tools draft-rundgren-predictable-serialization-for-json-00 Abstract This specification outlines an optional characteristic of JSON tools like parsers, serving two entirely different purposes: 1) Making information-rich JSON messages more human-readable by honoring the originator's conventions. 2) Facilitating simple "Signed JSON" schemes without necessarily needing specific signature text- processing software. Finally, there is a section containing recommendations for interoperability with systems based on EcmaScript V6 (AKA JavaScript). 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 May 7, 2016. Copyright Notice Copyright (c) 2015 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 Rundgren Expires May 7, 2016 [Page 1] Internet-Draft Predictable Serialization for JSON Tools November 2015 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 2. Predictable Serialization . . . . . . . . . . . . . . . . . . 3 2.1. Ordering of Properties . . . . . . . . . . . . . . . . . 3 2.2. Element Handling . . . . . . . . . . . . . . . . . . . . 3 2.2.1. Whitespace Processing . . . . . . . . . . . . . . . . 4 2.2.2. String Normalization . . . . . . . . . . . . . . . . 4 2.2.3. Number Representation . . . . . . . . . . . . . . . . 4 2.2.4. Other Element Types . . . . . . . . . . . . . . . . . 4 3. Signed JSON Objects . . . . . . . . . . . . . . . . . . . . . 4 3.1. Creating a Signed JSON object . . . . . . . . . . . . . . 4 3.2. Verifying a Signed JSON Object . . . . . . . . . . . . . 5 3.3. Interoperability with EcmaScript V6 . . . . . . . . . . . 6 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 7.2. Informative References . . . . . . . . . . . . . . . . . 8 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction There is currently a strong trend moving from XML, EDI, ASN.1, and plain-text formats to JSON [RFC7159]. Although obviously working, JSON's unspecified of ordering of properties as well as the lack of a canonical form, sometimes make the transition rather painful. The sample below displays the problems in a nutshell. Assume the following JSON message is parsed: { "device": "Pump2", "value": 0.000000000000000001 } After serialization a fully JSON-compliant output may look like: { "value": 1e-18, "device": "Pump2" } Rundgren Expires May 7, 2016 [Page 2] Internet-Draft Predictable Serialization for JSON Tools November 2015 Note: Whitespace was added for brevity. If a JSON object contains dozens of properties the ability for a human to follow a message with respect to its specification (which presumably lists properties in a "logical" order), becomes considerably harder if the properties are serialized in an arbitrary order. In addition, changing the representation of numbers also contributes to confusion. Computers however, do not care. While limitations in JSON-data for human consumption may only be considered a "nuisance", adding a signature property to a JSON object is infeasible unless there is some kind of predictable representation of data. This is one of the reasons why JSON Web Signature (JWS) [RFC7515] specifies that data to be signed must be Base64URL-encoded which though unfortunately makes JWS-signed messages unreadable by humans. 1.1. Notational Conventions 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]. 2. Predictable Serialization To cope with the mentioned drawbacks, this specification introduces a simple predictable serialization scheme, preferably implemented directly in JSON parsers. Note: This is not an attempt to change the JSON language in any way; it is only about how it is processed! 2.1. Ordering of Properties The original property order MUST be honored during parsing of JSON objects to support a subsequent serialization phase. Duplicate or empty properties MUST be rejected. 2.2. Element Handling In addition to preserving property order, this specification implies specific handling of JSON language elements, described in the succeeding sub-sections. Rundgren Expires May 7, 2016 [Page 3] Internet-Draft Predictable Serialization for JSON Tools November 2015 2.2.1. Whitespace Processing All whitespace before and after JSON values and structural characters MUST be removed during serialization. 2.2.2. String Normalization Quoted strings including properties MUST be normalized in a way which is close to the de-facto standard for JSON parsers which is: o JSON '\/' escape sequences MUST be honored on input within quoted strings but be treated as a "degenerate" equivalents to '/' by rewriting them. o Unicode [UNICODE] escape sequences ('\uhhhh') within quoted strings MUST be adjusted as follows: If the Unicode value falls within the ASCII [RFC20] control character range (0x00 - 0x1f), it MUST be rewritten in lower-case hexadecimal notation unless it is one of the pre-defined JSON escapes ('\n' etc.) because the latter have precedence. If the Unicode value is outside of the ASCII control character range, it MUST be replaced by the corresponding Unicode character with the exception of '"' and '\' which always MUST be escaped as well. 2.2.3. Number Representation The textual representation of numbers MUST be preserved during parsing and serialization. That is, if numbers like 3.50 and -0 are encountered during a parsing process, they MUST be serialized as 3.50 and -0 respectively although 3.5 and 0 would be the most natural outcome. 2.2.4. Other Element Types No particular action needs to be taken for the remaining JSON language elements. 3. Signed JSON Objects The following non-normative section shows the principles for creating and verifying in-object signatures built on top of the predictable serialization concept. 3.1. Creating a Signed JSON object Assume there is a JSON object like the following: Rundgren Expires May 7, 2016 [Page 4] Internet-Draft Predictable Serialization for JSON Tools November 2015 { "property-1": ..., "property-2": ..., ... "property-n": ... } A with this specification compliant serialization would then return: {"property-1":...,"property-2":...,..."property-n":...} This string may after conversion to UTF-8 [RFC3629] be signed using any suitable algorithm like HS256 [RFC7518] or RS256 [RFC7518]. Using a bare-bones signature scheme the resulting JSON object could look like the following: { "property-1": ..., "property-2": ..., ... "property-n": ..., "signature":"LmTlQxXB3LgZrNLmhOfMaCnDizczC_RfQ6Kx8iNwfFA" } The actual signature value would typically be Base64URL-encoded [RFC4648]. Note: The placement of the "signature" property with respect to the other properties (1-n) is insignificant. Note: Signed data may very well be "pretty-printed" since whitespace is excluded by the serialization process. 3.2. Verifying a Signed JSON Object The signed object created in the previous section could be verified by performing the following steps: 1. Parse the JSON object 2. Read and decode the value of the "signature" property 3. Remove the "signature" property from the JSON object 4. Serialize the JSON object which should generate exactly the same result as in the preceding section Rundgren Expires May 7, 2016 [Page 5] Internet-Draft Predictable Serialization for JSON Tools November 2015 5. Apply an algorithm-dependent signature verification method using the signature key, the UTF-8 representation of the serialization result from step #4, and the data read in step #2 as input arguments 3.3. Interoperability with EcmaScript V6 Since ECMAScript [ECMA-262] due its availability in Internet browsers represents the largest base of JSON-tools, it seems likely that "Signed JSON" will also be used in such environments. This is indeed possible but there are some constraints that need to be catered for if interoperability with this specification is desired: o Property names MUST NOT be expressed as integer values like "1" because EmcaScript does not honor creation order for such items as described in section 9.1.12 of the EcmaScript V6 specification. o Serialization of floating-point numbers is described in section 7.1.12.1 of the EcmaScript V6 specification. However, since this serialization scheme does not guarantee the correctness of the least significant digit, the following workaround is REQUIRED for maintaining interoperability between different EcmaScript implementations: var aValue = 0.000000000000000001; var myObject = {}; myObject.device = 'Pump2'; myObject.value = parseFloat((Math.abs(aValue) < 2.22507385850721E-308 ? 0 : aValue).toPrecision(15)); // Serialize object to a JSON string var jsonString = JSON.stringify(myObject); // This string can now be signed and the value be // added to the object itself (not shown here) The test with 2.22507385850721E-308 is for dealing with underflow and 15 digits of precision at the same time. Non-EcmaScript systems targeting EcmaScript environments MUST (of course) apply the measures specified above as well. An externally created signed object could for example be supplied as in-line EcmaScript in an HTML document like below: Rundgren Expires May 7, 2016 [Page 6] Internet-Draft Predictable Serialization for JSON Tools November 2015 var inObjectSignedData = { "device": "Pump2", "value": 1e-18, "signature": "LmTlQxXB3LgZrNLmhOfMaCnDizczC_RfQ6Kx8iNwfFA" }; Note: Whitespace can be used to make code more readable without affecting signatures. Note: Quotes around property names are actually redundant if you (as in the example), stick to names that are syntactically compatible with the EcmaScript language. 4. Acknowledgements During the initial design of the JSON Cleartext Signature (JCS) [JCS] scheme which was the "inspiration" for this specification, highly appreciated feedback was provided by Manu Sporny, Jim Klo, Jeffrey Walton, David Chadwick, Jim Schaad, David Waite, Douglas Crockford, Arne Riiber, Sergey Beryozkin, and Brian Campbell. A special thank goes to James Manger who helped weeding out bugs in both the specification and in the reference code. 5. IANA Considerations This memo includes no request to IANA. 6. Security Considerations This specification does (according to the author), not reduce or add vulnerabilities to JSON processing. Bugs in serializing software can though (of course) potentially expose sensitive data to attackers, activate protected APIs, or incorrectly validate signatures. 7. References 7.1. Normative References [RFC20] Cerf, V., "ASCII format for Network Interchange", October 1969, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . Rundgren Expires May 7, 2016 [Page 7] Internet-Draft Predictable Serialization for JSON Tools November 2015 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, . [UNICODE] The Unicode Consortium, "The Unicode Standard", . 7.2. Informative References [ECMA-262] Ecma International, "ECMAScript Language Specification Edition 6", June 2015, . [JCS] Rundgren, A., "JSON Cleartext Signature (JCS)", January 2015, . [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003, . [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, . [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015, . Author's Address Anders Rundgren (editor) WebPKI.org 14 Ave. Du General Leclerc Perols 34470 France Phone: +33 644 75 23 31 Email: anders.rundgren.net@gmail.com Rundgren Expires May 7, 2016 [Page 8]