このメモの位置づけ

本文書は Internet Standards Track 仕様ではなく、情報提供を目的として 公開される。¶

これは、他の RFC ストリームとは独立した RFC Series への寄稿である。 RFC Editor はその裁量により本文書を公開することを選択しており、 実装または展開に対する価値についていかなる声明も行わない。 RFC Editor によって公開が承認された文書は、どの水準の Internet Standard の候補でもない。RFC 7841 の Section 2 を参照。¶

本文書の現在の状態、正誤表、およびフィードバックの送付方法に関する 情報は、 https://www.rfc-editor.org/info/rfc8785 で入手できる。¶

著作権表示

Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.¶

本文書は、公開日に有効な BCP 78 および IETF Trust の Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) の対象となる。これらの文書には、本文書に関する権利および制限が 記載されているため、注意深く確認すること。¶

目次

1. 導入

本文書は JSON Canonicalization Scheme (JCS) について記述する。 本仕様は、ECMAScript [ECMA-262] によって 定義される JSON プリミティブの厳密なシリアル化方法を基盤とし、 JSON データを I-JSON [RFC7493] サブセットに制約し、決定的なプロパティソートを使用することで、 JSON [RFC8259] データの 正準表現を作成する方法を定義する。JCS の出力は、 暗号手法で使用できる JSON データの「ハッシュ可能な」表現である。 以降の段落では、主要な設計上の考慮事項の概要を述べる。¶

ハッシュ化や署名のような暗号操作では、操作を確実に 繰り返せるように、データが不変の形式で表現されている 必要がある。 これを実現する 1 つの方法は、base64url [RFC4648] のような、単純で固定された表現を持つ形式にデータを変換することである。 JSON Web Signature (JWS) [RFC7515] は、 この問題にそのように対処した。 もう 1 つの解決策は、XML signature [XMLDSIG] 標準で行われたことに似た、データの 正準バージョンを作成することである。¶

正準化スキームの主な利点は、データを元の形式のまま 保持できることである。これが JCS の中核的な根拠である。 別の言い方をすれば、正準化を使用することで、署名後であっても JSON オブジェクトを JSON オブジェクトのままにしておくことができる。 これは、システム設計、文書化、およびロギングを簡素化できる。¶

「車輪の再発明」を避けるため、JCS は、バージョン 6 以降の ECMAScript（別名 JavaScript） [ECMA-262] によって定義される JSON プリミティブ（文字列、数値、およびリテラル）のシリアル化に依存する。¶

経験豊富な XML 開発者は、XML 署名の検証を成功させる際の困難を 思い出すかもしれない。これは通常、非常に入り組んだ XML 正準化規則の 解釈の違い、および同じく複雑な Web Services セキュリティ標準の 解釈の違いによるものであった。JCS が同様の問題を抱えるべきではない 理由は次のとおりである。¶

• JSON には名前空間の概念およびデフォルト値がない。¶
• データは I-JSON [RFC7493] サブセットに 制約される。これにより、正準化を扱うための特定のパーサーが不要になる。¶
• JSON プリミティブの JCS 互換シリアル化は、現在、 ほとんどの Web ブラウザーおよび Node.js [NODEJS] によってサポートされている。¶
• JCS 仕様全体は、現在、複数のオープンソース実装によって サポートされている（Appendix G を参照）。 実装ガイドラインについては Appendix F も参照。¶

JCS は、JSON Web Key (JWK) Thumbprint [RFC7638] や Keybase [KEYBASE] など、JSON 正準化に依存する 既存のいくつかのシステムと互換性がある。¶

暗号以外での潜在的な用途については、[JSONCOMP] を参照。¶

本文書の想定読者は、JSON ツールベンダー、および JSON ベースの 暗号ソリューションの設計者である。読者は、"JSON" オブジェクトを含む ECMAScript について知識を持っているものと想定される。¶

2. 用語

本文書は IETF standards track 上の文書ではないことに注意。 しかし、適合実装は、セキュリティおよび相互運用性の理由から、 指定された動作に従うものとされる。このテキストでは、 その必要な動作を記述するために BCP 14 を使用する。¶

本文書におけるキーワード "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", および "OPTIONAL" は、 ここに示されるようにすべて大文字で現れる場合に限り、 BCP 14 [RFC2119] [RFC8174] に記述されているとおりに 解釈されるものとする。¶

3. 詳細な動作

このセクションでは、正準 JSON 表現の作成に関連する詳細と、 それらが JCS によってどのように対処されるかについて記述する。¶

Appendix 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 が Appendix F に記述されるような 署名スキームに適用される場合、アプリケーションは受信データに基づいて 動作する前に、次の操作を実行しなければならない（MUST）。¶

1. JSON データを解析し、それが I-JSON に従っていることを検証する。¶
2. それが使用されるエコシステムによって定義された規約に従い、 データの正しさを検証する。これには、署名データを保持する プロパティを特定することも含まれる。¶
3. 署名を検証する。¶

これらの手順のいずれかが失敗した場合、進行中の操作は 中止されなければならない（MUST）。¶

Appendix 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 += '}';
          }
      }
  };

Appendix B. 数値シリアル化 サンプル

次の表は、いくつかの境界ケースを含む、 ECMAScript 互換の数値シリアル化サンプルの集合を収めている。 "IEEE 754" 列は、"Number" データ型の内部 ECMAScript 表現を指し、 これは IEEE 754 [IEEE754] 標準に基づく 64 ビット（二倍精度）値であり、ここでは 16 進数で表されている。¶

注:¶

(1)

ECMAScript の "JSON" オブジェクトとの最大限の適合性のため、 真の整数として解釈される値は、-9007199254740991 から 9007199254740991 の範囲内にあるべきである（SHOULD）。 ただし、アプリケーションで数値がどのように使用されるかは JCS アルゴリズムに影響しない。¶

