跳到主要内容

4. JSON Web Key (JWK) 格式 (Format)

JWK 是表示加密密钥的 JSON 对象. 该对象的 member 表示密钥的属性, 包括密钥值. 根据 RFC 7159 [RFC7159] 第 2 节, 此 JSON 对象 MAY 在任何 JSON 值或结构字符之前或之后包含空白和/或换行. 本文档定义了非算法特定的 key parameter, 因而这些参数通用于许多密钥.

除通用参数外, 每个 JWK 还会具有特定于 key type 的 member. 这些 member 表示密钥的参数. JSON Web Algorithms (JWA) [JWA] 规范第 6 节定义了多种加密密钥及其关联 member.

JWK 内的 member name MUST 唯一; JWK 解析器 MUST 拒绝包含重复 member name 的 JWK, 或者使用仅返回按词法顺序最后一个重复 member name 的 JSON 解析器, 如 ECMAScript 5.1 [ECMAScript] 第 15.12 节 (The JSON Object) 所规定.

JWK 中可以存在其他 member; 遇到这些 member 的实现如果不能理解它们, 则 MUST 忽略它们. 用于表示不同 key type 的 key parameter 的 member name 不必彼此不同. 任何新的 member name 都应注册到第 8.1 节建立的 IANA "JSON Web Key Parameters" 注册表中, 或者是一个包含 Collision-Resistant Name 的值.

4.1. "kty" (Key Type) 参数​

"kty" (key type) 参数标识与该密钥一起使用的加密算法族, 例如 "RSA" 或 "EC". "kty" 值应注册到 [JWA] 建立的 IANA "JSON Web Key Types" 注册表中, 或者是一个包含 Collision-Resistant Name 的值. "kty" 值是区分大小写的字符串. 此 member MUST 存在于 JWK 中.

已定义的 "kty" 值列表见 [JWA] 建立的 IANA "JSON Web Key Types" 注册表; 该注册表的初始内容为 [JWA] 第 6.1 节中定义的值.

key type 定义包括对这些 key type 所用 member 的规定. 与特定 "kty" 值一起使用的 member 见第 8.1 节建立的 IANA "JSON Web Key Parameters" 注册表.

4.2. "use" (Public Key Use) 参数​

"use" (public key use) 参数标识公钥的预期用途. "use" 参数用于指示公钥是用于加密数据, 还是用于验证数据上的签名.

本规范定义的值如下:

  • "sig" (signature)
  • "enc" (encryption)

MAY 使用其他值. "use" 值是区分大小写的字符串. 除非应用要求存在该 member, 否则 "use" member 的使用是 OPTIONAL.

当一个密钥用于包装另一个密钥, 并且需要为前一个密钥指定 public key use 时, 使用 "enc" (encryption) key use 值, 因为密钥包装是一种加密. "enc" 值也用于执行密钥协商操作的公钥.

附加的 "use" (public key use) 值可以注册到第 8.2 节建立的 IANA "JSON Web Key Use" 注册表中. 当本规范用于开放环境时, 强烈建议注册所使用的任何扩展值, 因为在这种环境中, 多个组织需要对所使用的任何扩展具有共同理解. 但是, 在封闭环境中可以使用未注册的扩展值, 在这种环境中, 产生方组织和消费方组织始终相同.

4.3. "key_ops" (Key Operations) 参数​

"key_ops" (key operations) 参数标识该密钥预期用于的操作. "key_ops" 参数面向可能存在公钥, 私钥或对称密钥的用例.

