JWE JSON直列化

Edit New

JWE

[5] JWE (JSON Web Encryption) は、 暗号化したデータを交換できる JSON応用です。

[6] JWS 等で構成される JOSE 規格シリーズの1つです。

仕様書

暗号化

[16] JWA を使います。

[9] JWE の暗号化用語

データモデル

[8] JSON Web Encryption (JWE) は、 暗号化され一貫性保護されたメッセージを表現するデータ構造です。 >>7

[18] 1つの JWE は、 次により構成されます。 >>17

[19] JWE
JOSEヘッダー
次の合同です。
JWE被保護ヘッダー (JWE Protected Header)
被認証暗号化操作によって一貫性保護されたヘッダー引数群を含む JSONオブジェクトです。 当該ヘッダー引数群は、 JWE のすべての受信者に適用されます。 JWE簡潔直列化においては、 JOSEヘッダー全体で構成されます。 JWE JSON直列化においては、 JOSEヘッダーの構成要素の1つです。 >>7
JWE被共有非被保護ヘッダー
JWE のすべての受信者に適用されるヘッダー引数群であって一貫性保護されないものを含む JSONオブジェクトです。 JWE JSON直列化にのみ出現できます。 >>7
JWE受信者毎非被保護ヘッダー (JWE Per-Recipient Unprotected Header)
JWE の単独の受信者に適用されるヘッダー引数群を含む JSONオブジェクトです。 当該ヘッダー引数群は一貫性保護されません。 JWE JSON直列化にのみ出現できます。 >>7
JWE被暗号化鍵
JWE初期化ベクトル
JWE AAD
JWE暗号文
JWE認証タグ

[10] 平文の機密性と一貫性、 並びにJWE被保護ヘッダーと JWE AAD の一貫性を保証するため、 被認証暗号化を使います。 >>17

[145] 追加被認証データ (Additional Authenticated Data) (AAD) は、 AEAD 操作への入力であって、 整合性保護されるものの、 暗号化はされないものです。 >>7

[146] JWE AAD は、 被認証暗号化操作で一貫性保護される追加の値です。 JWE JSON直列化でのみ出現し得ます。 >>7

[147] JWE には応用データとして平文を暗号化した暗号文の他に、 AAD を含めることができます。 平文の方は暗号化されているので傍受しても解読できませんが、 AAD は base64url 符号化されているだけなので、 傍受すると読まれてしまいます。 しかし一貫性保護の対称になっていますから、 AAD を改竄すると検知できます。

[148] 従って漏洩しても構わない、 解読前でも確認したいような、 しかし改竄されるとまずいデータを入れる場所として使うことができます。 JWE被保護ヘッダーも同条件ですが、 そちらは JWE としてのプロトコル要素です。 対して AAD は完全に応用が好きに使える場所となっているようです。

[149] というような説明がなぜか JWE の RFC で明確には行われていないのですが。

[143] RFC 7520 - Examples of Protecting Content Using JSON Object Signing and Encryption (JOSE), https://datatracker.ietf.org/doc/html/rfc7520#section-5.10

[144] >>143 AAD として vCard を入れた例が示されています。 どういう利用形態を想定して vCard を使った事例なのかは書かれていません。

直列化

[124] JWE には3種類の直列化があります。 応用はそのいずれを使うか、 そのどの機能を使うかを指定する必要があります。 JWE の実装は、その対象とする応用が必要とする機能のみ対応する必要があります。 >>123

[125] つまり「JWE を使う」というだけでは意味が通じません。 「JWE を実装した」とするものが JWE のすべての機能を使えるとも限りません。

[20] JWE は、 RFC 7159 JSON データや base64url を使って記述されます。 JSON は、その定めるところにより、 値の前後に空白を挿入できます。 JSON >>17

[139] JWS との区別は JOSE 参照。

JWE 簡潔直列化

[14] JWE簡潔直列化 (JWE Compact Serialization) は、 JWE の簡潔で URL安全な文字列としての表現です。 >>7

[13] JWE簡潔直列化は、 次のものを順に連結したものです。 >>17, >>123

  1. [21] RFC 7515 BASE64URL (RFC 3629 UTF8 (JWE被保護ヘッダー))
  2. [22] .
  3. [23] RFC 7515 BASE64URL (JWE被暗号化鍵)
  4. [24] .
  5. [25] RFC 7515 BASE64URL (JWE初期化ベクトル)
  6. [26] .
  7. [27] RFC 7515 BASE64URL (JWE暗号文)
  8. [28] .
  9. [29] RFC 7515 BASE64URL (JWE認証タグ)

[11] JWE簡潔直列化では、 JWE共有非被保護ヘッダーや JWE受信者毎非被保護ヘッダーは、 利用できません。 >>7, >>17, >>123

