Skip to main content

4. JOSE Header (JOSE 头部)

对于 JWS, 表示 JOSE Header 的 JSON 对象的成员描述了应用于 JWS Protected Header 和 JWS Payload 的数字签名或 MAC, 以及可选的 JWS 的其他属性. JOSE Header 中的 Header Parameter 名称必须 (MUST) 是唯一的; JWS 解析器必须 (MUST) 拒绝具有重复 Header Parameter 名称的 JWS, 或使用仅返回词法上最后一个重复成员名称的 JSON 解析器, 如 ECMAScript 5.1 [ECMAScript] 第 15.12 节 ("The JSON Object") 中所规定.

实现需要理解本规范定义的被指定为 "MUST be understood" (必须理解) 的特定 Header Parameters, 并按照本规范中定义的方式处理它们. 本规范定义的所有其他未如此指定的 Header Parameters 在不理解时必须 (MUST) 被忽略. 除非按照第 4.1.11 节列为关键 Header Parameter, 否则所有本规范未定义的 Header Parameters 在不理解时必须 (MUST) 被忽略.

Header Parameter 名称有三类: Registered Header Parameter names (注册头部参数名称)、Public Header Parameter names (公共头部参数名称) 和 Private Header Parameter names (私有头部参数名称).

4.1 Registered Header Parameter Names (注册头部参数名称)​

以下用于 JWS 的 Header Parameter 名称在第 9.1 节建立的 IANA "JSON Web Signature and Encryption Header Parameters" 注册表中注册, 其含义在下面的子章节中定义.

如通用注册表所示, JWS 和 JWE 共享一个通用的 Header Parameter 空间; 当参数被两个规范使用时, 其用法在规范之间必须兼容.

4.1.1 "alg" (Algorithm) Header Parameter (算法头部参数)​

"alg" (algorithm, 算法) Header Parameter 标识用于保护 JWS 的加密算法. 如果 "alg" 值不表示支持的算法, 或者没有与数字签名或 MAC 内容的一方相关联的用于该算法的密钥, 则 JWS Signature 值无效. "alg" 值应该在 [JWA] 建立的 IANA "JSON Web Signature and Encryption Algorithms" 注册表中注册, 或者是包含 Collision-Resistant Name (抗冲突名称) 的值. "alg" 值是包含 StringOrURI 值的区分大小写的 ASCII 字符串. 此 Header Parameter 必须 (MUST) 存在, 并且必须 (MUST) 被实现理解和处理.

[JWA] 建立的 IANA "JSON Web Signature and Encryption Algorithms" 注册表中可以找到用于此用途的已定义 "alg" 值列表; 此注册表的初始内容是 [JWA] 第 3.1 节中定义的值.

4.1.2 "jku" (JWK Set URL) Header Parameter (JWK 集合 URL 头部参数)​

"jku" (JWK Set URL) Header Parameter 是一个 URI [RFC3986], 它引用一组 JSON 编码的公钥资源, 其中一个对应于用于数字签名 JWS 的密钥. 密钥必须 (MUST) 编码为 JWK Set [JWK]. 用于获取资源的协议必须 (MUST) 提供完整性保护; 检索 JWK Set 的 HTTP GET 请求必须 (MUST) 使用传输层安全 (Transport Layer Security, TLS) [RFC2818] [RFC5246]; 并且必须 (MUST) 验证服务器的身份, 符合 RFC 6125 [RFC6125] 第 6 节. 另请参见第 8 节关于 TLS 要求. 使用此 Header Parameter 是可选的 (OPTIONAL).

4.1.3 "jwk" (JSON Web Key) Header Parameter (JSON Web 密钥头部参数)​

"jwk" (JSON Web Key) Header Parameter 是与用于数字签名 JWS 的密钥对应的公钥. 此密钥表示为 JSON Web Key [JWK]. 使用此 Header Parameter 是可选的 (OPTIONAL).

4.1.4 "kid" (Key ID) Header Parameter (密钥 ID 头部参数)​

"kid" (key ID, 密钥 ID) Header Parameter 是一个提示, 指示使用哪个密钥来保护 JWS. 此参数允许发起者明确向接收者发出密钥更改的信号. "kid" 值的结构未指定. 其值必须 (MUST) 是区分大小写的字符串. 使用此 Header Parameter 是可选的 (OPTIONAL).

当与 JWK 一起使用时, "kid" 值用于匹配 JWK "kid" 参数值.

4.1.5 "x5u" (X.509 URL) Header Parameter (X.509 URL 头部参数)​

