仕様書

[7] RFC 7515 - JSON Web Signature (JWS), 2019-11-24 17:13:01 +09:00 https://tools.ietf.org/html/rfc7515

データモデル

[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 計算への入力です。この値は、

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

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

[62] alg や enc は耐衝突名かつ 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

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

JWS JSON直列化

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

[30] JWS JSON直列化では、 JWS保護ヘッダーとJWS非保護ヘッダーの両方を使うことができます >>8, >>22。どちらか一方は存在しなければなりません >>22。 JOSEヘッダーは両者全体で構成されます >>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 値の作成や検証に使うヘッダー引数は、 protected と header を合同して得られる 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 値の作成や検証に使うヘッダー引数は、 protected と header を合同して得られる JOSEヘッダーです。両者のヘッダー引数の名前は、互いに素でなければなりません。 >>31

処理

作成

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

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

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

検証

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

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

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

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

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

アルゴリズムと鍵

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

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

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

[15] JOSE鍵識別