Skip to main content

7. Serializations (序列化)

JWE 使用两种序列化之一: JWE Compact Serialization (JWE 紧凑序列化) 或 JWE JSON Serialization (JWE JSON 序列化). 使用本规范的应用程序需要指定该应用程序使用的序列化和序列化特性. 例如, 应用程序可能指定仅使用 JWE JSON Serialization, 仅使用对单个接收方的 JWE JSON Serialization 支持, 或使用对多个接收方的支持. JWE 实现只需要实现它们设计支持的应用程序所需的特性.

7.1 JWE Compact Serialization (JWE 紧凑序列化)​

JWE Compact Serialization 将加密内容表示为紧凑的、URL 安全的字符串. 此字符串是:

BASE64URL(UTF8(JWE Protected Header)) || '.' ||
BASE64URL(JWE Encrypted Key) || '.' ||
BASE64URL(JWE Initialization Vector) || '.' ||
BASE64URL(JWE Ciphertext) || '.' ||
BASE64URL(JWE Authentication Tag)

JWE Compact Serialization 仅支持一个接收方, 并且不提供表示 JWE Shared Unprotected Header、JWE Per-Recipient Unprotected Header 或 JWE AAD 值的语法.

7.2 JWE JSON Serialization (JWE JSON 序列化)​

JWE JSON Serialization 将加密内容表示为 JSON 对象. 此表示既不针对紧凑性进行优化, 也不是 URL 安全的.

为 JWE JSON Serialization 定义了两种密切相关的语法: 一种完全通用的语法, 可以将内容加密给多个接收方, 以及一种扁平化语法, 针对单接收方情况进行了优化.

7.2.1 General JWE JSON Serialization Syntax (通用 JWE JSON 序列化语法)​

以下成员定义用于完全通用的 JWE JSON Serialization 语法的顶级 JSON 对象:

protected : 当 JWE Protected Header 值非空时, "protected" 成员必须 (MUST) 存在并包含值 BASE64URL(UTF8(JWE Protected Header)); 否则, 它必须 (MUST) 不存在. 这些 Header Parameter 值受完整性保护.

unprotected : 当 JWE Shared Unprotected Header 值非空时, "unprotected" 成员必须 (MUST) 存在并包含值 JWE Shared Unprotected Header; 否则, 它必须 (MUST) 不存在. 此值表示为未编码的 JSON 对象, 而不是字符串. 这些 Header Parameter 值不受完整性保护.

iv : 当 JWE Initialization Vector 值非空时, "iv" 成员必须 (MUST) 存在并包含值 BASE64URL(JWE Initialization Vector); 否则, 它必须 (MUST) 不存在.

aad : 当 JWE AAD 值非空时, "aad" 成员必须 (MUST) 存在并包含值 BASE64URL(JWE AAD)); 否则, 它必须 (MUST) 不存在. 可以包含 JWE AAD 值以提供受完整性保护但不加密的 base64url 编码值.

ciphertext : "ciphertext" 成员必须 (MUST) 存在并包含值 BASE64URL(JWE Ciphertext).

tag : 当 JWE Authentication Tag 值非空时, "tag" 成员必须 (MUST) 存在并包含值 BASE64URL(JWE Authentication Tag); 否则, 它必须 (MUST) 不存在.

recipients : "recipients" 成员值必须 (MUST) 是 JSON 对象的数组. 每个对象包含特定于单个接收方的信息. 即使某些或所有数组元素值都是空 JSON 对象 "" (当所有 Header Parameter 值在所有接收方之间共享且未使用加密密钥时可能会发生这种情况, 例如在进行 Direct Encryption 时), 此成员也必须 (MUST) 存在, 每个接收方恰好有一个数组元素.

以下成员定义用于 "recipients" 数组元素的 JSON 对象:

header : 当 JWE Per-Recipient Unprotected Header 值非空时, "header" 成员必须 (MUST) 存在并包含值 JWE Per-Recipient Unprotected Header; 否则, 它必须 (MUST) 不存在. 此值表示为未编码的 JSON 对象, 而不是字符串. 这些 Header Parameter 值不受完整性保护.

encrypted_key : 当 JWE Encrypted Key 值非空时, "encrypted_key" 成员必须 (MUST) 存在并包含值 BASE64URL(JWE Encrypted Key); 否则, 它必须 (MUST) 不存在.