(2)

2**68 のような特定の整数の集合は拡張精度を持つものと みなせる場合があるが、JCS/ECMAScript 数値シリアル化アルゴリズムは これを考慮しない。¶

(3)

範囲外の値は JSON では許可されない。 Section 3.2.2.3 を参照。¶

(4)

この数値は正確には 1424953923781206.25 であるが、 Section 3.2.2.3 で言及されている "Note 2" 規則の後、切り詰められ、最も近い偶数値に丸められる。¶

JCS 数値シリアライザーをより徹底的に検証するには、 開発ポータル（Appendix I を参照）で （現在）利用可能な、多数のサンプル値を含むファイルに対して テストできる。別の選択肢は、V8 [V8] をライブ参照として使用し、 大量のランダムな IEEE 754 値を生成するプログラムと一緒に実行することである。¶

Appendix C. "Wire Format" としての正準化 JSON

正準化処理（Section 3.2.4 を参照）の結果は完全に有効な JSON であるため、 "Wire Format" としても使用できる。ただし、これは単なる選択肢である。 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 データを 1 行のテキストにも 変換するため、デバッグやロギングにはあまり理想的ではない場合がある。¶

Appendix D. 大きな数値の扱い

JSON 数値型にはいくつかの問題があり、ここでは次のサンプルオブジェクトで 例示する。¶

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

上記のサンプルは JSON [RFC8259] に 適合しているが、アプリケーションは通常、 "giantNumber" と "int64Max" を格納するために異なるネイティブデータ型を使用する。 さらに、"payMeThis" のような金銭データは、十進演算に関する丸め問題のため、 おそらく浮動小数点データ型には依存しない。¶

この種の JSON 数値型の「多重利用」を扱う確立された方法 （少なくとも拡張可能な方法）は、マッピング機構を通じて、 名前に基づいて異なるプロパティをどう扱うかをパーサーに指示することである。 しかし、これは本来の、いくらか制約された JavaScript 文脈の外で JSON 数値型を使用する価値を大きく制限する。 ECMAScript の "JSON" オブジェクトも、JSON 数値型へのマッピングをサポートしない。¶

上記の理由により、現在の JSON エコシステムに自然な位置を持たない数値は、 JSON 文字列型を使用してラップされなければならない（MUST）。 これはオープンシステムにおける事実上の標準に近い。これは、 Appendix E に記述される "DateTime" オブジェクトのように、JSON で直接サポートされない他のデータ型にも適用される。¶

JSON 文字列型を使用するシステムの助けを借りれば、次のようなプログラム的な方法であれ¶

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

OpenAPI [OPENAPI] のような宣言的スキームであれ、 JCS は、ECMAScript を使用する場合を含め、アプリケーションに制限を課さない。¶

Appendix E. 文字列サブタイプの扱い

JSON に備わるデータ型の集合が限られているため、JSON 文字列型は サブタイプを保持するために一般的に使用される。これは JSON の解析方法によっては 相互運用性の問題につながる可能性があり、より広い読者層を対象とする JCS 適合アプリケーションでは対処されなければならない（MUST）。¶

スキーマ設計者が "BigInt" サブタイプを保持するためのプロパティとして "big" を割り当て、"DateTime" サブタイプを保持するためのプロパティとして "time" を割り当て、一方で "val" は JCS に適合する JSON 数値であると 想定される 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] によってのみ ネイティブにサポートされていることに注意。¶

Appendix 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
  );

ここで Appendix A の正準化器を "object" に適用すると、次の文字列が生成される。¶

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

この場合、"big" および "time" の文字列引数は元のものから変化しており、 JCS に依存するアプリケーションが失敗する原因になると考えられる。¶

逸脱の理由は、ストリームベースおよびスキーマベースの JSON パーサーでは、 元の文字列引数が通常、その場でネイティブサブタイプに置き換えられ、 それがシリアル化されると、異なる、かつプラットフォーム依存のパターンを 示す可能性があるためである。¶

すなわち、ストリームベースおよびスキーマベースの解析は、 サブタイプを「純粋な」（不変の）JSON 文字列型として扱い、 実際の指定されたネイティブ型への変換を後続の手順で行わなければならない （MUST）。Go、Java、および C# のような現代の プログラミングプラットフォームでは、アノテーション、ゲッター、および セッターを組み合わせることで、適度な労力でこれを実現できる。 以下は、JSON オブジェクトとしてシリアル化可能なクラスの一部を示す C#/Json.NET の例である。¶

  // 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 二倍精度と比較してかなり異なる特性を持つ）。¶

Appendix F. 実装ガイドライン

最適な解決策は、JCS のサポートを JSON シリアライザーに直接統合することである （パーサーに変更は不要である）。 すなわち、正準化は JSON シリアライザーの追加の "mode" にすぎなくなる。 しかし、現時点ではこれは当てはまらない。幸い、JCS サポートは、 既存の JSON シリアライザーに対するポストプロセッサとして動作する、 外部から提供される正準化器ソフトウェアを通じて導入できる。 この構成はまた、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 シリアライザーを使用すると、 両方の処理において、正準化手順の前に行われるシリアル化を 省略できる。¶

Appendix 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>¶

Appendix 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-to-JSON 変換を 基盤としている。テキストレベル正準化の主な特徴は、 使用される JSON の種類に対して中立にできることである。 しかし、そのようなスキームは JSON 解析処理への大きな変更も意味し、 これは採用への障害となる可能性が高い。特定の JSON および アプリケーション制約を代償としつつも、JCS は既存の JSON ツールと 互換性を持つように設計された。¶

Appendix 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 が提供した 数値シリアル化のためのソフトウェアとサポートは非常に有用であった。¶

著者の連絡先