JWS API¶

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

class joserfc.jws.CompactSignature(protected: Dict[str, Any], payload: bytes)¶: 用于紧凑模式的 JSON Web Signature 对象。此对象用于表示 JWS 实例。

class joserfc.jws.FlattenedJSONSerialization¶

class joserfc.jws.FlattenedJSONSignature(member: HeaderMember, payload: bytes)¶

表示扁平 JSON 序列化的 JSON Signature 对象。

flattened: ClassVar[bool] = True¶: 标记为扁平

member¶: 唯一的 header 成员

payload¶: 有效载荷内容

class joserfc.jws.GeneralJSONSerialization¶

class joserfc.jws.GeneralJSONSignature(members: list[HeaderMember], payload: bytes)¶

表示通用 JSON 序列化的 JSON Signature 对象。

flattened: ClassVar[bool] = False¶: 标记为非扁平（通用）

members¶: header 成员列表

payload¶: 有效载荷内容

class joserfc.jws.HeaderDict¶

class joserfc.jws.HeaderMember(protected: Dict[str, Any] | None = None, header: Dict[str, Any] | None = None)¶

JSON 签名的 header 成员。它由受保护和未保护的 header 组成。

header¶: 未保护的 header

protected¶: 受保护的 header

class joserfc.jws.JWSAlgModel¶

JWS 算法接口。JWA 规范 (RFC7518) 应使用此基础实现来实现 JWS 的算法。

abstractmethod sign(msg: bytes, key: Any) → bytes¶

使用私钥/签名密钥签署文本消息。

参数:

msg -- 要签名的消息字节
key -- 用于签名消息的私钥

返回:

字节

abstractmethod verify(msg: bytes, sig: bytes, key: Any) → bool¶

使用公钥/验证密钥验证文本消息的签名。

参数:

msg -- 要签名的消息字节
sig -- 要比较的结果签名
key -- 用于验证签名的公钥

返回:

布尔值

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

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

参数:

header_registry -- 额外的 header 参数注册表
algorithms -- 允许使用的算法
strict_check_header -- 仅允许使用注册表中的 header 密钥

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

get_alg(name: str) → JWSAlgModel¶

获取给定名称的允许算法实例。

参数:: name -- alg 的值，例如 HS256、RS256

classmethod register(alg: JWSAlgModel) → None¶: 将给定的 JWS 算法实例注册到注册表。

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

仅用于显示目的的换行¶

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

参数:

value -- JWS 紧凑序列化的字符串（或字节）
public_key -- 用于验证签名的灵活公钥
algorithms -- 允许的算法列表
registry -- 要使用的 JWSRegistry

返回:

CompactSignature 对象

使用给定密钥提取并验证 JWS（字符串形式）。

参数:

value -- 字典形式的 JSON Signature
public_key -- 用于验证签名的灵活公钥
algorithms -- 允许的算法列表
registry -- 要使用的 JWSRegistry

返回:

SignatureData 对象

触发:

ValueError 或 BadSignatureError

joserfc.jws.detach_content(value: DetachValue) → DetachValue¶

在某些情况下，保护不包含在 JWS 中的内容的完整性是有用的。此方法是 https://www.rfc-editor.org/rfc/rfc7515#appendix-F 的实现

用于分离紧凑和 JSON 序列化内容。

>>> from joserfc import jws
>>> from joserfc.jwk import OctKey
>>> key = OctKey.import_key("secret")
>>> encoded_text = jws.serialize_compact({"alg": "HS256"}, b"hello", key)
>>> jws.detach_content(encoded_text)
'eyJhbGciOiJIUzI1NiJ9..UYmO_lPAY5V0Wf4KZsfhiYs1SxqXPhxvjuYqellDV5A'

您还可以分离 JSON 序列化：

>>> obj = jws.serialize_json({"protected": {"alg": "HS256"}}, b"hello", key)
>>> jws.detach_content(obj)
{
    'payload': '',
    'signature': 'UYmO_lPAY5V0Wf4KZsfhiYs1SxqXPhxvjuYqellDV5A',
    'protected': 'eyJhbGciOiJIUzI1NiJ9'
}

joserfc.jws.extract_compact(value: bytes) → CompactSignature¶

从字节中提取 JWS 紧凑序列化为对象。

参数:: value -- 字节形式的 JWS
触发:: DecodeError

生成 JWS 紧凑序列化。JWS 紧凑序列化将数字签名或 MAC 内容表示为紧凑的 URL 安全字符串，参见第 7.1 节。

BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload) || '.' ||
BASE64URL(JWS Signature)

参数:

protected -- JWS 的受保护 header 部分，字典形式
payload -- JWS 的有效载荷数据，字节形式
private_key -- 用于签名的灵活私钥
algorithms -- 允许的算法列表
registry -- 要使用的 JWSRegistry

返回:

字符串形式的 JWS

生成 JWS JSON 序列化（字典形式）。JWS JSON 序列化将数字签名或 MAC 内容表示为 JSON 对象。此表示既不优化紧凑性，也不 URL 安全。

通用 JWS JSON 序列化包含：

有效载荷: “有效载荷”成员必须存在，并包含值 BASE64URL(JWS Payload)。
签名: “签名”成员值必须是 JSON 对象数组。每个对象表示 JWS 有效载荷和 JWS 受保护 header 的签名或 MAC。

扁平 JWS JSON 序列化如下所示：

{
    "payload":"<payload contents>",
    "protected":"<integrity-protected header contents>",
    "header":<non-integrity-protected header contents>,
    "signature":"<signature contents>"
}

使用给定密钥验证 JWS 紧凑序列化。此方法通常与 extract_compact 一起使用。

参数:

obj -- JWS 紧凑序列化的对象
public_key -- 用于验证签名的灵活公钥
algorithms -- 允许的算法列表
registry -- 要使用的 JWSRegistry