メインコンテンツまでスキップ

4. JSON Web Key (JWK) Format (JWK フォーマット)

JWK は、暗号鍵 (Cryptographic Key) を表現する JSON オブジェクトです。オブジェクトのメンバーは、その値を含む鍵のプロパティを表現します。この JSON オブジェクトは、RFC 7159 [RFC7159] のセクション 2 に従って、任意の JSON 値または構造文字の前後に空白や改行を含むことができます (MAY)。本文書は、アルゴリズム固有ではなく、したがって多くの鍵に共通する鍵パラメータを定義します。

共通パラメータに加えて、各 JWK には鍵タイプ固有のメンバーがあります。これらのメンバーは鍵のパラメータを表現します。JSON Web Algorithms (JWA) [JWA] 仕様のセクション 6 は、複数種類の暗号鍵とそれらに関連するメンバーを定義しています。

JWK 内のメンバー名は必ず (MUST) 一意でなければなりません。JWK パーサーは、重複するメンバー名を持つ JWK を拒否するか (MUST)、ECMAScript 5.1 [ECMAScript] のセクション 15.12 (The JSON Object) で指定されているように、辞書的に最後の重複メンバー名のみを返す JSON パーサーを使用しなければなりません (MUST)。

JWK には追加のメンバーが存在することができます (MAY)。それらを理解しない実装がそれらに遭遇した場合は、必ず (MUST) 無視しなければなりません。異なる鍵タイプの鍵パラメータを表現するために使用されるメンバー名は、異なる必要はありません。新しいメンバー名は、セクション 8.1 で確立された IANA「JSON Web Key Parameters」レジストリに登録されるべきです (SHOULD)、または衝突耐性名 (Collision-Resistant Name) を含む値であるべきです。

4.1. "kty" (Key Type) Parameter (鍵タイプパラメータ)​

「kty」(key type、鍵タイプ) パラメータは、鍵と共に使用される暗号アルゴリズムファミリー (Cryptographic Algorithm Family) を識別します。例えば「RSA」や「EC」などです。「kty」値は、[JWA] によって確立された IANA「JSON Web Key Types」レジストリに登録されるべきです (SHOULD)、または衝突耐性名を含む値であるべきです。「kty」値は大文字小文字を区別する文字列です。このメンバーは必ず (MUST) JWK に存在しなければなりません。

定義された「kty」値のリストは、[JWA] によって確立された IANA「JSON Web Key Types」レジストリで見つけることができます。このレジストリの初期内容は、[JWA] のセクション 6.1 で定義された値です。

鍵タイプ定義には、これらの鍵タイプに使用されるメンバーの仕様が含まれます。特定の「kty」値と共に使用されるメンバーは、セクション 8.1 で確立された IANA「JSON Web Key Parameters」レジストリで見つけることができます。

4.2. "use" (Public Key Use) Parameter (公開鍵用途パラメータ)​

「use」(public key use、公開鍵用途) パラメータは、公開鍵の意図された用途を識別します。「use」パラメータは、公開鍵がデータの暗号化に使用されるか、データ上の署名の検証に使用されるかを示すために使用されます。

本仕様で定義される値は次のとおりです:

  • "sig" (signature、署名)
  • "enc" (encryption、暗号化)

他の値を使用することができます (MAY)。「use」値は大文字小文字を区別する文字列です。「use」メンバーの使用は任意です (OPTIONAL)。ただし、アプリケーションがその存在を要求する場合を除きます。

鍵が別の鍵をラップ (Wrap) するために使用され、最初の鍵に公開鍵用途の指定が必要な場合、「enc」(encryption、暗号化) 鍵用途値が使用されます。これは、鍵ラッピングが暗号化の一種であるためです。「enc」値は、鍵協商 (Key Agreement) 操作に使用される公開鍵にも使用されます。

追加の「use」(public key use) 値は、セクション 8.2 で確立された IANA「JSON Web Key Use」レジストリに登録することができます (MAY)。本仕様がオープン環境で使用される場合、使用される拡張値を登録することが強く推奨されます (RECOMMENDED)。オープン環境では、複数の組織が使用される拡張について共通の理解を持つ必要があります。ただし、登録されていない拡張値は、クローズド環境で使用することができます。クローズド環境では、生産組織と消費組織は常に同じです。

4.3. "key_ops" (Key Operations) Parameter (鍵操作パラメータ)​

「key_ops」(key operations、鍵操作) パラメータは、鍵が使用される予定の操作を識別します。「key_ops」パラメータは、公開鍵、秘密鍵、または対称鍵が存在する可能性のあるユースケースを対象としています。

