JWK API

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

class joserfc.jwk.ECKey(raw_value: NativePrivateKey | NativePublicKey, original_value: Any, parameters: KeyParameters | None = None)

property alg: str | None

The "alg" value of the JSON Web Key.

as_dict(private: bool | None = None, **params: Any) → dict[str, str | list[str]]

Output this key to a JWK format (in dict). By default, it will return the dict_value of this key.

参数:

• private -- 确定此方法是否应输出私钥

• params -- 添加到此密钥的其他参数

触发:

ValueError

check_alg(alg: str) → None

检查此密钥是否支持给定的 "alg"。

参数:

alg -- 此密钥预期使用的算法，例如 "HS256"、"ECDH-EC"

触发:

UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None

检查此密钥是否支持给定的 key_op。

参数:

operation -- 密钥操作的值，例如 "sign"、"encrypt"。

触发:

UnsupportedKeyOperationError

check_use(use: str) → None

检查此密钥是否支持给定的 "use"。

Values defined by this specification are:

• "sig" (签名)

• "enc" (加密)

可以使用其他值。"use" 值区分大小写。除非应用程序要求其存在，否则 "use" 成员是可选的。

参数:

use -- 此密钥用于，例如 "sig"、"enc"

触发:

UnsupportedKeyUseError

property dict_value: dict[str, str | list[str]]

字典形式（JSON）的密钥的属性值。

ensure_kid() → None

确保此密钥具有 kid。如果默认未提供 kid，将使用 .thumbprint 方法生成 kid，该方法由 RFC7638 定义。

classmethod generate_key(crv: str | None = 'P-256', parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) → ECKey

生成具有给定 "crv" 值的 ECKey。

参数:

• crv -- ECKey 曲线名称

• parameters -- JWK 中的额外参数

• private -- 生成私钥或公钥

• auto_kid -- 自动添加 kid

property kid: str | None

The "kid" value of the JSON Web Key.

thumbprint() → str

Call this method will generate the thumbprint with algorithm defined in RFC7638.

thumbprint_uri() → str

Call this method will generate the thumbprint URI defined in RFC9278.

value_registry: t.ClassVar[KeyParameterRegistryDict] = {'crv': <joserfc.registry.KeyParameter object>, 'd': <joserfc.registry.KeyParameter object>, 'x': <joserfc.registry.KeyParameter object>, 'y': <joserfc.registry.KeyParameter object>}

EC 密钥注册表定义 https://www.rfc-editor.org/rfc/rfc7518#section-6.2

class joserfc.jwk.GuestProtocol(*args, **kwargs)

class joserfc.jwk.JWKRegistry

JWK 的注册表，用于记录 joserfc 支持的密钥类型。通常，您会使用显式密钥类型，如 OctKey、RSAKey；此注册表提供了一种动态导入和生成密钥的方法。例如：

from joserfc.jwk import JWKRegistry

# instead of choosing which key type to use yourself,
# JWKRegistry can import it automatically
data = {"kty": "oct", "k": "..."}
key = JWKRegistry.import_key(data)

classmethod generate_key(key_type: str, crv_or_size: str | int | None = None, parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) → OctKey | RSAKey | ECKey | OKPKey

根据给定的密钥类型生成密钥的类方法。当 key_type 为 "oct" 和 "RSA" 时，第二个参数应为位大小。当 key_type 为 "EC" 和 "OKP" 时，第二个参数应为 "crv" 字符串。

JWKRegistry.generate_key("RSA", 2048)
JWKRegistry.generate_key("EC", "P-256")

classmethod import_key(data: str | bytes | dict[str, str | list[str]], key_type: str | None = None, parameters: KeyParameters | None = None) → OctKey | RSAKey | ECKey | OKPKey

从字节、字符串和字典导入密钥的类方法。当 value 为字典时，此方法可以自动识别密钥类型，否则，开发人员应自行传递 key_type。

参数:

• data -- 字节、字符串或字典形式的密钥数据。

• key_type -- 可选的密钥类型字符串。

