Internet DRAFT - draft-rundgren-predictable-serialization-for-json
draft-rundgren-predictable-serialization-for-json
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, <http://www.rfc-editor.org/info/rfc20>.
[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>.
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, <http://www.rfc-editor.org/info/rfc7159>.
[UNICODE] The Unicode Consortium, "The Unicode Standard",
<http://www.unicode.org/versions/latest/>.
7.2. Informative References
[ECMA-262]
Ecma International, "ECMAScript Language Specification
Edition 6", June 2015, <http://www.ecma-
international.org/publications/standards/Ecma-262.htm>.
[JCS] Rundgren, A., "JSON Cleartext Signature (JCS)", January
2015,
<https://cyberphone.github.io/openkeystore/resources/docs/
jcs.html>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <http://www.rfc-editor.org/info/rfc3629>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<http://www.rfc-editor.org/info/rfc4648>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <http://www.rfc-editor.org/info/rfc7515>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI
10.17487/RFC7518, May 2015,
<http://www.rfc-editor.org/info/rfc7518>.
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]
