JWS Compact Serialization

JWS

[14] JWS は、 電子署名のための JSON応用です。

仕様書

データモデル

[9] JSON Web Signature (JWS) は、 デジタル的に RFC 4949 署名されまたは RFC 4949 MAC されたメッセージです。 >>8, >>22

[21] JWS には、一貫性保護のない非保安JWSも含まれます。

[24] JWS は、次により構成されます。 >>22

[25] JWS
JOSEヘッダー
次の合同です。
JWS被保護ヘッダー (JWS Protected Header)
JWS署名RFC 4949 デジタル署名または RFC 4949 MAC演算によって一貫性保護されたヘッダー引数を含む JSONオブジェクトです。 >>8
JWS非被保護ヘッダー (JWS Unprotected Header)
一貫性保護されていないヘッダー引数を含む JSONオブジェクトです。 >>8
JWSペイロード
JWS署名

[13] JOSEヘッダーには、 JWS 用のヘッダー引数をいくつか指定できます。 ヘッダー引数は名前と値の組です。 JOSEヘッダー

[10] JOSEヘッダー内のヘッダー引数の重複は認められません。 JOSEヘッダー JWS被保護ヘッダーJWS非被保護ヘッダーの間でも同名があってはなりません (>>43, >>46)。

構文

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

[11] JWSペイロード (JWS Payload) は、 保安される (secured) オクテット列すなわち (aka) メッセージ (message) です。 ペイロードは、 任意のオクテット列を含められます。 >>8

[12] JWS署名 (JWS Signature) は、 JWS保護ヘッダーJWSペイロードに関する RFC 4949 デジタル署名RFC 4949 MAC です。 >>8

[16] JWS署名入力 (JWS Signing Input) は、 RFC 4949 デジタル署名または RFC 4949 MAC 計算への入力です。 この値は、

  1. RFC 20 ASCII (RFC 7515 BASE64URL (RFC 3629 UTF8 (JWS保護ヘッダー)))
  2. .
  3. RFC 7515 BASE64URL (JWSペイロード)

... を順に連結した結果です。 >>8

[20] StringOrURI は、 JSON文字列値であって、 任意の文字列値であっても構わないものの、 : が含まれる場合は RFC 3986 URI でなければならないものです。 比較は、 大文字・小文字区別ありで変形や正準化なく行います。 >>8

[62] algenc耐衝突名かつ StringOrURI (を含む文字列) とされています。


[173] JWS のうち JWSペイロードを含めない、 つまり JWS 生成後に JWS簡潔直列化にあっては該当部分を空文字列とし、 JWS JSON直列化にあっては payload を削除したものを扱うのが時に有用なのであって、 受信者も別の手段で JWSペイロード相当の情報を入手し、 容易に JWS を再構築し得るものである、 と仕様書に敢えて言及があります >>172

[174] しかしなぜか本体仕様とは別に簡単に説明されているに過ぎず、 しかも送受信者がそのような簡単な操作で標準的な JWS のライブラリーの入出力を改変して実現可能だ、 と JWS 本体ではなく応用側で実装するべきものとしています。 本当にそのような需要があるのなら、 こうした取ってつけた説明ではなく JWS 本体仕様に組み込んで詳細に規定するべきで、不可解です。

直列化

[27] JWS は、 3種類の表現方法があります。 JWS を使う応用は、 どちらの直列化を使うか、 どの直列化機能 (feature) を使うかを、 規定する必要があります。 JWS の実装は、 対応したい応用で必要な機能のみ実装する必要があります。 >>31

[33] 例えば、 「JWS JSON直列化で署名か MAC の値は1つだけ対応する」 のような定めが可能です。 >>31

[26] そのためただ「JWS を使う」「JWS に対応」とだけ言っても意味は通じません。 2つの 「JWS に対応」した実装が相互運用可能とは限りません。

[32] JWE との区別は JOSE 参照。

JWS簡潔直列化

[17] JWS簡潔直列化 (JWS Compact Serialization) は、 JWS を簡潔で URL安全文字列として表現したものです。 >>8

[28] JWS簡潔直列化では、 JWS非保護ヘッダーを使うことが出来ません。 JOSEヘッダー = JWS保護ヘッダーです。 >>8, >>22

[29] JWS簡潔直列化は、 次のものを順に連結したものです。 >>22, >>31

  1. RFC 7515 BASE64URL (RFC 3629 UTF8 (JWS保護ヘッダー))
  2. .
  3. RFC 7515 BASE64URL (JWSペイロード)
  4. .
  5. RFC 7515 BASE64URL (JWS署名)

[34] 署名MAC は1つだけしか指定できません。 >>31

JWS JSON直列化

[18] JWS JSON直列化 (JWS JSON Serialization) は、 JWSJSONオブジェクトとして表現したものです。 JWS簡潔直列化と違って、 複数の RFC 4949 デジタル署名RFC 4949 MAC一方又は両方を同じ内容に適用できます。 簡潔性や URL安全性は重視していません。 >>8