"header"、"protected" 和 "unprotected" 成员中的至少一个必须 (MUST) 存在, 以便为每个接收方计算传达 "alg" 和 "enc" Header Parameter 值.

上面定义的 JSON 对象中可以存在其他成员; 如果遇到它们的实现不理解它们, 则必须 (MUST) 忽略它们.

某些 Header Parameters (包括 "alg" 参数) 可以在所有接收方计算之间共享. JWE Protected Header 和 JWE Shared Unprotected Header 值中的 Header Parameters 在所有接收方之间共享.

创建或验证每接收方密文和 Authentication Tag 值时使用的 Header Parameter 值是可能存在的三组 Header Parameter 值的并集: (1) 在 "protected" 成员中表示的 JWE Protected Header, (2) 在 "unprotected" 成员中表示的 JWE Shared Unprotected Header, 以及 (3) 在接收方的数组元素的 "header" 成员中表示的 JWE Per-Recipient Unprotected Header. 这些 Header Parameters 集合的并集构成 JOSE Header. 三个位置中的 Header Parameter 名称必须 (MUST) 是不相交的.

每个 JWE Encrypted Key 值使用相应 JOSE Header 值的参数以与 JWE Compact Serialization 相同的方式计算. 这具有理想的属性, 即 "recipients" 数组中的每个 JWE Encrypted Key 值与在 JWE Compact Serialization 中为相同参数计算的值相同. 同样, JWE Ciphertext 和 JWE Authentication Tag 值与为 JWE Compact Serialization 产生的值匹配, 前提是 JWE Protected Header 值 (表示受完整性保护的 Header Parameter 值) 与 JWE Compact Serialization 中使用的值匹配.

所有接收方在存在时使用相同的 JWE Protected Header、JWE Initialization Vector、JWE Ciphertext 和 JWE Authentication Tag 值, 如果消息很大, 则可能会显著节省空间. 因此, 指定明文值处理的所有 Header Parameters 对于所有接收方必须 (MUST) 相同. 这主要意味着每个接收方的 JOSE Header 中的 "enc" (encryption algorithm, 加密算法) Header Parameter 值以及该算法的任何参数必须 (MUST) 相同.

总之, 使用通用 JWE JSON Serialization 的 JWE 语法如下:

{
 "protected":"<integrity-protected shared header contents>",
 "unprotected":<non-integrity-protected shared header contents>,
 "recipients":[
  {"header":<per-recipient unprotected header 1 contents>,
   "encrypted_key":"<encrypted key 1 contents>"},
  ...
  {"header":<per-recipient unprotected header N contents>,
   "encrypted_key":"<encrypted key N contents>"}],
 "aad":"<additional authenticated data contents>",
 "iv":"<initialization vector contents>",
 "ciphertext":"<ciphertext contents>",
 "tag":"<authentication tag contents>"
}

有关使用通用 JWE JSON Serialization 语法的 JWE 示例, 请参见附录 A.4.

7.2.2 Flattened JWE JSON Serialization Syntax (扁平化 JWE JSON 序列化语法)​

扁平化 JWE JSON Serialization 语法基于通用语法, 但将其扁平化, 针对单接收方情况进行了优化. 它通过删除 "recipients" 成员并将为在 "recipients" 数组中使用而定义的那些成员 ("header" 和 "encrypted_key" 成员) 放置在顶级 JSON 对象中 (与 "ciphertext" 成员处于同一级别) 来扁平化它.

使用此语法时, "recipients" 成员禁止 (MUST NOT) 存在. 除了这种语法差异之外, 使用扁平化语法的 JWE JSON Serialization 对象的处理方式与使用通用语法的对象完全相同.

总之, 使用扁平化 JWE JSON Serialization 的 JWE 语法如下:

{
 "protected":"<integrity-protected header contents>",
 "unprotected":<non-integrity-protected header contents>,
 "header":<more non-integrity-protected header contents>,
 "encrypted_key":"<encrypted key contents>",
 "aad":"<additional authenticated data contents>",
 "iv":"<initialization vector contents>",
 "ciphertext":"<ciphertext contents>",
 "tag":"<authentication tag contents>"
}

请注意, 当使用扁平化语法时, 正如使用通用语法时一样, 任何非受保护的 Header Parameter 值都可以驻留在 "unprotected" 成员或 "header" 成员中, 或两者都有.

有关使用扁平化 JWE JSON Serialization 语法的 JWE 示例, 请参见附录 A.5.

Last updated on