その値は、鍵操作値の配列です。本仕様で定義される値は次のとおりです:

  • "sign" (compute digital signature or MAC、デジタル署名または MAC を計算)
  • "verify" (verify digital signature or MAC、デジタル署名または MAC を検証)
  • "encrypt" (encrypt content、コンテンツを暗号化)
  • "decrypt" (decrypt content and validate decryption, if applicable、コンテンツを復号化し、該当する場合は復号化を検証)
  • "wrapKey" (encrypt key、鍵を暗号化)
  • "unwrapKey" (decrypt key and validate decryption, if applicable、鍵を復号化し、該当する場合は復号化を検証)
  • "deriveKey" (derive key、鍵を派生)
  • "deriveBits" (derive bits not to be used as a key、鍵として使用されないビットを派生)

(「key_ops」値は、Web Cryptography API [W3C.CR-WebCryptoAPI-20141211] 仕様で定義されている「KeyUsage」値と意図的に一致していることに注意してください。)

他の値を使用することができます (MAY)。鍵操作値は大文字小文字を区別する文字列です。配列内に重複する鍵操作値が存在してはなりません (MUST NOT)。「key_ops」メンバーの使用は任意です (OPTIONAL)。ただし、アプリケーションがその存在を要求する場合を除きます。

同じ鍵で複数のアルゴリズムを使用することに関連する潜在的な脆弱性があるため、鍵に複数の無関係な鍵操作を指定すべきではありません (SHOULD NOT)。したがって、「sign」と「verify」、「encrypt」と「decrypt」、および「wrapKey」と「unwrapKey」の組み合わせは許可されますが、他の組み合わせは使用すべきではありません (SHOULD NOT)。

追加の「key_ops」(key operations) 値は、セクション 8.3 で確立された IANA「JSON Web Key Operations」レジストリに登録することができます (MAY)。拡張値の登録に関する同じ考慮事項が、「use」メンバーと同様に「key_ops」メンバーにも適用されます。

「use」と「key_ops」JWK メンバーは一緒に使用すべきではありません (SHOULD NOT)。ただし、両方が使用される場合、それらが伝える情報は必ず (MUST) 一貫している必要があります。アプリケーションは、これらのメンバーのいずれかを使用する場合、どちらを使用するかを指定すべきです (SHOULD)。

4.4. "alg" (Algorithm) Parameter (アルゴリズムパラメータ)​

「alg」(algorithm、アルゴリズム) パラメータは、鍵と共に使用される予定のアルゴリズムを識別します。使用される値は、[JWA] によって確立された IANA「JSON Web Signature and Encryption Algorithms」レジストリに登録されるべきです (SHOULD)、または衝突耐性名を含む値であるべきです。「alg」値は大文字小文字を区別する ASCII 文字列です。このメンバーの使用は任意です (OPTIONAL)。

4.5. "kid" (Key ID) Parameter (鍵 ID パラメータ)​

「kid」(key ID、鍵 ID) パラメータは、特定の鍵を照合するために使用されます。これは、例えば、鍵のロールオーバー (Key Rollover) 中に JWK Set 内の鍵のセットから選択するために使用されます。「kid」値の構造は指定されていません。JWK Set 内で「kid」値が使用される場合、JWK Set 内の異なる鍵は異なる「kid」値を使用すべきです (SHOULD)。(異なる鍵が同じ「kid」値を使用する可能性がある例の一つは、それらが異なる「kty」(key type、鍵タイプ) 値を持っているが、それらを使用するアプリケーションによって等価な代替と見なされる場合です。)「kid」値は大文字小文字を区別する文字列です。このメンバーの使用は任意です (OPTIONAL)。JWS または JWE と共に使用される場合、「kid」値は JWS または JWE の「kid」Header Parameter 値と照合するために使用されます。

4.6. "x5u" (X.509 URL) Parameter (X.509 URL パラメータ)​

「x5u」(X.509 URL) パラメータは、X.509 公開鍵証明書または証明書チェーン (Certificate Chain) [RFC5280] のリソースを参照する URI [RFC3986] です。識別されたリソースは必ず (MUST)、RFC 5280 [RFC5280] に準拠した証明書または証明書チェーンの表現を PEM エンコード形式で提供し、各証明書は RFC 4945 [RFC4945] のセクション 6.1 で指定されているように区切られている必要があります。最初の証明書の鍵は必ず (MUST)、JWK の他のメンバーによって表現される公開鍵と一致しなければなりません。リソースを取得するために使用されるプロトコルは必ず (MUST) 完全性保護 (Integrity Protection) を提供しなければなりません。証明書を取得する HTTP GET リクエストは必ず (MUST) TLS [RFC2818] [RFC5246] を使用しなければなりません。サーバーの ID は必ず (MUST)、RFC 6125 [RFC6125] のセクション 6 に従って検証されなければなりません。このメンバーの使用は任意です (OPTIONAL)。

