JSON Canonicalization Scheme (JCS)
RFC 8785

• Status
• IESG evaluation record
• IESG writeups
• Email expansions
• History

• Versions
• 00
• 01
• 02
• 03
• 04
• 05
• 06
• 07
• 08
• 09
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17



Independent Submission                                       A. Rundgren
Request for Comments: 8785                                   Independent
Category: Informational                                        B. Jordan
ISSN: 2070-1721                                                 Broadcom
                                                              S. Erdtman
                                                              Spotify AB
                                                               June 2020

                   JSON Canonicalization Scheme (JCS)

Abstract

   Cryptographic operations like hashing and signing need the data to be
   expressed in an invariant format so that the operations are reliably
   repeatable.  One way to address this is to create a canonical
   representation of the data.  Canonicalization also permits data to be
   exchanged in its original form on the "wire" while cryptographic
   operations performed on the canonicalized counterpart of the data in
   the producer and consumer endpoints generate consistent results.

   This document describes the JSON Canonicalization Scheme (JCS).  This
   specification defines how to create a canonical representation of
   JSON data by building on the strict serialization methods for JSON
   primitives defined by ECMAScript, constraining JSON data to the
   Internet JSON (I-JSON) subset, and by using deterministic property
   sorting.

Status of This Memo

   This document is not an Internet Standards Track specification; it is
   published for informational purposes.

   This is a contribution to the RFC Series, independently of any other
   RFC stream.  The RFC Editor has chosen to publish this document at
   its discretion and makes no statement about its value for
   implementation or deployment.  Documents approved for publication by
   the RFC Editor are not candidates for any level of Internet Standard;
   see Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   https://www.rfc-editor.org/info/rfc8785.

Copyright Notice

   Copyright (c) 2020 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
   (https://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.

Table of Contents

   1.  Introduction
   2.  Terminology
   3.  Detailed Operation
     3.1.  Creation of Input Data
     3.2.  Generation of Canonical JSON Data
       3.2.1.  Whitespace
       3.2.2.  Serialization of Primitive Data Types
         3.2.2.1.  Serialization of Literals
         3.2.2.2.  Serialization of Strings
         3.2.2.3.  Serialization of Numbers
       3.2.3.  Sorting of Object Properties
       3.2.4.  UTF-8 Generation
   4.  IANA Considerations
   5.  Security Considerations
   6.  References
     6.1.  Normative References
     6.2.  Informative References
   Appendix A.  ECMAScript Sample Canonicalizer
   Appendix B.  Number Serialization Samples
   Appendix C.  Canonicalized JSON as "Wire Format"
   Appendix D.  Dealing with Big Numbers
   Appendix E.  String Subtype Handling
     E.1.  Subtypes in Arrays
   Appendix F.  Implementation Guidelines
   Appendix G.  Open-Source Implementations
   Appendix H.  Other JSON Canonicalization Efforts
   Appendix I.  Development Portal
   Acknowledgements
   Authors' Addresses

1.  Introduction

   This document describes the JSON Canonicalization Scheme (JCS).  This
   specification defines how to create a canonical representation of
   JSON [RFC8259] data by building on the strict serialization methods
   for JSON primitives defined by ECMAScript [ECMA-262], constraining
   JSON data to the I-JSON [RFC7493] subset, and by using deterministic
   property sorting.  The output from JCS is a "hashable" representation
   of JSON data that can be used by cryptographic methods.  The
   subsequent paragraphs outline the primary design considerations.

   Cryptographic operations like hashing and signing need the data to be
   expressed in an invariant format so that the operations are reliably
   repeatable.  One way to accomplish this is to convert the data into a
   format that has a simple and fixed representation, like base64url
   [RFC4648].  This is how JSON Web Signature (JWS) [RFC7515] addressed
   this issue.  Another solution is to create a canonical version of the
   data, similar to what was done for the XML signature [XMLDSIG]
   standard.

   The primary advantage with a canonicalizing scheme is that data can
   be kept in its original form.  This is the core rationale behind JCS.
   Put another way, using canonicalization enables a JSON object to
   remain a JSON object even after being signed.  This can simplify