• parameters -- 额外的密钥参数

返回:

OctKey、RSAKey、ECKey 或 OKPKey

class joserfc.jwk.KeyParameters

clear() → None.  Remove all items from D.

copy() → a shallow copy of D

classmethod fromkeys(iterable, value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class joserfc.jwk.KeySetSerialization

clear() → None.  Remove all items from D.

copy() → a shallow copy of D

classmethod fromkeys(iterable, value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class joserfc.jwk.OKPKey(raw_value: NativePrivateKey | NativePublicKey, original_value: Any, parameters: KeyParameters | None = None)

OKP 密钥类型的密钥类。

property alg: str | None

The "alg" value of the JSON Web Key.

as_dict(private: bool | None = None, **params: Any) → dict[str, str | list[str]]

Output this key to a JWK format (in dict). By default, it will return the dict_value of this key.

参数:

• private -- 确定此方法是否应输出私钥

• params -- 添加到此密钥的其他参数

触发:

ValueError

check_alg(alg: str) → None

检查此密钥是否支持给定的 "alg"。

参数:

alg -- 此密钥预期使用的算法，例如 "HS256"、"ECDH-EC"

触发:

UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None

检查此密钥是否支持给定的 key_op。

参数:

operation -- 密钥操作的值，例如 "sign"、"encrypt"。

触发:

UnsupportedKeyOperationError

check_use(use: str) → None

检查此密钥是否支持给定的 "use"。

Values defined by this specification are:

• "sig" (签名)

• "enc" (加密)

可以使用其他值。"use" 值区分大小写。除非应用程序要求其存在，否则 "use" 成员是可选的。

参数:

use -- 此密钥用于，例如 "sig"、"enc"

触发:

UnsupportedKeyUseError

property dict_value: dict[str, str | list[str]]

字典形式（JSON）的密钥的属性值。

ensure_kid() → None

确保此密钥具有 kid。如果默认未提供 kid，将使用 .thumbprint 方法生成 kid，该方法由 RFC7638 定义。

classmethod generate_key(crv: str | None = 'Ed25519', parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) → OKPKey

生成具有给定 "crv" 值的 OKPKey。

参数:

• crv -- OKPKey 曲线名称

• parameters -- JWK 中的额外参数

• private -- 生成私钥或公钥

• auto_kid -- 自动添加 kid

property kid: str | None

The "kid" value of the JSON Web Key.

thumbprint() → str

Call this method will generate the thumbprint with algorithm defined in RFC7638.

thumbprint_uri() → str

Call this method will generate the thumbprint URI defined in RFC9278.

value_registry: t.ClassVar[KeyParameterRegistryDict] = {'crv': <joserfc.registry.KeyParameter object>, 'd': <joserfc.registry.KeyParameter object>, 'x': <joserfc.registry.KeyParameter object>}

OKP 密钥注册表定义 https://www.rfc-editor.org/rfc/rfc8037#section-2

class joserfc.jwk.OctKey(raw_value: NativePrivateKey | NativePublicKey, original_value: Any, parameters: KeyParameters | None = None)

OctKey 是对称密钥，由 RFC7518 第 6.4 节定义。

property alg: str | None

The "alg" value of the JSON Web Key.

as_dict(private: bool | None = None, **params: Any) → dict[str, str | list[str]]

Output this key to a JWK format (in dict). By default, it will return the dict_value of this key.

参数:

• private -- 确定此方法是否应输出私钥

• params -- 添加到此密钥的其他参数

触发:

ValueError

check_alg(alg: str) → None

检查此密钥是否支持给定的 "alg"。

参数:

alg -- 此密钥预期使用的算法，例如 "HS256"、"ECDH-EC"

触发:

UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None

检查此密钥是否支持给定的 key_op。

参数:

operation -- 密钥操作的值，例如 "sign"、"encrypt"。

触发:

UnsupportedKeyOperationError

check_use(use: str) → None

检查此密钥是否支持给定的 "use"。

Values defined by this specification are:

• "sig" (签名)

• "enc" (加密)

可以使用其他值。"use" 值区分大小写。除非应用程序要求其存在，否则 "use" 成员是可选的。

参数:

use -- 此密钥用于，例如 "sig"、"enc"

触发:

UnsupportedKeyUseError

property dict_value: dict[str, str | list[str]]

字典形式（JSON）的密钥的属性值。

ensure_kid() → None

确保此密钥具有 kid。如果默认未提供 kid，将使用 .thumbprint 方法生成 kid，该方法由 RFC7638 定义。

classmethod generate_key(key_size: int | None = 256, parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) → OctKey

生成具有给定位大小（不是字节）的 OctKey。

参数:

• key_size -- 位大小

• parameters -- JWK 中的额外参数

• private -- 必须为 True

• auto_kid -- 自动添加 kid

property is_private: bool

对称密钥始终是私有的。

property kid: str | None

The "kid" value of the JSON Web Key.

property private_key: bytes

Returns the raw_value as the private key.

property public_key: bytes

Returns the raw_value as the public key.

property raw_value: bytes

原始密钥，字节形式。

thumbprint() → str

Call this method will generate the thumbprint with algorithm defined in RFC7638.

thumbprint_uri() → str

Call this method will generate the thumbprint URI defined in RFC9278.

value_registry: t.ClassVar[KeyParameterRegistryDict] = {'k': <joserfc.registry.KeyParameter object>}

https://www.rfc-editor.org/rfc/rfc7518#section-6.4

class joserfc.jwk.RSAKey(raw_value: NativePrivateKey | NativePublicKey, original_value: Any, parameters: KeyParameters | None = None)

property alg: str | None

The "alg" value of the JSON Web Key.

as_dict(private: bool | None = None, **params: Any) → dict[str, str | list[str]]

Output this key to a JWK format (in dict). By default, it will return the dict_value of this key.

参数:

• private -- 确定此方法是否应输出私钥

• params -- 添加到此密钥的其他参数

触发:

ValueError

check_alg(alg: str) → None

检查此密钥是否支持给定的 "alg"。

参数:

alg -- 此密钥预期使用的算法，例如 "HS256"、"ECDH-EC"

触发:

UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None

检查此密钥是否支持给定的 key_op。

参数:

operation -- 密钥操作的值，例如 "sign"、"encrypt"。

触发:

UnsupportedKeyOperationError

check_use(use: str) → None

检查此密钥是否支持给定的 "use"。

Values defined by this specification are:

• "sig" (签名)

• "enc" (加密)

可以使用其他值。"use" 值区分大小写。除非应用程序要求其存在，否则 "use" 成员是可选的。

参数:

use -- 此密钥用于，例如 "sig"、"enc"

触发:

UnsupportedKeyUseError

property dict_value: dict[str, str | list[str]]

字典形式（JSON）的密钥的属性值。

ensure_kid() → None

确保此密钥具有 kid。如果默认未提供 kid，将使用 .thumbprint 方法生成 kid，该方法由 RFC7638 定义。

classmethod generate_key(key_size: int | None = 2048, parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) → RSAKey

生成具有给定位大小（不是字节）的 RSAKey。

参数:

• key_size -- 位大小

• parameters -- JWK 中的额外参数

• private -- 生成私钥或公钥

• auto_kid -- 自动添加 kid

property kid: str | None

The "kid" value of the JSON Web Key.

thumbprint() → str

Call this method will generate the thumbprint with algorithm defined in RFC7638.

thumbprint_uri() → str

Call this method will generate the thumbprint URI defined in RFC9278.

value_registry: t.ClassVar[KeyParameterRegistryDict] = {'d': <joserfc.registry.KeyParameter object>, 'dp': <joserfc.registry.KeyParameter object>, 'dq': <joserfc.registry.KeyParameter object>, 'e': <joserfc.registry.KeyParameter object>, 'n': <joserfc.registry.KeyParameter object>, 'oth': <joserfc.registry.KeyParameter object>, 'p': <joserfc.registry.KeyParameter object>, 'q': <joserfc.registry.KeyParameter object>, 'qi': <joserfc.registry.KeyParameter object>}

RSA 密钥注册表定义 https://www.rfc-editor.org/rfc/rfc7518#section-6.3

joserfc.jwk.generate_key(key_type: Literal['oct'], crv_or_size: int | None = None, parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) → OctKey

joserfc.jwk.generate_key(key_type: Literal['RSA'], crv_or_size: int | None = None, parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) → RSAKey

joserfc.jwk.generate_key(key_type: Literal['EC'], crv_or_size: Literal['P-256', 'P-384', 'P-521', 'secp256k1'] | None = None, parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) → ECKey

joserfc.jwk.generate_key(key_type: Literal['OKP'], crv_or_size: Literal['Ed25519', 'Ed448', 'X25519', 'X448'] | None = None, parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) → OKPKey

根据给定的密钥类型生成密钥。当 key_type 为 "oct" 或 "RSA" 时，第二个参数应为以位为单位的密钥长度。当 key_type 为 "EC" 或 "OKP" 时，第二个参数应为 "crv" 字符串。

joserfc.jwk.guess_key(key: OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], OctKey | RSAKey | ECKey | OKPKey | KeySet], obj: GuestProtocol, random: bool = False, use: Literal['sig', 'enc'] | None = None) → OctKey | RSAKey | ECKey | OKPKey