「x5u」メンバーが使用される場合、鍵用途、アルゴリズム、またはその他の情報を提供する任意の JWK メンバーが存在する必要はありませんが、そうすることで PKIX 証明書 [RFC5280] を処理しないアプリケーションの相互運用性が向上する可能性があります。他のメンバーが存在する場合、それらのメンバーの内容は必ず (MUST)、最初の証明書の関連フィールドと意味的に一致しなければなりません。例えば、「use」メンバーが存在する場合、証明書にこの情報が含まれているときは、証明書で指定されている用途に必ず (MUST) 対応しなければなりません。同様に、「alg」メンバーが存在する場合、証明書で指定されているアルゴリズムに必ず (MUST) 対応しなければなりません。

4.7. "x5c" (X.509 Certificate Chain) Parameter (X.509 証明書チェーンパラメータ)​

「x5c」(X.509 certificate chain、X.509 証明書チェーン) パラメータは、1 つ以上の PKIX 証明書 [RFC5280] のチェーンを含みます。証明書チェーンは、証明書値文字列の JSON 配列として表現されます。配列内の各文字列は、base64 エンコード ([RFC4648] のセクション 4 -- base64url エンコードではありません) された DER [ITU.X690.1994] PKIX 証明書値です。鍵値を含む PKIX 証明書は必ず (MUST) 最初の証明書でなければなりません。これに続いて追加の証明書が続くことができます (MAY)。各後続の証明書は、前の証明書を認証するために使用される証明書です。最初の証明書の鍵は必ず (MUST)、JWK の他のメンバーによって表現される公開鍵と一致しなければなりません。このメンバーの使用は任意です (OPTIONAL)。

「x5u」メンバーと同様に、「x5c」メンバーが使用される場合、鍵用途、アルゴリズム、またはその他の情報を提供する任意の JWK メンバーも存在することができます (MAY)。他のメンバーが存在する場合、それらのメンバーの内容は必ず (MUST)、最初の証明書の関連フィールドと意味的に一致しなければなりません。これに関する追加のガイダンスについては、セクション 4.6 の最後の段落を参照してください。

4.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter (X.509 証明書 SHA-1 サムプリントパラメータ)​

「x5t」(X.509 certificate SHA-1 thumbprint、X.509 証明書 SHA-1 サムプリント) パラメータは、X.509 証明書 [RFC5280] の DER エンコーディングの base64url エンコードされた SHA-1 サムプリント (thumbprint、別名ダイジェスト digest) です。証明書サムプリントは、証明書フィンガープリント (certificate fingerprints) とも呼ばれることに注意してください。証明書内の鍵は必ず (MUST)、JWK の他のメンバーによって表現される公開鍵と一致しなければなりません。このメンバーの使用は任意です (OPTIONAL)。

「x5u」メンバーと同様に、「x5t」メンバーが使用される場合、鍵用途、アルゴリズム、またはその他の情報を提供する任意の JWK メンバーも存在することができます (MAY)。他のメンバーが存在する場合、それらのメンバーの内容は必ず (MUST)、参照される証明書の関連フィールドと意味的に一致しなければなりません。これに関する追加のガイダンスについては、セクション 4.6 の最後の段落を参照してください。

4.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter (X.509 証明書 SHA-256 サムプリントパラメータ)​

「x5t#S256」(X.509 certificate SHA-256 thumbprint、X.509 証明書 SHA-256 サムプリント) パラメータは、X.509 証明書 [RFC5280] の DER エンコーディングの base64url エンコードされた SHA-256 サムプリント (thumbprint、別名ダイジェスト digest) です。証明書サムプリントは、証明書フィンガープリント (certificate fingerprints) とも呼ばれることに注意してください。証明書内の鍵は必ず (MUST)、JWK の他のメンバーによって表現される公開鍵と一致しなければなりません。このメンバーの使用は任意です (OPTIONAL)。

「x5u」メンバーと同様に、「x5t#S256」メンバーが使用される場合、鍵用途、アルゴリズム、またはその他の情報を提供する任意の JWK メンバーも存在することができます (MAY)。他のメンバーが存在する場合、それらのメンバーの内容は必ず (MUST)、参照される証明書の関連フィールドと意味的に一致しなければなりません。これに関する追加のガイダンスについては、セクション 4.6 の最後の段落を参照してください。

に最終更新