JWE API¶

文档的这一部分涵盖了 joserfc.jwe 的所有接口。

class joserfc.jwe.CompactEncryption(protected: Dict[str, Any], plaintext: bytes | None = None)¶

一个对象，用于表示 JWE 紧凑序列化。通常由 decrypt_compact 方法返回。

attach_recipient(key: OctKey | RSAKey | ECKey | OKPKey, header: Dict[str, Any] | None = None) → None¶

向 JWE 紧凑序列化添加一个接收者。请添加符合给定 "alg" 值的密钥。

参数:

key -- 一个密钥实例，例如 (OctKey, RSAKey, ECKey 等)
header -- 字典中的额外 header

plaintext¶: 字节形式的明文

protected¶: 字典中的受保护 header

class joserfc.jwe.FlattenedJSONEncryption(protected: Dict[str, Any], plaintext: bytes | None = None, unprotected: Dict[str, Any] | None = None, aad: bytes | None = None)¶

一个对象，用于表示 JWE 扁平 JSON 序列化。由 encrypt_json 使用，通常由 decrypt_json 方法返回。

构造 FlattenedJSONEncryption 对象：

protected = {"enc": "A128CBC-HS256"}
plaintext = b"hello world"
obj = FlattenedJSONEncryption(protected, plaintext)
# then add each recipient
obj.add_recipient({"alg": "A128KW"})

向 JWE JSON 序列化添加一个接收者。请添加符合 "alg" 的密钥。

参数:

header -- 接收者自己的（未保护的）header
key -- 一个密钥实例，例如 (OctKey, RSAKey, ECKey 等)

flattened: ClassVar[bool] = True¶: 表示对象是否为扁平语法

class joserfc.jwe.GeneralJSONEncryption(protected: Dict[str, Any], plaintext: bytes | None = None, unprotected: Dict[str, Any] | None = None, aad: bytes | None = None)¶

一个对象，用于表示 JWE 通用 JSON 序列化。由 encrypt_json 使用，通常由 decrypt_json 方法返回。

构造 GeneralJSONEncryption 对象：

protected = {"enc": "A128CBC-HS256"}
plaintext = b"hello world"
obj = GeneralJSONEncryption(protected, plaintext)
# then add each recipient
obj.add_recipient({"alg": "A128KW"})

向 JWE JSON 序列化添加一个接收者。请添加符合 "alg" 的密钥。

参数:

header -- 接收者自己的（未保护的）header
key -- 一个密钥实例，例如 (OctKey, RSAKey, ECKey 等)

flattened: ClassVar[bool] = False¶: 表示对象是否为扁平语法

class joserfc.jwe.JWERegistry(header_registry: Dict[str, HeaderParameter] | None = None, algorithms: list[str] | None = None, verify_all_recipients: bool = True, strict_check_header: bool = True)¶

一个用于 JSON Web Encryption 的注册表，用于保存所有支持的算法。通常与 joserfc.jwe 中的方法一起使用。

参数:

header_registry -- 额外的 header 参数注册表
algorithms -- 允许使用的算法
verify_all_recipients -- 验证 JSON 序列化中的所有接收者
strict_check_header -- 仅允许使用注册表中的 header 密钥

check_header(header: Dict[str, Any], check_more: bool = False) → None¶: 检查并验证 JWS 对象 header 部分的字段。

get_alg(name: str) → JWEKeyEncryption | JWEKeyWrapping | JWEKeyAgreement | JWEDirectEncryption¶

获取给定名称的允许 ("alg") 算法实例。

参数:: name -- alg 的值，例如 ECDH-ES、A128KW

get_enc(name: str) → JWEEncModel¶

获取给定名称的允许 ("enc") 算法实例。

参数:: name -- enc 的值，例如 A128CBC-HS256、A128GCM

get_zip(name: str) → JWEZipModel¶

获取给定名称的允许 ("zip") 算法实例。

参数:: name -- zip 的值，例如 DEF

class joserfc.jwe.Recipient(parent: CompactEncryption | GeneralJSONEncryption | FlattenedJSONEncryption, header: Dict[str, Any] | None = None, recipient_key: KeyType | None = None)¶

使用给定密钥提取并验证 JWE 紧凑序列化（字符串或字节）。JWE 紧凑序列化如下所示：

仅用于显示目的的换行¶

OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe
ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb
Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV
mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8
1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi
6UklfCpIMfIjf7iGdXKHzg

参数:

value -- JWE 紧凑序列化的字符串（或字节）
private_key -- 用于解密序列化的灵活型私钥
algorithms -- 允许的算法列表
registry -- 要使用的 JWERegistry
sender_key -- 仅在使用 ECDH-1PU 时需要

返回:

CompactEncryption 对象

解密 JWE JSON 序列化（字典形式）为 GeneralJSONEncryption 或 FlattenedJSONEncryption 对象。

参数:

data -- 字典类型的 JWE JSON 序列化
private_key -- 用于解密 CEK 的灵活型私钥
algorithms -- 允许的算法列表
registry -- 要使用的 JWERegistry
sender_key -- 仅在使用 ECDH-1PU 时需要

返回:

GeneralJSONEncryption 或 FlattenedJSONEncryption 的实例

生成 JWE 紧凑序列化。JWE 紧凑序列化将加密内容表示为紧凑的 URL 安全字符串。该字符串如下所示：

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

参数:

protected -- JWE 的受保护 header 部分，字典形式
plaintext -- 要加密的内容（消息）
public_key -- 用于加密 CEK 的公钥
algorithms -- 允许的算法列表
registry -- 要使用的 JWERegistry
sender_key -- 仅在使用 ECDH-1PU 时需要

返回:

JWE 紧凑序列化的字节形式

生成 JWE JSON 序列化（字典形式）。JWE JSON 序列化将加密内容表示为 JSON 对象。此表示既不优化紧凑性，也不 URL 安全。

调用此方法时，开发人员必须构造 GeneralJSONEncryption 或 FlattenedJSONEncryption 对象的实例。以下是一个示例：

from joserfc.jwe import GeneralJSONEncryption

protected = {"enc": "A128CBC-HS256"}
plaintext = b"hello world"
header = {"jku": "https://server.example.com/keys.jwks"}  # optional shared header
obj = GeneralJSONEncryption(protected, plaintext, header)
# add the recipients
obj.add_recipient({"kid": "alice", "alg": "RSA1_5"})  # not configured a key
bob_key = OctKey.import_key("bob secret")
obj.add_recipient({"kid": "bob", "alg": "A128KW"}, bob_key)

参数:

obj -- GeneralJSONEncryption 或 FlattenedJSONEncryption 的实例
public_key -- 用于加密 CEK 的公钥
algorithms -- 允许的算法列表
registry -- 要使用的 JWERegistry
sender_key -- 仅在使用 ECDH-1PU 时需要

返回:

字典类型的 JWE JSON 序列化