[12] 従ってJOSEヘッダー = JWE被保護ヘッダーです。 >>17

[126] JWE簡潔直列化では、 JWE AAD は使えません。 >>123

[127] JWE簡潔直列化では、受信者は常に1つです。 >>123

JWE JSON 直列化

[15] JWE JSON直列化 (JWE JSON Serialization) は、 JWE の JSONオブジェクトとしての直列化です。 JWE JSON直列化では複数の当事者 (parties) に対して同じ内容を暗号化できます。 >>7

[30] JWE JSON直列化では、 JWE被保護ヘッダー、 JWE共有非被保護ヘッダー、 JWE受信者毎非被保護ヘッダーのうち 1つ以上は必須です。 >>17

[150] ヘッダー引数と違って明言されていませんが、 JSONオブジェクトの重複メンバーは ヘッダー引数の重複と同様に処理するべきと思われます。 ヘッダー引数

一般構文

[128] (完全)一般JWE JSON直列化構文 ((fully) general JWE JSON serialization syntax) は、 次のような最上位の JSONオブジェクトです。 >>123

[129] JSONオブジェクト
protected
JWE被保護ヘッダーが空でない場合、 RFC 7515 BASE64URL (RFC 3629 UTF8 (JWE被保護ヘッダー)) でなければなりません。 すべての受信者に共有されます。 そうでない場合、 指定してはなりません。 >>123
unprotected
JWE共有非被保護ヘッダーが空でない場合、 JWE共有非被保護ヘッダーでなければなりません。 すべての受信者に共有されます。 そうでない場合、 指定してはなりません。 >>123
iv
JWE初期化ベクトルが空でない場合、 RFC 7515 BASE64URL (JWE初期化ベクトル) でなければなりません。 そうでない場合、 指定してはなりません。 >>123
aad
JWE AAD が空でない場合、 RFC 7515 BASE64URL (JWE AAD) でなければなりません。 そうでない場合、 指定してはなりません。 >>123
ciphertext
RFC 7515 BASE64URL (JWE暗号文) でなければなりません。 >>123
tag
JWE認証タグが空でない場合、 RFC 7515 BASE64URL (JWE認証タグ) でなければなりません。 そうでない場合、 指定してはなりません。 >>123
recipients
JSON配列でなければなりません。 >>123
[130] JSON配列

[131] 各JSONオブジェクトは、 特定の受信者に固有の情報を表します。 >>123

[132] JSONオブジェクト
header
JWE受信者毎非被保護ヘッダーが空でない場合、 JWE受信者毎非被保護ヘッダーでなければなりません。 そうでない場合、 指定してはなりません。 >>123
encrypted_key
JWE被暗号化鍵が空でない場合、 RFC 7515 BASE64URL (JWE被暗号化鍵) でなければなりません。 そうでない場合、 指定してはなりません。 >>123

[133] 各受信者に対してヘッダー引数 alg と enc が必須であり、従って各受信者に対して header, protected, unprotected の最低でも1つは必須です。 >>123

[134] protected 以外は一貫性保護されないことには注意。

[136] 平文値の取り扱いを指定するすべてのヘッダー引数は、 すべての受信者について同じでなければなりません。 主として enc ヘッダー引数と、 その指定された算法に関するヘッダー引数が該当します。 これはJWE暗号文等がすべての受信者に対して共通であることからの帰結とされます。 >>123

[137] しかしそれを protected に入れなければならないという制約はなく、 すべてを header 内に入れても構わないようです。 しかし recipients 内のオブジェクトすべてで同じ値でなければならないということです。

[135] 内側、外側のどちらのJSONオブジェクトにも、 これ以外の追加のメンバーを指定できます。 実装は、理解できないメンバーを無視しなければなりません。 >>123

平坦化構文

[31] 平滑化JWE JSON直列化構文 (flattened JWE JSON serialization syntax) は、 単一の受信者の場合に最適化したもので、 次のような最上位 JSONオブジェクトです。 >>123, >>17

[32] JSONオブジェクト
protected
RFC 7515 BASE64URL (RFC 3629 UTF8 (JWE被保護ヘッダー))
unprotected
JWE共有非被保護ヘッダー
header
JWE受信者毎非被保護ヘッダー
encrypted_key
RFC 7515 BASE64URL (JWE被暗号化鍵)
iv
RFC 7515 BASE64URL (JWE初期化ベクトル)
ciphertext
RFC 7515 BASE64URL (JWE暗号文)
tag
RFC 7515 BASE64URL (JWE認証タグ)
aad
RFC 7515 BASE64URL (JWE AAD)

[138] 平坦化JWE JSON直列化構文は、 一般JWE JSON直列化構文の recipients を展開したものという形で規定されています。 >>123 明言されていませんが、 ここに規定されていない他の (recipients 以外の) メンバーを指定することもまた認められると思われます。