其值是 key operation 值数组. 本规范定义的值如下:

  • "sign" (compute digital signature or MAC)
  • "verify" (verify digital signature or 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 使用其他值. key operation 值是区分大小写的字符串. 数组中 MUST NOT 存在重复的 key operation 值. 除非应用要求存在该 member, 否则 "key_ops" member 的使用是 OPTIONAL.

SHOULD NOT 为一个密钥指定多个无关的 key operation, 因为同一密钥与多个算法一起使用会带来潜在漏洞. 因此, 允许 "sign" 与 "verify", "encrypt" 与 "decrypt", 以及 "wrapKey" 与 "unwrapKey" 的组合, 但其他组合 SHOULD NOT 使用.

附加的 "key_ops" (key operations) 值可以注册到第 8.3 节建立的 IANA "JSON Web Key Operations" 注册表中. 关于注册扩展值的同样考量也适用于 "key_ops" member, 与适用于 "use" member 的考量相同.

"use" 和 "key_ops" 这两个 JWK member SHOULD NOT 一起使用; 但是, 如果两者都使用, 它们传达的信息 MUST 一致. 如果应用要使用其中任一 member, 则应用应明确指定使用哪一个.

4.4. "alg" (Algorithm) 参数​

"alg" (algorithm) 参数标识预期与该密钥一起使用的算法. 所使用的值应注册到 [JWA] 建立的 IANA "JSON Web Signature and Encryption Algorithms" 注册表中, 或者是一个包含 Collision-Resistant Name 的值. "alg" 值是区分大小写的 ASCII 字符串. 此 member 的使用是 OPTIONAL.

4.5. "kid" (Key ID) 参数​

"kid" (key ID) 参数用于匹配特定密钥. 例如, 在密钥轮换期间, 它用于在 JWK Set 内的一组密钥中进行选择. "kid" 值的结构未作规定. 当 "kid" 值在 JWK Set 内使用时, JWK Set 内的不同密钥 SHOULD 使用不同的 "kid" 值. (不同密钥可能使用相同 "kid" 值的一个例子是: 它们具有不同的 "kty" (key type) 值, 但使用它们的应用认为它们是等效的替代项.) "kid" 值是区分大小写的字符串. 此 member 的使用是 OPTIONAL. 当与 JWS 或 JWE 一起使用时, "kid" 值用于匹配 JWS 或 JWE 的 "kid" Header Parameter 值.

4.6. "x5u" (X.509 URL) 参数​

"x5u" (X.509 URL) 参数是一个 URI [RFC3986], 指向 X.509 公钥证书或证书链 [RFC5280] 的资源. 所标识的资源 MUST 以 PEM 编码形式提供符合 RFC 5280 [RFC5280] 的证书或证书链表示, 其中每个证书按 RFC 4945 [RFC4945] 第 6.1 节的规定分隔. 第一个证书中的密钥 MUST 匹配 JWK 的其他 member 所表示的公钥. 用于获取该资源的协议 MUST 提供完整性保护; 用于检索证书的 HTTP GET 请求 MUST 使用 TLS [RFC2818] [RFC5246]; 服务器身份 MUST 按 RFC 6125 [RFC6125] 第 6 节进行验证. 此 member 的使用是 OPTIONAL.

使用 "x5u" member 时, 并不要求同时存在提供 key usage, algorithm 或其他信息的可选 JWK member, 但这样做可以提高不处理 PKIX 证书 [RFC5280] 的应用的互操作性. 如果存在其他 member, 这些 member 的内容 MUST 在语义上与第一个证书中的相关字段一致. 例如, 如果存在 "use" member, 则当证书包含此信息时, 它 MUST 对应于证书中指定的用途. 类似地, 如果存在 "alg" member, 它 MUST 对应于证书中指定的算法.

4.7. "x5c" (X.509 Certificate Chain) 参数​

"x5c" (X.509 certificate chain) 参数包含由一个或多个 PKIX 证书 [RFC5280] 组成的链. 证书链表示为证书值字符串的 JSON 数组. 数组中的每个字符串都是 base64 编码的 (见 [RFC4648] 第 4 节 -- 不是 base64url 编码的) DER [ITU.X690.1994] PKIX 证书值. 包含密钥值的 PKIX 证书 MUST 是第一个证书. 后面 MAY 跟随其他证书, 每个后续证书都是用于认证前一个证书的证书. 第一个证书中的密钥 MUST 匹配 JWK 的其他 member 所表示的公钥. 此 member 的使用是 OPTIONAL.

与 "x5u" member 一样, 使用 "x5c" member 时, 也 MAY 存在提供 key usage, algorithm 或其他信息的可选 JWK member. 如果存在其他 member, 这些 member 的内容 MUST 在语义上与第一个证书中的相关字段一致. 有关这方面的更多指导, 见第 4.6 节最后一段.

4.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) 参数​

"x5t" (X.509 certificate SHA-1 thumbprint) 参数是 X.509 证书 [RFC5280] 的 DER 编码的 base64url 编码 SHA-1 thumbprint (也称为 digest). 请注意, 证书 thumbprint 有时也称为证书 fingerprint. 证书中的密钥 MUST 匹配 JWK 的其他 member 所表示的公钥. 此 member 的使用是 OPTIONAL.

与 "x5u" member 一样, 使用 "x5t" member 时, 也 MAY 存在提供 key usage, algorithm 或其他信息的可选 JWK member. 如果存在其他 member, 这些 member 的内容 MUST 在语义上与所引用证书中的相关字段一致. 有关这方面的更多指导, 见第 4.6 节最后一段.

4.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 参数​

"x5t#S256" (X.509 certificate SHA-256 thumbprint) 参数是 X.509 证书 [RFC5280] 的 DER 编码的 base64url 编码 SHA-256 thumbprint (也称为 digest). 请注意, 证书 thumbprint 有时也称为证书 fingerprint. 证书中的密钥 MUST 匹配 JWK 的其他 member 所表示的公钥. 此 member 的使用是 OPTIONAL.

与 "x5u" member 一样, 使用 "x5t#S256" member 时, 也 MAY 存在提供 key usage, algorithm 或其他信息的可选 JWK member. 如果存在其他 member, 这些 member 的内容 MUST 在语义上与所引用证书中的相关字段一致. 有关这方面的更多指导, 见第 4.6 节最后一段.

最后于 更新