[30] JWS JSON直列化では、 JWS保護ヘッダーJWS非保護ヘッダーの両方を使うことができます >>8, >>22。 どちらか一方は存在しなければなりません >>22JOSEヘッダーは両者全体で構成されます >>8, >>22

[35] 一般構文と呼ばれるものと、平坦化構文と呼ばれるものの2種類があります。 >>31

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

一般構文

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

[38] JSONオブジェクト
payload
RFC 7516 BASE64URL (JWSペイロード)。 必須>>31
signatures
JSONオブジェクト配列でなければなりません
[40] JSON配列

[41]JSONオブジェクトは、 JWSペイロードJWS保護ヘッダー署名MAC を表します。 >>31

[39] JSONオブジェクト
protected
JWS保護ヘッダー値が空でない時、 RFC 7515 BASE64URL (RFC 3629 UTF8 (JWS保護ヘッダー)) でなければなりませんヘッダー引数値は一貫性保護されます。 そうでないとき、 省略しなければなりません>>31
header
JWS非保護ヘッダー値が空でない時、 JWS非保護ヘッダーたる JSON 値でなければなりませんヘッダー引数値は一貫性保護されません。 そうでないとき、 省略しなければなりません>>31
signature
RFC 5715 BASE64URL (JWS署名) でなければなりません>>31
その他
他のメンバーを指定できます。 実装は、理解できないものを無視しなければなりません>>31

[42] protected または header の一方または両方がなければなりません。 最低でも alg ヘッダー引数が必要です。 >>31

[43] 署名MAC 値の作成や検証に使うヘッダー引数は、 protectedheader合同して得られる JOSEヘッダーです。 両者のヘッダー引数の名前は、互いに素でなければなりません>>31

その他
他のメンバーを指定できます。 実装は、理解できないものを無視しなければなりません>>31 (protected, header, signature も禁止はされていません。)

平坦化構文

[37] 平滑化JWS JSON直列化構文 (flattened JWS JSON serialization syntax) は、 単一のデジタル署名MAC の場合に最適化したもので、 次のような最上位 JSONオブジェクトです。 >>31

[44] JSONオブジェクト
payload
RFC 7516 BASE64URL (JWSペイロード)。 必須>>31
protected
JWS保護ヘッダー値が空でない時、 RFC 7515 BASE64URL (RFC 3629 UTF8 (JWS保護ヘッダー)) でなければなりませんヘッダー引数値は一貫性保護されます。 そうでないとき、 省略しなければなりません>>31
header
JWS非保護ヘッダー値が空でない時、 JWS非保護ヘッダーたる JSON 値でなければなりませんヘッダー引数値は一貫性保護されません。 そうでないとき、 省略しなければなりません>>31
signature
RFC 5715 BASE64URL (JWS署名) でなければなりません>>31
その他
他のメンバーを指定できます。 実装は、理解できないものを無視しなければなりませんsignatures があってはなりません>>31

[45] protected または header の一方または両方がなければなりません。 最低でも alg ヘッダー引数が必要です。 >>31

[46] 署名MAC 値の作成や検証に使うヘッダー引数は、 protectedheader合同して得られる JOSEヘッダーです。 両者のヘッダー引数の名前は、互いに素でなければなりません>>31

処理

作成

[82] JWSを作成 (create a JWS) するには、 JWSペイロードJSONオブジェクトまたは null JWS保護ヘッダーJSONオブジェクトまたは null JWS非保護ヘッダーを、 次のようにします。 >>81

  1. [87] Assert: JOSEヘッダー (JWS保護ヘッダーJWS非保護ヘッダー) には alg ヘッダー引数が含まれなければなりません
  2. [83] 符号化ペイロード値を、 RFC 7515 BASE64URL (JWSペイロード) の結果に設定します。
  3. [84] 符号化ヘッダー値を、空文字列に設定します。
  4. [85] 符号化ヘッダー値nullない場合、
    1. [86] RFC 7515 BASE64URL (RFC 3629 UTF8 (JWS保護ヘッダー)) の結果に設定します。
  5. [88] JWS署名を、JWS署名を計算した結果に設定します。
    JWS署名入力
    RFC 20 ASCII (符号化ヘッダー値)、 .符号化ペイロード値順に連結した結果
    JOSEヘッダー
    JWS保護ヘッダーJWS非保護ヘッダー
  6. [89] 符号化署名値を、 RFC 7515 BASE64URL (JWS署名) の結果に設定します。
  7. [90] 符号化保護ヘッダーJWS非保護ヘッダー符号化ペイロード値符号化署名値について、 直列化した結果を返します。

[128] BOM を生成するべきか否か仕様書から明らかではありません。一般的には Encoding StandardUTF-8符号化のように BOM を生成しないものと解されています。

検証