処理

暗号化

[34] メッセージの暗号化は、次のようにします。 >>33

  1. [53] 受信者リスト中の各受信者受信者について、 順に、
    1. [35] 算法を、 alg で指定された算法 (CEK 値の決定に使う算法) に設定します。
    2. [36] 鍵管理モードを、 算法により鍵管理モードを決定した結果に設定します。
    3. [37] 鍵管理モードが鍵包み、 鍵暗号化、 鍵包み付き鍵合意の場合、
      1. [38] 無作為に CEK 値を生成します。 無作為値の生成については RFC 4086 を参照。 CEK は、 内容暗号化算法が要求する長さと等しくなければなりません。
    4. [39] 鍵管理モードが直接鍵合意、 鍵包み付き鍵合意の場合、
      1. [40] 合意された鍵 (agreed upon key) を計算すべく鍵合意算法を実行します。
      2. [41] 鍵管理モードが直接鍵合意の場合、
        1. [42] CEK を得られた値に設定します。
      3. [43] 鍵管理モードが鍵包み付き鍵合意の場合、
        1. [44] 得られた値は CEK を包むのに使われます。
    5. [45] 鍵管理モードが鍵包み、 鍵暗号化、 鍵包み付き鍵合意の場合、
      1. [46] JWE被暗号化鍵を、 CEK を受信者に対して暗号化した結果に設定します。
    6. [47] 鍵管理モードが直接鍵合意, 直接暗号化の場合、
      1. [48] JWE被暗号化鍵を、 空オクテット列に設定します。
    7. [49] 鍵管理モードが直接暗号化の場合、
      1. [50] CEK を共有対称鍵に設定します。
  2. [54] JWE初期化ベクトルを、空オクテット列に設定します。
  3. [55] 内容暗号化算法が初期化ベクトルを必要とする場合、
    1. [56] JWE初期化ベクトルを、 内容暗号化算法で適切な大きさの無作為の JWE初期化ベクトルを生成した結果に設定します。
  4. [58] zip が指定されている場合、
    1. [59] Mを、平文を zip で指定された算法で圧縮した結果に設定します。
  5. [62] それ以外の場合、
    1. [63] M を、平文に設定します。
  6. [61] 必要な場合、
    1. [69] JWE被保護ヘッダーを、 適切なヘッダー引数を含んだJOSEヘッダーに設定します。
    2. [64] 符号化被保護ヘッダーの値を、 RFC 7515 BASE64URL (RFC 3629 UTF8 (JWE被保護ヘッダー)) を計算した結果に設定します。
  7. [70] それ以外の場合、
    1. [71] 符号化被保護ヘッダーの値を、 空文字列に設定します。
  8. [65] 必要な場合、
    1. [67] JWE被共有非被保護ヘッダーを、 適切なヘッダー引数を含んだJOSEヘッダーに設定します。
  9. [66] 必要な場合、
    1. [68] JWE受信者毎非被保護ヘッダーを、 適切なヘッダー引数を含んだJOSEヘッダーに設定します。
  10. [72] JWE AAD がある場合、
    1. [75] 値を、 次の文字列を順に連結した結果に設定します。
  11. [76] それ以外の場合、
    1. [77] 値を、 符号化被保護ヘッダーに設定します。
  12. [73] AAD暗号化引数を、 値を RFC 20 ASCII で符号化した結果に設定します。
  13. [74] JWE暗号文とJWE認証タグを、 M, CEK, JWK初期化ベクトル, AAD暗号化引数について、 指定された内容暗号化算法で暗号化した結果に設定します。
  14. [82] ここまでで得られた値を使って直列化します。
[83] 仕様書には簡単なアルゴリズムの形で求められる挙動が書かれていますが、 現代的な Web標準の仕様書などで使われている記述方式に比べると曖昧で行間を読まなければならない前近代的なものです。

[122] JOSE鍵識別も参照。

解読

