4. JOSE Header
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 Parameter, 并按照本规范定义的方式处理它们. 本规范定义的所有其他未作此指定的 Header Parameter, 在无法理解时 MUST 被忽略. 除非按照第 4.1.11 节被列为关键 Header Parameter, 否则所有非本规范定义的 Header Parameter 在无法理解时 MUST 被忽略.
Header Parameter 名称分为三类: Registered Header Parameter 名称, Public Header Parameter 名称, 以及 Private Header Parameter 名称.
4.1 Registered Header Parameter Names (已注册的 Header Parameter 名称)
以下用于 JWS 的 Header Parameter 名称已注册到 IANA "JSON Web Signature and Encryption Header Parameters" 注册表中; 该注册表由第 9.1 节建立, 其含义在下面的小节中定义.
如公共注册表所示, 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" 值是区分大小写的 ASCII 字符串, 其中包含一个 StringOrURI 值. 此 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
"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
"jwk" (JSON Web Key) Header Parameter 是与用于对 JWS 进行数字签名的密钥相对应的公钥. 此密钥表示为 JSON Web Key [JWK]. 使用此 Header Parameter 是 OPTIONAL.
4.1.4 "kid" (Key ID) Header Parameter
"kid" (key ID) Header Parameter 是一个提示, 指示使用了哪个密钥来保护 JWS. 该参数允许发起方向接收方显式发出密钥变更信号. "kid" 值的结构未作规定. 其值 MUST 是区分大小写的字符串. 使用此 Header Parameter 是 OPTIONAL.
当与 JWK 一起使用时, "kid" 值用于匹配 JWK 的 "kid" 参数值.
4.1.5 "x5u" (X.509 URL) Header Parameter
"x5u" (X.509 URL) Header Parameter 是一个 URI [RFC3986], 它引用 X.509 公钥证书或证书链 [RFC5280] 的资源, 该证书或证书链对应于用于对 JWS 进行数字签名的密钥. 被标识的资源 MUST 以 PEM 编码形式提供符合 RFC 5280 [RFC5280] 的证书或证书链表示, 每个证书按 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
"x5c" (X.509 certificate chain) Header Parameter 包含与用于对 JWS 进行数字签名的密钥相对应的 X.509 公钥证书或证书链 [RFC5280]. 证书或证书链表示为由证书值字符串组成的 JSON 数组. 数组中的每个字符串都是 base64 编码的 DER [ITU.X690.2008] PKIX 证书值 (见 [RFC4648] 第 4 节, 不是 base64url 编码). 包含与用于对 JWS 进行数字签名的密钥相对应公钥的证书 MUST 是第一个证书. 后面 MAY 跟随其他证书, 每个后续证书都是用于认证前一个证书的证书. 接收方 MUST 按 RFC 5280 [RFC5280] 验证证书链, 并在发生任何验证失败时认为该证书或证书链无效. 使用此 Header Parameter 是 OPTIONAL.
有关 "x5c" 值的示例, 请参见 Appendix B.
4.1.7 "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter
"x5t" (X.509 certificate SHA-1 thumbprint) Header Parameter 是 X.509 证书 [RFC5280] 的 DER 编码的 SHA-1 指纹 (thumbprint, 又称摘要 digest) 的 base64url 编码值, 该证书对应于用于对 JWS 进行数字签名的密钥. 注意, 证书 thumbprint 有时也称为证书 fingerprint. 使用此 Header Parameter 是 OPTIONAL.
4.1.8 "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter
"x5t#S256" (X.509 certificate SHA-256 thumbprint) Header Parameter 是 X.509 证书 [RFC5280] 的 DER 编码的 SHA-256 指纹 (thumbprint, 又称摘要 digest) 的 base64url 编码值, 该证书对应于用于对 JWS 进行数字签名的密钥. 注意, 证书 thumbprint 有时也称为证书 fingerprint. 使用此 Header Parameter 是 OPTIONAL.
4.1.9 "typ" (Type) Header Parameter
"typ" (type) Header Parameter 由 JWS 应用用来声明这个完整 JWS 的媒体类型 (media type) [IANA.MediaTypes]. 当能够包含 JWS 的应用数据结构中可能出现多种对象时, 该参数供应用使用; 应用可以使用此值来区分可能出现的不同对象类型. 当对象类型已经已知时, 应用通常不会使用该参数. JWS 实现会忽略此参数; 对此参数的任何处理均由 JWS 应用执行. 使用此 Header Parameter 是 OPTIONAL.
根据 RFC 2045 [RFC2045], 所有媒体类型值, 子类型值和参数名称都不区分大小写. 但是, 除非特定参数另有规定, 参数值区分大小写.
为了在常见情况下保持消息紧凑, RECOMMENDED 生产者在 "typ" Header Parameter 中的媒体类型值不包含其他 '/' 时省略 "application/" 前缀. 使用该媒体类型值的接收方 MUST 将任何不包含 '/' 的 "typ" 值视为已在其前面添加 "application/". 例如, SHOULD 使用 "typ" 值 "example" 来表示 "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 应用用来声明被保护内容 (payload) 的媒体类型 [IANA.MediaTypes]. 当 JWS Payload 中可能出现多种对象时, 该参数供应用使用; 应用可以使用此值来区分可能出现的不同对象类型. 当对象类型已经已知时, 应用通常不会使用该参数. JWS 实现会忽略此参数; 对此参数的任何处理均由 JWS 应用执行. 使用此 Header Parameter 是 OPTIONAL.
根据 RFC 2045 [RFC2045], 所有媒体类型值, 子类型值和参数名称都不区分大小写. 但是, 除非特定参数另有规定, 参数值区分大小写.
为了在常见情况下保持消息紧凑, RECOMMENDED 生产者在 "cty" Header Parameter 中的媒体类型值不包含其他 '/' 时省略 "application/" 前缀. 使用该媒体类型值的接收方 MUST 将任何不包含 '/' 的 "cty" 值视为已在其前面添加 "application/". 例如, SHOULD 使用 "cty" 值 "example" 来表示 "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 Parameter, 则 JWS 无效. 生产者 MUST NOT 在 "crit" 列表中包含本规范或 [JWA] 为 JWS 使用而定义的 Header Parameter 名称, 重复名称, 或者 JOSE Header 中并未作为 Header Parameter 名称出现的名称. 生产者 MUST NOT 使用空列表 "[]" 作为 "crit" 值. 如果 critical 列表包含本规范或 [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 (公共 Header Parameter 名称)
使用 JWS 的各方可以定义额外的 Header Parameter 名称. 但是, 为了防止碰撞, 任何新的 Header Parameter 名称都应当注册到第 9.1 节建立的 IANA "JSON Web Signature and Encryption Header Parameters" 注册表中, 或者是 Public Name (包含 Collision-Resistant Name 的值). 在任何情况下, 名称或值的定义者都需要采取合理预防措施, 确保其控制用于定义该 Header Parameter 名称的命名空间部分.
新的 Header Parameter 应当谨慎引入, 因为它们可能导致不可互操作的 JWS.
4.3 Private Header Parameter Names (私有 Header Parameter 名称)
JWS 的生产者和消费者可以约定使用属于 Private Name 的 Header Parameter 名称 (不是 Registered Header Parameter 名称 (第 4.1 节)), 或者使用 Public Header Parameter 名称 (第 4.2 节). 与 Public Header Parameter 名称不同, Private Header Parameter 名称可能发生碰撞, 因此应谨慎使用.