从各种来源猜测密钥。

参数:

• key -- 非常灵活的密钥

• obj -- 具有 headers 和 set_kid 方法的协议

• random -- 从密钥集中随机选择一个密钥

• use -- 可选的 "use" 值

joserfc.jwk.import_key(data: str | bytes | dict[str, str | list[str]], key_type: Literal['oct'], parameters: KeyParameters | None = None) → OctKey

joserfc.jwk.import_key(data: str | bytes | dict[str, str | list[str]], key_type: Literal['RSA'], parameters: KeyParameters | None = None) → RSAKey

joserfc.jwk.import_key(data: str | bytes | dict[str, str | list[str]], key_type: Literal['EC'], parameters: KeyParameters | None = None) → ECKey

joserfc.jwk.import_key(data: str | bytes | dict[str, str | list[str]], key_type: Literal['OKP'], parameters: KeyParameters | None = None) → OKPKey

joserfc.jwk.import_key(data: dict[str, str | list[str]], key_type: None = None, parameters: KeyParameters | None = None) → OctKey | RSAKey | ECKey | OKPKey

从字节、字符串或字典导入密钥。当 value 是字典时，该方法可以自动识别密钥类型，否则开发者应自行传入 key_type。

参数:

• data -- 字节、字符串或字典形式的密钥数据。