[51] メッセージの解読は、次のようにします。 >>33

  1. [79] 直列化された JWE を構文解析します。
  2. [80] JWE被保護ヘッダー, JWE被暗号化鍵, JWE初期化ベクトル, JWE暗号文, JWE認証タグ, JWE AAD を base64url 改行・空白・その他追加文字なしで復号します。
  3. [81] JWE被保護ヘッダーが妥当な RFC 7159 JSONオブジェクトを UTF-8 符号化したものであることを検証します。
  4. [107] 直列化された表現に含まれる各受信者について、 順に、
    1. [84] 直列化が JWE簡潔直列化の場合、
      1. [85] JOSEヘッダーを、 JWE被保護ヘッダーに設定します。
    2. [86] それ以外の場合、
      1. [87] JOSEヘッダーを、 JWE被保護ヘッダー, JWE被共有非被保護ヘッダー, 対応する (corresponding) JWE受信者毎非被保護ヘッダーの合同とします。 このとき、
    3. [90] 仕様書、算法、 crit ヘッダー引数が要求するすべての欄を実装が理解、 処理できること、並びにそれらヘッダー引数の値が理解でき対応できることを検証します。
    4. [91] 鍵管理モードを、 alg ヘッダー引数に指定された算法により決定した鍵管理モードに設定します。
    5. [92] JWE が受信者の知っている鍵を使っていることを検証します。
    6. [93] 鍵管理モードが直接鍵合意、 鍵包み付き鍵合意の場合、
      1. [94] 合意された鍵 (agreed upon key) を計算すべく鍵合意算法を実行します。
      2. [95] 鍵管理モードが直接鍵合意の場合、
        1. [96] CEK を得られた値に設定します。
      3. [97] 鍵管理モードが鍵包み付き鍵合意の場合、
        1. [98] 得られた値はJWE被暗号化鍵の解読に使われます。
    7. [99] 鍵管理モードが鍵包み、 鍵暗号化、 鍵包み付き鍵合意の場合、
      1. [100] CEK を、 JWE被暗号化鍵を解読した結果に設定します。 CEK は内容暗号化算法において必要な長さと等しくなければなりません。
    8. [101] 鍵管理モードが直接鍵合意, 直接暗号化の場合、
      1. [102] JWE被暗号化鍵が空オクテット列か検証します。
    9. [103] 鍵管理モードが直接暗号化の場合、
      1. [104] CEK を、共有された対称鍵に設定します。
    10. [105] CEK がこの受信者に対して決定成功したかを記録します。
  5. [108] JWE非被保護ヘッダーがない場合、
    1. [109] 符号化被保護ヘッダーの値を、 空文字列に設定します。
  6. [110] それ以外の場合、
    1. [106] 符号化被保護ヘッダーの値を、 RFC 7515 BASE64URL (RFC 3629 UTF8 (JWE被保護ヘッダー)) を計算した結果に設定します。
  7. [111] JWE AAD がある場合、
    1. [112] 値を、 次の文字列を順に連結した結果に設定します。
  8. [113] それ以外の場合、
    1. [114] 値を、 符号化被保護ヘッダーに設定します。
  9. [115] AAD暗号化引数を、 値を RFC 20 ASCII で符号化した結果に設定します。
  10. [116] 平文を、 JWE暗号文を CEK, JWK初期化ベクトル, AAD暗号化引数, JWE認証タグについて内容暗号化算法を適用した結果に設定します。 内容暗号化算法に基づきJWE認証タグを妥当性検証し、 不正確なら解読結果を返さずに拒絶します。
  11. [117] zip が指定された場合、
    1. [118] 平文を、平文を指定された圧縮算法で解読した結果に設定します。
  12. [119] 平文とどの受信者であるかを返します。
[120] 仕様書はアルゴリズムの形で記述していますが、 エラー処理をどうするべきかや複数の受信者をどう扱うのかをあまり明確には描き出していません。 常識的に行間を読むと、処理に失敗したらその受信者については解読失敗として次の受信者の処理に移る (受信者の決定以前の失敗なら全体を失敗とする) ということのようです。
[142] なお >>141 のような重要な規定が仕様書本文中のアルゴリズムには組み込まれていなかったりします。 他の各段階も既知のセキュリティー問題に十分な配慮が必要です。 「本体」とセキュリティーを分けて考える RFC の悪習です。 RFC を読みながら実装するときは要注意。

[57] 受信者が複数の場合、 すべての受信者に対して検証に成功しなければならないとしようが、 いずれか1つの受信者に対して検証に成功すれば良いとしようが、 応用の裁量で決められます。 どうするにせよ、 少なくても1つの受信者に対しては検証に成功していなければなりません。 そうでなければ非妥当としなければなりません。 >>33

[78] 特定の場面でどの算法を使うかは、 応用の裁量によります。 解読に成功したとしても、 応用が受理できる算法でなければ、 非妥当とするべきです。 >>33

[121] JOSE鍵識別も参照。

[141] RFC 3218 timing attack の対策のため、 被暗号化鍵の 形式 (format) エラー, 詰め (padding) エラー, 長さ (length) エラーを区別してはなりません。 形式が不適切 (improperly formatted) な鍵を受信した際は、 timing attack 対策のため、 無作為に生成した CEK に置き換えて次段階に進むことが強く推奨 (strongly recommended) されます。 >>140

MIME 型

JOSE

応用

[151] JWE の応用

歴史

[2] RFC 7516 は、 に IETF 標準化過程RFC (提案標準) として出版されました。 >>1

メモ

Updated: