本备忘录状态

本文档不是互联网标准跟踪规范；它是为资料性目的而发布的。¶

这是对 RFC 系列的贡献，独立于任何其他 RFC 流。 RFC 编辑器已自行决定发布本文档，并且不对其实现或部署价值 作出任何声明。经 RFC 编辑器批准发布的文档不是任何级别 互联网标准的候选；见 RFC 7841 第 2 节。¶

关于本文档当前状态、任何勘误以及如何提供反馈的信息，可通过 https://www.rfc-editor.org/info/rfc8785 获得。¶

版权声明

版权所有 (c) 2020 IETF Trust 和列为本文档作者的人员。 保留所有权利。¶

本文档受 BCP 78 以及在本文档发布之日生效的 IETF Trust 与 IETF 文档相关的法律条款 (https://trustee.ietf.org/license-info) 约束。请仔细阅读这些文档，因为它们描述了你关于本文档的 权利与限制。¶

目录

1. 引言

本文档描述 JSON 规范化方案 (JCS)。 本规范定义了如何通过基于 ECMAScript [ECMA-262] 为 JSON 原语定义的严格序列化方法、将 JSON [RFC8259] 数据约束到 I-JSON [RFC7493] 子集，以及使用确定性的属性排序，来创建 JSON 数据的规范表示。 JCS 的输出是 JSON 数据的一种“可哈希”表示，可供加密方法使用。 后续段落概述主要设计考虑。¶

哈希和签名等加密操作需要将数据表示为一种不变格式， 以便这些操作能够可靠地重复执行。 实现这一点的一种方式是把数据转换为一种具有简单且固定表示的格式， 例如 base64url [RFC4648]。 JSON Web Signature (JWS) [RFC7515] 就是这样处理这一问题的。 另一种解决方案是创建数据的规范版本， 类似于 XML 签名 [XMLDSIG] 标准所采用的做法。¶

规范化方案的主要优势是数据可以保持其原始形式。 这是 JCS 背后的核心理由。 换句话说，使用规范化使 JSON 对象即使在签名之后仍能保持为 JSON 对象。 这可以简化系统设计、文档编写和日志记录。¶

为避免“重新发明轮子”，JCS 依赖 ECMAScript（又称 JavaScript） [ECMA-262] 从第 6 版开始定义的 JSON 原语 （字符串、数字和字面量）序列化。¶

经验丰富的 XML 开发人员可能还记得让 XML 签名通过验证时遇到的困难。 这通常是由于对相当复杂的 XML 规范化规则以及同样复杂的 Web Services 安全标准有不同解释造成的。 JCS 不应遭受类似问题的原因如下：¶

• JSON 没有命名空间概念和默认值。¶
• 数据被约束到 I-JSON [RFC7493] 子集。 这消除了为处理规范化而需要特定解析器的必要性。¶
• JCS 兼容的 JSON 原语序列化目前受到大多数 Web 浏览器以及 Node.js [NODEJS] 的支持。¶
• 完整的 JCS 规范目前受到多个开源实现的支持（见附录 G）。 另见附录 F 中的实现指南。¶

JCS 与一些依赖 JSON 规范化的现有系统兼容，例如 JSON Web Key (JWK) Thumbprint [RFC7638] 和 Keybase [KEYBASE]。¶

关于加密之外的潜在用途，见 [JSONCOMP]。¶

本文档的预期读者是 JSON 工具供应商以及基于 JSON 的加密解决方案的设计者。 假定读者了解 ECMAScript，包括 "JSON" 对象。¶

2. 术语

注意，本文档不属于 IETF 标准跟踪。然而，出于安全性和互操作性原因， 合规实现应当遵循所规定的行为。本文使用 BCP 14 来描述这种必要行为。¶

本文档中的关键词 "MUST"、"MUST NOT"、 "REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、 "RECOMMENDED"、"NOT RECOMMENDED"、 "MAY" 和 "OPTIONAL"，当且仅当它们以全大写形式出现时， 应按 BCP 14 [RFC2119] [RFC8174] 中的描述进行解释， 如这里所示。¶

3. 详细操作

本节描述与创建规范 JSON 表示相关的细节，以及 JCS 如何处理这些细节。¶

附录 F 描述了向现有 JSON 工具添加 JCS 支持的 RECOMMENDED 方式。¶

  {
    "numbers": [333333333.33333329, 1E30, 4.50,
                2e-3, 0.000000000000000000000000001],
    "string": "\u20ac$\u000F\u000aA'\u0042\u0022\u005c\\\"\/",
    "literals": [null, true, false]
  }

  {"numbers":[333333333.3333333,1e+30,4.5,0.002,1e-27],"string":
  "€$\u000f\nA'B\"\\\\\"/","literals":[null,true,false]}

  {"literals":[null,true,false],"numbers":[333333333.3333333,
  1e+30,4.5,0.002,1e-27],"string":"€$\u000f\nA'B\"\\\\\"/"}

  {
    "\u20ac": "Euro Sign",
    "\r": "Carriage Return",
    "\ufb33": "Hebrew Letter Dalet With Dagesh",
    "1": "One",
    "\ud83d\ude00": "Emoji: Grinning Face",
    "\u0080": "Control",
    "\u00f6": "Latin Small Letter O With Diaeresis"
  }

  "Carriage Return"
  "One"
  "Control"
  "Latin Small Letter O With Diaeresis"
  "Euro Sign"
  "Emoji: Grinning Face"
  "Hebrew Letter Dalet With Dagesh"

  7b 22 6c 69 74 65 72 61 6c 73 22 3a 5b 6e 75 6c 6c 2c 74 72
  75 65 2c 66 61 6c 73 65 5d 2c 22 6e 75 6d 62 65 72 73 22 3a
  5b 33 33 33 33 33 33 33 33 33 2e 33 33 33 33 33 33 33 2c 31
  65 2b 33 30 2c 34 2e 35 2c 30 2e 30 30 32 2c 31 65 2d 32 37
  5d 2c 22 73 74 72 69 6e 67 22 3a 22 e2 82 ac 24 5c 75 30 30
  30 66 5c 6e 41 27 42 5c 22 5c 5c 5c 5c 5c 22 2f 22 7d

4. IANA 考虑事项

本文档没有 IANA 操作。¶

5. 安全考虑事项

对输入数据执行健全性检查至关重要，以避免缓冲区溢出以及可能影响系统完整性的类似问题。¶

当 JCS 应用于签名方案（例如附录 F 中描述的方案）时，应用在根据接收数据采取行动之前 MUST 执行以下操作：¶

1. 解析 JSON 数据并验证其符合 I-JSON。¶
2. 根据将要使用该数据的生态系统所定义的约定，验证数据的正确性。 这还包括定位保存签名数据的属性。¶
3. 验证签名。¶

如果这些步骤中的任何一步失败，正在进行的操作 MUST 被中止。¶

附录 A. ECMAScript 示例 规范化器

下面是一个用于基于 ECMAScript 系统的 JCS 规范化器示例：¶

  ////////////////////////////////////////////////////////////
  // Since the primary purpose of this code is highlighting //
  // the core of the JCS algorithm, error handling and      //
  // UTF-8 generation were not implemented.                 //
  ////////////////////////////////////////////////////////////
  var canonicalize = function(object) {

      var buffer = '';
      serialize(object);
      return buffer;

      function serialize(object) {
          if (object === null || typeof object !== 'object' ||
              object.toJSON != null) {
              /////////////////////////////////////////////////
              // Primitive type or toJSON, use "JSON"        //
              /////////////////////////////////////////////////
              buffer += JSON.stringify(object);

          } else if (Array.isArray(object)) {
              /////////////////////////////////////////////////
              // Array - Maintain element order              //
              /////////////////////////////////////////////////
              buffer += '[';
              let next = false;
              object.forEach((element) => {
                  if (next) {
                      buffer += ',';
                  }
                  next = true;
                  /////////////////////////////////////////
                  // Array element - Recursive expansion //
                  /////////////////////////////////////////
                  serialize(element);
              });
              buffer += ']';

          } else {
              /////////////////////////////////////////////////
              // Object - Sort properties before serializing //
              /////////////////////////////////////////////////
              buffer += '{';
              let next = false;
              Object.keys(object).sort().forEach((property) => {
                  if (next) {
                      buffer += ',';
                  }
                  next = true;
                  /////////////////////////////////////////////
                  // Property names are strings, use "JSON"  //
                  /////////////////////////////////////////////
                  buffer += JSON.stringify(property);
                  buffer += ':';
                  //////////////////////////////////////////
                  // Property value - Recursive expansion //
                  //////////////////////////////////////////
                  serialize(object[property]);
              });
              buffer += '}';
          }
      }
  };

附录 B. 数字序列化 样例

下表包含一组与 ECMAScript 兼容的数字序列化样例， 包括一些边界情况。"IEEE 754" 列指的是 "Number" 数据类型的 内部 ECMAScript 表示，该表示基于 IEEE 754 [IEEE754] 标准，使用 64 位（双精度）值，这里以十六进制表示。¶

注：¶

(1)

为了最大限度符合 ECMAScript "JSON" 对象， 要解释为真整数的值 SHOULD 位于 -9007199254740991 到 9007199254740991 范围内。 然而，数字在应用中的使用方式不会影响 JCS 算法。¶

(2)

尽管像 2**68 这样的一组特定整数可被视为具有扩展精度， 但 JCS/ECMAScript 数字序列化算法并不考虑这一点。¶

(3)

JSON 中不允许超出范围的值。 见第 3.2.2.3 节。¶

(4)

该数字精确值为 1424953923781206.25，但在应用 第 3.2.2.3 节 中提到的 "Note 2" 规则后，将被截断并舍入到最接近的偶数值。¶

若要对 JCS 数字序列化器进行更详尽的验证，你可以测试 开发门户（见附录 I）中 （目前）可用的、包含大量样例值的文件。另一个选择是运行 V8 [V8] 作为实时参考，并配合一个生成大量随机 IEEE 754 值的程序。¶

附录 C. 作为“线路格式”的规范化 JSON

由于规范化过程（见第 3.2.4 节）的结果是完全有效的 JSON， 它也可以用作“线路格式”。然而，这只是一个选项，因为基于 JCS 的加密方案在大多数情况下并不依赖外部提供的 JSON 数据已经规范化。¶

实际上，使用 "JSON.stringify()" 序列化对象的 ECMAScript 标准方式 会产生一种更“合乎逻辑”的格式，其中属性保持其创建或接收时的顺序。 下面的示例展示了一个可能受益于 ECMAScript 标准序列化的地址记录：¶

  {
    "name": "John Doe",
    "address": "2000 Sunset Boulevard",
    "city": "Los Angeles",
    "zip": "90001",
    "state": "CA"
  }

使用规范化后，上述属性将按 "address"、"city"、"name"、 "state" 和 "zip" 的顺序输出，从人类（开发者或技术支持） 角度看，这会给数据增加模糊性。 规范化还会将 JSON 数据转换为单行文本，这对于调试和日志记录 可能并不理想。¶

附录 D. 处理大数

JSON 数字类型存在若干相关问题，这里通过以下示例对象进行说明：¶

  {
    "giantNumber": 1.4e+9999,
    "payMeThis": 26000.33,
    "int64Max": 9223372036854775807
  }

尽管上述样例符合 JSON [RFC8259]， 应用通常会使用不同的原生数据类型来存储 "giantNumber" 和 "int64Max"。 此外，像 "payMeThis" 这样的货币数据大概不会依赖浮点数据类型， 因为十进制算术存在舍入问题。¶

处理 JSON 数字类型这种“重载”的既定方式（至少以可扩展方式而言） 是通过映射机制，根据属性名称指示解析器应如何处理不同属性。 然而，这大大限制了在 JSON 原始且多少受限的 JavaScript 上下文之外 使用 JSON 数字类型的价值。ECMAScript "JSON" 对象也不支持到 JSON 数字类型的映射。¶

因此，在当前 JSON 生态系统中没有自然位置的数字 MUST 使用 JSON 字符串类型进行包装。 这接近开放系统中的事实标准。这也适用于 JSON 中没有直接支持的 其他数据类型，例如附录 E 中描述的 "DateTime" 对象。¶

在使用 JSON 字符串类型的系统辅助下，无论是像下面这样以编程方式¶

  var obj = JSON.parse('{"giantNumber": "1.4e+9999"}');
  var biggie = new BigNumber(obj.giantNumber);

还是使用像 OpenAPI [OPENAPI] 这样的声明式方案，JCS 都不会对应用施加限制，包括使用 ECMAScript 时也是如此。¶

附录 E. 字符串子类型处理

由于 JSON 中的数据类型集合有限，JSON 字符串类型通常用于保存子类型。 这可能取决于 JSON 解析方法而导致互操作性问题， 面向更广泛受众的 JCS 合规应用 MUST 处理这些问题。¶

假设你想解析一个 JSON 对象，其中模式设计者指定属性 "big" 用于保存 "BigInt" 子类型，"time" 用于保存 "DateTime" 子类型， 而 "val" 应当是一个符合 JCS 的 JSON 数字。 以下示例展示了这样的对象：¶

  {
    "time": "2019-01-28T07:45:10Z",
    "big": "055",
    "val": 3.5
  }

可以通过以下 ECMAScript 语句解析该对象：¶

  var object = JSON.parse(JSON_object_featured_as_a_string);

解析后，可以提取实际数据；对于子类型， 这还涉及使用解析过程结果（一个 ECMAScript 对象）作为输入的转换步骤：¶

  ... = new Date(object.time); // Date object
  ... = BigInt(object.big);    // Big integer
  ... = object.val;            // JSON/JS number

注意，"BigInt" 数据类型目前仅由 V8 [V8] 原生支持。¶

使用附录 A中的示例代码对 "object" 进行规范化，将返回以下字符串：¶

  {"big":"055","time":"2019-01-28T07:45:10Z","val":3.5}

尽管这在 JCS 方面技术上是正确的，但还有另一种解析 JSON 数据的方式， 也可以与 ECMAScript 一起使用，如下所示：¶

  // "BigInt" requires the following code to become JSON serializable
  BigInt.prototype.toJSON = function() {
      return this.toString();
  };

  // JSON parsing using a "stream"-based method
  var object = JSON.parse(JSON_object_featured_as_a_string,
      (k,v) => k == 'time' ? new Date(v) : k == 'big' ? BigInt(v) : v
  );

如果现在将附录 A中的规范化器应用到 "object"，将生成以下字符串：¶

  {"big":"55","time":"2019-01-28T07:45:10.000Z","val":3.5}

在这种情况下，"big" 和 "time" 的字符串参数相对于原始值发生了变化， 很可能会使依赖 JCS 的应用失败。¶

产生偏差的原因是，在基于流和基于模式的 JSON 解析器中， 原始字符串参数通常会即时被原生子类型替换，而该子类型在序列化时 可能表现出不同且依赖平台的模式。¶

也就是说，基于流和基于模式的解析 MUST 将子类型视为“纯”（不可变）JSON 字符串类型，并在后续步骤中 执行到指定原生类型的实际转换。 在 Go、Java 和 C# 等现代编程平台中，可以通过结合注解、getter 和 setter 以适度工作量实现这一点。下面是 C#/Json.NET 中的一个示例， 展示了可序列化为 JSON 对象的类的一部分：¶

  // The "pure" string solution uses a local
  // string variable for JSON serialization while
  // exposing another type to the application
  [JsonProperty("amount")]
  private string _amount;

  [JsonIgnore]
  public decimal Amount {
      get { return decimal.Parse(_amount); }
      set { _amount = value.ToString(); }
  }

在应用中，"Amount" 可以像任何其他属性一样访问， 而在 JSON 上下文中它实际上由带引号的字符串表示。¶

注意：上述示例还处理了 I-JSON 隐含的数字数据约束 （C# "decimal" 数据类型与 IEEE 754 双精度相比具有相当不同的特性）。¶

附录 F. 实现指南

最优解决方案是在 JSON 序列化器中直接集成 JCS 支持 （解析器不需要改变）。 也就是说，规范化只是 JSON 序列化器的一个附加“模式”。 然而，目前情况并非如此。 幸运的是，可以通过外部提供的规范化器软件作为现有 JSON 序列化器的后处理器来引入 JCS 支持。 这种安排还使 JCS 实现者无需处理底层数据应如何表示为 JSON。¶

后处理器概念支持如下签名创建方案：¶

1. 创建要签名的数据。¶
2. 使用现有 JSON 工具序列化数据。¶
3. 让外部规范化器处理序列化数据，并返回规范化后的结果数据。¶
4. 对规范化数据进行签名。¶
5. 通过指定的签名属性将生成的签名值添加到原始 JSON 数据中。¶
6. 使用现有 JSON 工具序列化已完成的（现在已签名的）JSON 对象。¶

兼容的签名验证方案随后如下：¶

1. 使用现有 JSON 工具解析已签名的 JSON 数据。¶
2. 从指定的签名属性读取并保存签名值。¶
3. 从解析后的 JSON 对象中移除签名属性。¶
4. 使用现有 JSON 工具序列化剩余的 JSON 数据。¶
5. 让外部规范化器处理序列化数据，并返回规范化后的结果数据。¶
6. 使用创建签名时所用的算法和密钥，验证规范化数据是否与保存的签名值匹配。¶

上述规范化器实际上只是一个“过滤器”，可能可与多种相当不同的加密方案一起使用。¶

使用集成 JCS 支持的 JSON 序列化器时， 对于这两个过程，都可以消除规范化步骤之前执行的序列化。¶

附录 G. 开源 实现

以下开源实现已被验证与 JCS 兼容：¶

• JavaScript：<https://www.npmjs.com/package/canonicalize>¶
• Java：<https://github.com/erdtman/java-json-canonicalization>¶
• Go：<https://github.com/cyberphone/json-canonicalization/tree/master/go>¶
• .NET/C#：<https://github.com/cyberphone/json-canonicalization/tree/master/dotnet>¶
• Python：<https://github.com/cyberphone/json-canonicalization/tree/master/python3>¶

附录 H. 其他 JSON 规范化 工作

还有（并且曾经有）其他创建“Canonical JSON”的工作。 下面列出其中一些工作的 URL：¶

• <https://tools.ietf.org/html/draft-staykov-hu-json-canonical-form-00>¶
• <https://gibson042.github.io/canonicaljson-spec/>¶
• <http://wiki.laptop.org/go/Canonical_JSON>¶

列出的工作都基于文本级 JSON 到 JSON 转换。 文本级规范化的主要特性是，它可以被设计为对所使用的 JSON 风格保持中立。 然而，这类方案也意味着需要对 JSON 解析过程进行重大改变， 这很可能成为采用障碍。 尽管需要付出某些 JSON 和应用约束的代价，JCS 仍被设计为 与现有 JSON 工具兼容。¶

附录 I. 开发门户

JCS 规范目前在以下位置开发： <https://github.com/cyberphone/ietf-json-canon>。¶

JCS 源代码和大量测试数据可在以下位置获得： <https://github.com/cyberphone/json-canonicalization>。¶

致谢

基于 ECMAScript 数字序列化这一做法最初由 James Manger 提出。 这最终促成了对 JSON 原语采用完整 ECMAScript 序列化方案。¶

其他为本规范贡献了宝贵意见的人包括 Scott Ananian、 Tim Bray、 Ben Campbell、 Adrian Farell、 Richard Gibson、 Bron Gondwana、 John-Mark Gurney、 Mike Jones, John Levine、 Mark Miller、 Matthew Miller、 Mark Nottingham、 Mike Samuel、 Jim Schaad、 Robert Tupelo-Schneck 和 Michal Wadas。¶

为进行真实世界的概念验证， Ulf Adams、 Tanner Gooding 和 Remy Oudompheng 提供的软件以及对数字序列化的支持非常有帮助。¶

作者地址