[91] JWS検証 (validate) するには、 JWS を、 次のようにします。 >>81

  1. [92] 結果を、 JWS を構文解析した結果に設定します。
  2. [93] 結果失敗の場合、
    1. [94] を返し、ここで停止します。
  3. [95] ヘッダーバイト列を、 結果符号化ヘッダー値RFC 7515 base64url復号した結果に設定します。
  4. [96] ヘッダーバイト列失敗の場合、
    1. [97] を返し、ここで停止します。
  5. [99] ヘッダー文字列を、 ヘッダーバイト列RFC 3629 UTF-8 復号した結果に設定します。
  6. [100] ヘッダー文字列失敗の場合、
    1. [101] を返し、ここで停止します。
  7. [98] JWS保護ヘッダーを、 ヘッダー文字列RFC 7159 JSON として構文解析した結果に設定します。
  8. [102] JWS保護ヘッダーJSONオブジェクトない場合、
    1. [103] を返し、ここで停止します。
  9. [104] 結果JWS非保護ヘッダーnullない場合、
    1. [105] 結果JWS非保護ヘッダーのメンバーとJWS保護ヘッダーのメンバーについて、 メンバー名 (= ヘッダー引数名) に重複がある場合、
      1. [106] を返し、ここで停止します。
  10. [107] 結果JWS保護ヘッダーJWS保護ヘッダーについて、 JWS の規定により対応しなければならないとされるもの、 指定されたアルゴリズムにより対応しなければならないとされるもの、 crit ヘッダー引数で指定されたものについて、 実装が理解し処理できるヘッダー引数であること、 その値もまた理解し処理できるものであることを確認します。そうでない場合、
    1. [108] を返し、ここで停止します。
  11. [109] ペイロードバイト列を、 結果符号化ペイロード値RFC 7515 base64url復号した結果に設定します。
  12. [110] ペイロードバイト列失敗の場合、
    1. [111] を返し、ここで停止します。
  13. [112] 署名バイト列を、 結果符号化署名値RFC 7515 base64url復号した結果に設定します。
  14. [113] 署名バイト列失敗の場合、
    1. [114] を返し、ここで停止します。
  15. [115] JWS署名を、JWS署名を計算した結果に設定します。
    JWS署名入力
    RFC 20 ASCII (結果符号化ヘッダー値)、 .結果符号化ペイロード値順に連結した結果
    JOSEヘッダー
    JWS保護ヘッダー結果JWS非保護ヘッダー
  16. [116] 署名バイト列JWS署名ない場合、
    1. [117] を返し、ここで停止します。
  17. [119] ペイロード文字列を、 ペイロードバイト列RFC 3629 UTF-8 復号した結果に設定します。
  18. [120] ペイロード文字列失敗の場合、
    1. [121] を返し、ここで停止します。 仕様書になし
  19. [122] JWSペイロードを、 ペイロード文字列RFC 7159 JSONとして構文解析した結果に設定します。
  20. [123] JWSペイロードJSONオブジェクトない場合、
    1. [124] を返し、ここで停止します。 仕様書になし
  21. [118] JWS保護ヘッダー結果JWS非保護ヘッダーJWSペイロードを返します。

[125] JWS署名が複数含まれる時、 どれを検証するか、すべてを検証するかは応用が決めることとされています。 最低でも1つは検証しを返すことを確認しなければなりません>>81

[126] 検証結果がであっても、 アルゴリズム応用の期待するものでなければ、 非妥当とみなすべきです>>81

[127] UTF-8JSON復号について、参照している仕様が明確に方法を定めていないため、 相互運用性の問題が生じるおそれがあります。仕様書の厳密な解釈に従うことは避け、 明確な規定のある Encoding Standard BOMなしUTF-8復号または失敗ECMAScript JSON.stringify に倣うべきでしょう。

アルゴリズムと鍵

[134] JWS署名の計算に使われるアルゴリズムは、 alg ヘッダー引数に指定することになっています。 生成器は、これを指定しなければなりませんalg の値が受信器対応しているアルゴリズムでないとき、 妥当ではありません >>47検証失敗します。

[135] つまり、相互運用性のため、 応用は送受信者が対応しなければならないアルゴリズムを明確かつ限定的に規定しなければなりません。

[149] アルゴリズムの実装によってはJWS署名値内に含まれるアルゴリズムを使って検証する場合があります。 その場合でもそれが alg と一致しているか確認しなければなりません。 さもなくば alg に強いアルゴリズムを指定し、 実際には弱いアルゴリズムで攻撃することが可能となってしまいます。 >>148

[15] JOSE鍵識別

MIME 型

JOSE

応用

[6] JWS応用

[49] JAdES

関連

[19] 関連記事: JOSE, JWE

歴史

[1] JSON Web Signature (JWS) ( ( 版)) http://openid.net/specs/draft-jones-json-web-signature-04.html

[2] draft-ietf-jose-json-web-signature-19 - JSON Web Signature (JWS) ( ( 版)) http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-19

[3] IETF 提案標準 RFC 7515 として出版されました。

[4] RFC 7797 - JSON Web Signature (JWS) Unencoded Payload Option ( 版) https://tools.ietf.org/html/rfc7797

[5] RFC 8055 - Session Initiation Protocol (SIP) Via Header Field Parameter to Indicate Received Realm () https://tools.ietf.org/html/rfc8055