Skip to main content

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

JWK是表示加密密钥的JSON对象. 对象的成员表示密钥的属性，包括其值. 根据RFC 7159 [RFC7159] 第2节的规定，此JSON对象可以 (MAY) 在任何JSON值或结构字符之前或之后包含空格和/或换行符. 本文档定义了非算法特定的密钥参数，因此这些参数对许多密钥都是通用的.

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

JWK中的成员名称必须 (MUST) 是唯一的; JWK解析器必须 (MUST) 拒绝具有重复成员名称的JWK，或使用仅返回词法上最后一个重复成员名称的JSON解析器，如ECMAScript 5.1 [ECMAScript] 第15.12节 (The JSON Object) 中所指定.

JWK中可以存在其他成员; 如果遇到它们的实现不理解这些成员，则必须 (MUST) 忽略它们. 用于表示不同密钥类型的密钥参数的成员名称不必是不同的. 任何新成员名称应该 (SHOULD) 在第8.1节建立的IANA "JSON Web Key Parameters" 注册表中注册，或者是包含抗碰撞名称 (Collision-Resistant Name) 的值.

4.1. "kty" (Key Type) Parameter (密钥类型参数)​

"kty" (key type，密钥类型) 参数标识与密钥一起使用的加密算法族 (Cryptographic Algorithm Family)，例如"RSA"或"EC". "kty"值应该 (SHOULD) 在[JWA]建立的IANA "JSON Web Key Types" 注册表中注册，或者是包含抗碰撞名称的值. "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) 操作的公钥.

可以在第8.2节建立的IANA "JSON Web Key Use" 注册表中注册其他"use" (public key use) 值. 当在开放环境中使用本规范时，强烈建议 (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) 使用其他组合.

可以在第8.3节建立的IANA "JSON Web Key Operations" 注册表中注册其他"key_ops" (key operations) 值. 关于注册扩展值的相同考虑适用于"key_ops"成员，就像适用于"use"成员一样.

不应该 (SHOULD NOT) 同时使用"use"和"key_ops" JWK成员; 但是，如果两者都使用，它们传达的信息必须 (MUST) 是一致的. 应用程序应该 (SHOULD) 指定它们使用这些成员中的哪一个，如果应用程序要使用其中任何一个.

4.4. "alg" (Algorithm) Parameter (算法参数)​

"alg" (algorithm，算法) 参数标识预期与密钥一起使用的算法. 使用的值应该 (SHOULD) 在[JWA]建立的IANA "JSON Web Signature and Encryption Algorithms" 注册表中注册，或者是包含抗碰撞名称的值. "alg"值是区分大小写的ASCII字符串. 使用此成员是可选的 (OPTIONAL).

4.5. "kid" (Key ID) Parameter (密钥ID参数)​

"kid" (key ID，密钥ID) 参数用于匹配特定密钥. 例如，这用于在密钥轮换 (Key Rollover) 期间在JWK Set中的一组密钥中进行选择. "kid"值的结构是未指定的. 当在JWK Set中使用"kid"值时，JWK Set中的不同密钥应该 (SHOULD) 使用不同的"kid"值. (不同密钥可能使用相同"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公钥证书或证书链 [RFC5280] 资源的URI [RFC3986]. 标识的资源必须 (MUST) 提供符合RFC 5280 [RFC5280] 的PEM编码形式的证书或证书链的表示，每个证书按照RFC 4945 [RFC4945] 第6.1节中指定的方式分隔. 第一个证书中的密钥必须 (MUST) 与JWK的其他成员表示的公钥匹配. 用于获取资源的协议必须 (MUST) 提供完整性保护 (Integrity Protection); 检索证书的HTTP GET请求必须 (MUST) 使用TLS [RFC2818] [RFC5246]; 必须 (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证书链) 参数包含一个或多个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节的最后一段.

Last updated on