"x5u" (X.509 URL) Header Parameter 是一个 URI [RFC3986], 它引用与用于数字签名 JWS 的密钥对应的 X.509 公钥证书或证书链 [RFC5280] 的资源. 标识的资源必须 (MUST) 提供符合 RFC 5280 [RFC5280] 的证书或证书链的表示, 采用 PEM 编码形式, 每个证书按照 RFC 4945 [RFC4945] 第 6.1 节中的规定进行分隔. 包含与用于数字签名 JWS 的密钥对应的公钥的证书必须 (MUST) 是第一个证书. 后面可以 (MAY) 跟随其他证书, 每个后续证书是用于认证前一个证书的证书. 用于获取资源的协议必须 (MUST) 提供完整性保护; 检索证书的 HTTP GET 请求必须 (MUST) 使用 TLS [RFC2818] [RFC5246]; 并且必须 (MUST) 验证服务器的身份, 符合 RFC 6125 [RFC6125] 第 6 节. 另请参见第 8 节关于 TLS 要求. 使用此 Header Parameter 是可选的 (OPTIONAL).

4.1.6 "x5c" (X.509 Certificate Chain) Header Parameter (X.509 证书链头部参数)​

"x5c" (X.509 certificate chain, X.509 证书链) Header Parameter 包含与用于数字签名 JWS 的密钥对应的 X.509 公钥证书或证书链 [RFC5280]. 证书或证书链表示为证书值字符串的 JSON 数组. 数组中的每个字符串是 base64 编码的 ([RFC4648] 第 4 节 -- 不是 base64url 编码的) DER [ITU.X690.2008] PKIX 证书值. 包含与用于数字签名 JWS 的密钥对应的公钥的证书必须 (MUST) 是第一个证书. 后面可以 (MAY) 跟随其他证书, 每个后续证书是用于认证前一个证书的证书. 接收方必须 (MUST) 根据 RFC 5280 [RFC5280] 验证证书链, 并在发生任何验证失败时将证书或证书链视为无效. 使用此 Header Parameter 是可选的 (OPTIONAL).

有关 "x5c" 值的示例, 请参见附录 B.

4.1.7 "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter (X.509 证书 SHA-1 指纹头部参数)​

"x5t" (X.509 certificate SHA-1 thumbprint, X.509 证书 SHA-1 指纹) Header Parameter 是与用于数字签名 JWS 的密钥对应的 X.509 证书 [RFC5280] 的 DER 编码的 base64url 编码的 SHA-1 指纹 (也称为摘要). 请注意, 证书指纹有时也称为证书指纹. 使用此 Header Parameter 是可选的 (OPTIONAL).

4.1.8 "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter (X.509 证书 SHA-256 指纹头部参数)​

"x5t#S256" (X.509 certificate SHA-256 thumbprint, X.509 证书 SHA-256 指纹) Header Parameter 是与用于数字签名 JWS 的密钥对应的 X.509 证书 [RFC5280] 的 DER 编码的 base64url 编码的 SHA-256 指纹 (也称为摘要). 请注意, 证书指纹有时也称为证书指纹. 使用此 Header Parameter 是可选的 (OPTIONAL).

4.1.9 "typ" (Type) Header Parameter (类型头部参数)​

"typ" (type, 类型) Header Parameter 由 JWS 应用程序使用, 用于声明此完整 JWS 的媒体类型 [IANA.MediaTypes]. 这旨在供应用程序在应用程序数据结构中可能存在多种对象类型且可以包含 JWS 时使用; 应用程序可以使用此值来区分可能存在的不同类型的对象. 当对象的类型已知时, 应用程序通常不会使用它. JWS 实现会忽略此参数; 任何对此参数的处理都由 JWS 应用程序执行. 使用此 Header Parameter 是可选的 (OPTIONAL).

根据 RFC 2045 [RFC2045], 所有媒体类型值、子类型值和参数名称都不区分大小写. 但是, 参数值是区分大小写的, 除非为特定参数另有规定.

为了在常见情况下保持消息紧凑, 建议 (RECOMMENDED) 生产者在 "typ" Header Parameter 中省略媒体类型值的 "application/" 前缀, 当媒体类型值中没有其他 '/' 出现时. 使用媒体类型值的接收方必须 (MUST) 将其视为在不包含 '/' 的任何 "typ" 值前加上 "application/". 例如, "typ" 值 "example" 应该 (SHOULD) 用于表示 "application/example" 媒体类型, 而媒体类型 "application/example;part="1/2"" 不能缩短为 "example;part="1/2"".