• key_type -- 可选的密钥类型字符串。

• parameters -- 额外的密钥参数

返回:

OctKey、RSAKey、ECKey 或 OKPKey

joserfc.jwk.thumbprint(value: dict[str, Any], digest_method: Literal['sha256', 'sha384', 'sha512'] = 'sha256') → str

根据 RFC 7638 计算密钥的指纹值。

from joserfc import jwk

jwk.thumbprint({
    'kty': 'oct',
    'k': 'sTBpI_oCHSyW-n0exSwhzNHwU9FGRioPauxWA84bnRU',
})
# 'DCdRGGDKvhAJgmVlCp6tosc2T9ELtd30S_15vn8bhrI'

joserfc.jwk.thumbprint_uri(value: dict[str, Any], digest_method: Literal['sha256', 'sha384', 'sha512'] = 'sha256') → str

根据 RFC9278 计算 JWK 指纹值的 URI。

from joserfc import jwk

jwk.thumbprint({
    'kty': 'oct',
    'k': 'sTBpI_oCHSyW-n0exSwhzNHwU9FGRioPauxWA84bnRU',
})
# 'urn:ietf:params:oauth:jwk-thumbprint:sha-256:DCdRGGDKvhAJgmVlCp6tosc2T9ELtd30S_15vn8bhrI'