idnits 2.17.1 draft-rundgren-predictable-serialization-for-json-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 4, 2015) is 3067 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force A. Rundgren, Ed. 3 Internet-Draft WebPKI.org 4 Intended status: Informational November 4, 2015 5 Expires: May 7, 2016 7 Predictable Serialization for JSON Tools 8 draft-rundgren-predictable-serialization-for-json-00 10 Abstract 12 This specification outlines an optional characteristic of JSON tools 13 like parsers, serving two entirely different purposes: 1) Making 14 information-rich JSON messages more human-readable by honoring the 15 originator's conventions. 2) Facilitating simple "Signed JSON" 16 schemes without necessarily needing specific signature text- 17 processing software. Finally, there is a section containing 18 recommendations for interoperability with systems based on EcmaScript 19 V6 (AKA JavaScript). 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on May 7, 2016. 38 Copyright Notice 40 Copyright (c) 2015 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 57 2. Predictable Serialization . . . . . . . . . . . . . . . . . . 3 58 2.1. Ordering of Properties . . . . . . . . . . . . . . . . . 3 59 2.2. Element Handling . . . . . . . . . . . . . . . . . . . . 3 60 2.2.1. Whitespace Processing . . . . . . . . . . . . . . . . 4 61 2.2.2. String Normalization . . . . . . . . . . . . . . . . 4 62 2.2.3. Number Representation . . . . . . . . . . . . . . . . 4 63 2.2.4. Other Element Types . . . . . . . . . . . . . . . . . 4 64 3. Signed JSON Objects . . . . . . . . . . . . . . . . . . . . . 4 65 3.1. Creating a Signed JSON object . . . . . . . . . . . . . . 4 66 3.2. Verifying a Signed JSON Object . . . . . . . . . . . . . 5 67 3.3. Interoperability with EcmaScript V6 . . . . . . . . . . . 6 68 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 71 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 73 7.2. Informative References . . . . . . . . . . . . . . . . . 8 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 76 1. Introduction 78 There is currently a strong trend moving from XML, EDI, ASN.1, and 79 plain-text formats to JSON [RFC7159]. Although obviously working, 80 JSON's unspecified of ordering of properties as well as the lack of a 81 canonical form, sometimes make the transition rather painful. 83 The sample below displays the problems in a nutshell. Assume the 84 following JSON message is parsed: 86 { 87 "device": "Pump2", 88 "value": 0.000000000000000001 89 } 91 After serialization a fully JSON-compliant output may look like: 93 { 94 "value": 1e-18, 95 "device": "Pump2" 96 } 98 Note: Whitespace was added for brevity. 100 If a JSON object contains dozens of properties the ability for a 101 human to follow a message with respect to its specification (which 102 presumably lists properties in a "logical" order), becomes 103 considerably harder if the properties are serialized in an arbitrary 104 order. In addition, changing the representation of numbers also 105 contributes to confusion. Computers however, do not care. 107 While limitations in JSON-data for human consumption may only be 108 considered a "nuisance", adding a signature property to a JSON object 109 is infeasible unless there is some kind of predictable representation 110 of data. This is one of the reasons why JSON Web Signature (JWS) 111 [RFC7515] specifies that data to be signed must be Base64URL-encoded 112 which though unfortunately makes JWS-signed messages unreadable by 113 humans. 115 1.1. Notational Conventions 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in RFC 2119 [RFC2119]. 121 2. Predictable Serialization 123 To cope with the mentioned drawbacks, this specification introduces a 124 simple predictable serialization scheme, preferably implemented 125 directly in JSON parsers. 127 Note: This is not an attempt to change the JSON language in any way; 128 it is only about how it is processed! 130 2.1. Ordering of Properties 132 The original property order MUST be honored during parsing of JSON 133 objects to support a subsequent serialization phase. Duplicate or 134 empty properties MUST be rejected. 136 2.2. Element Handling 138 In addition to preserving property order, this specification implies 139 specific handling of JSON language elements, described in the 140 succeeding sub-sections. 142 2.2.1. Whitespace Processing 144 All whitespace before and after JSON values and structural characters 145 MUST be removed during serialization. 147 2.2.2. String Normalization 149 Quoted strings including properties MUST be normalized in a way which 150 is close to the de-facto standard for JSON parsers which is: 152 o JSON '\/' escape sequences MUST be honored on input within quoted 153 strings but be treated as a "degenerate" equivalents to '/' by 154 rewriting them. 156 o Unicode [UNICODE] escape sequences ('\uhhhh') within quoted 157 strings MUST be adjusted as follows: If the Unicode value falls 158 within the ASCII [RFC20] control character range (0x00 - 0x1f), it 159 MUST be rewritten in lower-case hexadecimal notation unless it is 160 one of the pre-defined JSON escapes ('\n' etc.) because the latter 161 have precedence. If the Unicode value is outside of the ASCII 162 control character range, it MUST be replaced by the corresponding 163 Unicode character with the exception of '"' and '\' which always 164 MUST be escaped as well. 166 2.2.3. Number Representation 168 The textual representation of numbers MUST be preserved during 169 parsing and serialization. That is, if numbers like 3.50 and -0 are 170 encountered during a parsing process, they MUST be serialized as 3.50 171 and -0 respectively although 3.5 and 0 would be the most natural 172 outcome. 174 2.2.4. Other Element Types 176 No particular action needs to be taken for the remaining JSON 177 language elements. 179 3. Signed JSON Objects 181 The following non-normative section shows the principles for creating 182 and verifying in-object signatures built on top of the predictable 183 serialization concept. 185 3.1. Creating a Signed JSON object 187 Assume there is a JSON object like the following: 189 { 190 "property-1": ..., 191 "property-2": ..., 192 ... 193 "property-n": ... 194 } 196 A with this specification compliant serialization would then return: 198 {"property-1":...,"property-2":...,..."property-n":...} 200 This string may after conversion to UTF-8 [RFC3629] be signed using 201 any suitable algorithm like HS256 [RFC7518] or RS256 [RFC7518]. 202 Using a bare-bones signature scheme the resulting JSON object could 203 look like the following: 205 { 206 "property-1": ..., 207 "property-2": ..., 208 ... 209 "property-n": ..., 210 "signature":"LmTlQxXB3LgZrNLmhOfMaCnDizczC_RfQ6Kx8iNwfFA" 211 } 213 The actual signature value would typically be Base64URL-encoded 214 [RFC4648]. 216 Note: The placement of the "signature" property with respect to the 217 other properties (1-n) is insignificant. 219 Note: Signed data may very well be "pretty-printed" since whitespace 220 is excluded by the serialization process. 222 3.2. Verifying a Signed JSON Object 224 The signed object created in the previous section could be verified 225 by performing the following steps: 227 1. Parse the JSON object 229 2. Read and decode the value of the "signature" property 231 3. Remove the "signature" property from the JSON object 233 4. Serialize the JSON object which should generate exactly the same 234 result as in the preceding section 236 5. Apply an algorithm-dependent signature verification method using 237 the signature key, the UTF-8 representation of the serialization 238 result from step #4, and the data read in step #2 as input 239 arguments 241 3.3. Interoperability with EcmaScript V6 243 Since ECMAScript [ECMA-262] due its availability in Internet browsers 244 represents the largest base of JSON-tools, it seems likely that 245 "Signed JSON" will also be used in such environments. This is indeed 246 possible but there are some constraints that need to be catered for 247 if interoperability with this specification is desired: 249 o Property names MUST NOT be expressed as integer values like "1" 250 because EmcaScript does not honor creation order for such items as 251 described in section 9.1.12 of the EcmaScript V6 specification. 253 o Serialization of floating-point numbers is described in section 254 7.1.12.1 of the EcmaScript V6 specification. However, since this 255 serialization scheme does not guarantee the correctness of the 256 least significant digit, the following workaround is REQUIRED for 257 maintaining interoperability between different EcmaScript 258 implementations: 260 var aValue = 0.000000000000000001; 261 var myObject = {}; 262 myObject.device = 'Pump2'; 263 myObject.value = 264 parseFloat((Math.abs(aValue) < 2.22507385850721E-308 ? 265 0 : aValue).toPrecision(15)); 267 // Serialize object to a JSON string 268 var jsonString = JSON.stringify(myObject); 270 // This string can now be signed and the value be 271 // added to the object itself (not shown here) 273 The test with 2.22507385850721E-308 is for dealing with underflow and 274 15 digits of precision at the same time. 276 Non-EcmaScript systems targeting EcmaScript environments MUST (of 277 course) apply the measures specified above as well. An externally 278 created signed object could for example be supplied as in-line 279 EcmaScript in an HTML document like below: 281 var inObjectSignedData = 282 { 283 "device": "Pump2", 284 "value": 1e-18, 285 "signature": "LmTlQxXB3LgZrNLmhOfMaCnDizczC_RfQ6Kx8iNwfFA" 286 }; 288 Note: Whitespace can be used to make code more readable without 289 affecting signatures. 291 Note: Quotes around property names are actually redundant if you (as 292 in the example), stick to names that are syntactically compatible 293 with the EcmaScript language. 295 4. Acknowledgements 297 During the initial design of the JSON Cleartext Signature (JCS) [JCS] 298 scheme which was the "inspiration" for this specification, highly 299 appreciated feedback was provided by Manu Sporny, Jim Klo, Jeffrey 300 Walton, David Chadwick, Jim Schaad, David Waite, Douglas Crockford, 301 Arne Riiber, Sergey Beryozkin, and Brian Campbell. 303 A special thank goes to James Manger who helped weeding out bugs in 304 both the specification and in the reference code. 306 5. IANA Considerations 308 This memo includes no request to IANA. 310 6. Security Considerations 312 This specification does (according to the author), not reduce or add 313 vulnerabilities to JSON processing. Bugs in serializing software can 314 though (of course) potentially expose sensitive data to attackers, 315 activate protected APIs, or incorrectly validate signatures. 317 7. References 319 7.1. Normative References 321 [RFC20] Cerf, V., "ASCII format for Network Interchange", October 322 1969, . 324 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 325 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 326 RFC2119, March 1997, 327 . 329 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 330 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 331 2014, . 333 [UNICODE] The Unicode Consortium, "The Unicode Standard", 334 . 336 7.2. Informative References 338 [ECMA-262] 339 Ecma International, "ECMAScript Language Specification 340 Edition 6", June 2015, . 343 [JCS] Rundgren, A., "JSON Cleartext Signature (JCS)", January 344 2015, 345 . 348 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 349 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 350 2003, . 352 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 353 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 354 . 356 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 357 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 358 2015, . 360 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 361 10.17487/RFC7518, May 2015, 362 . 364 Author's Address 366 Anders Rundgren (editor) 367 WebPKI.org 368 14 Ave. Du General Leclerc 369 Perols 34470 370 France 372 Phone: +33 644 75 23 31 373 Email: anders.rundgren.net@gmail.com