应用程序可以使用 "typ" 值 "JOSE" 来指示此对象是使用 JWS Compact Serialization 或 JWE Compact Serialization 的 JWS 或 JWE. 应用程序可以使用 "typ" 值 "JOSE+JSON" 来指示此对象是使用 JWS JSON Serialization 或 JWE JSON Serialization 的 JWS 或 JWE. 应用程序还可以使用其他类型值.

4.1.10 "cty" (Content Type) Header Parameter (内容类型头部参数)​

"cty" (content type, 内容类型) Header Parameter 由 JWS 应用程序使用, 用于声明受保护内容 (载荷) 的媒体类型 [IANA.MediaTypes]. 这旨在供应用程序在 JWS Payload 中可能存在多种对象类型时使用; 应用程序可以使用此值来区分可能存在的不同类型的对象. 当对象的类型已知时, 应用程序通常不会使用它. JWS 实现会忽略此参数; 任何对此参数的处理都由 JWS 应用程序执行. 使用此 Header Parameter 是可选的 (OPTIONAL).

根据 RFC 2045 [RFC2045], 所有媒体类型值、子类型值和参数名称都不区分大小写. 但是, 参数值是区分大小写的, 除非为特定参数另有规定.

为了在常见情况下保持消息紧凑, 建议 (RECOMMENDED) 生产者在 "cty" Header Parameter 中省略媒体类型值的 "application/" 前缀, 当媒体类型值中没有其他 '/' 出现时. 使用媒体类型值的接收方必须 (MUST) 将其视为在不包含 '/' 的任何 "cty" 值前加上 "application/". 例如, "cty" 值 "example" 应该 (SHOULD) 用于表示 "application/example" 媒体类型, 而媒体类型 "application/example;part="1/2"" 不能缩短为 "example;part="1/2"".

4.1.11 "crit" (Critical) Header Parameter (关键头部参数)​

"crit" (critical, 关键) Header Parameter 指示正在使用对本规范和/或 [JWA] 的扩展, 这些扩展必须 (MUST) 被理解和处理. 其值是一个数组, 列出了 JOSE Header 中使用这些扩展的 Header Parameter 名称. 如果接收方不理解和支持任何列出的扩展 Header Parameters, 则 JWS 无效. 生产者禁止 (MUST NOT) 在 "crit" 列表中包含本规范或 [JWA] 为与 JWS 一起使用而定义的 Header Parameter 名称、重复的名称或不作为 JOSE Header 中的 Header Parameter 名称出现的名称. 生产者禁止 (MUST NOT) 使用空列表 "[]" 作为 "crit" 值. 如果关键列表包含本规范或 [JWA] 为与 JWS 一起使用而定义的任何 Header Parameter 名称, 或者违反了对其使用的任何其他约束, 则接收方可以 (MAY) 将 JWS 视为无效. 使用时, 此 Header Parameter 必须 (MUST) 受完整性保护; 因此, 它必须 (MUST) 仅出现在 JWS Protected Header 中. 使用此 Header Parameter 是可选的 (OPTIONAL). 此 Header Parameter 必须 (MUST) 被实现理解和处理.

一个示例用法, 以及一个假设的 "exp" (expiration time, 过期时间) 字段是:

{"alg":"ES256",
 "crit":["exp"],
 "exp":1363284000
}

4.2 Public Header Parameter Names (公共头部参数名称)​

使用 JWS 的人可以定义其他 Header Parameter 名称. 但是, 为了防止冲突, 任何新的 Header Parameter 名称应该在第 9.1 节建立的 IANA "JSON Web Signature and Encryption Header Parameters" 注册表中注册, 或者是 Public Name (包含 Collision-Resistant Name 的值). 在每种情况下, 名称或值的定义者都需要采取合理的预防措施, 以确保他们控制用于定义 Header Parameter 名称的命名空间部分.

应该谨慎引入新的 Header Parameters, 因为它们可能导致不可互操作的 JWS.

4.3 Private Header Parameter Names (私有头部参数名称)​

JWS 的生产者和消费者可以同意使用 Private Names (不是 Registered Header Parameter names (第 4.1 节) 或 Public Header Parameter names (第 4.2 节) 的名称) 的 Header Parameter 名称. 与 Public Header Parameter Names 不同, Private Header Parameter Names 可能会发生冲突, 应该谨慎使用.

Last updated on