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 -- determine whether this method should output private key or not
params -- other parameters added into this key

触发:

ValueError

check_alg(alg: str) → None¶

Check if this key supports the given "alg".

参数:: alg -- the algorithm this key is intended to be used, e.g. "HS256", "ECDH-EC"
触发:: UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None¶

Check if the given key_op is supported by this key.

参数:: operation -- key operation value, such as "sign", "encrypt".
触发:: UnsupportedKeyOperationError

check_use(use: str) → None¶

Check if this key supports the given "use".

Values defined by this specification are:

"sig" (signature)
"enc" (encryption)

Other values MAY be used. The "use" value is a case-sensitive string. Use of the "use" member is OPTIONAL, unless the application requires its presence.

参数:: use -- this key is used for, e.g. "sig", "enc"
触发:: UnsupportedKeyUseError

property dict_value: dict[str, str | list[str]]¶: Property of the Key in Dict (JSON).

ensure_kid() → None¶: Ensure this key has a kid. If kid is not provided by default, it will generate the kid with .thumbprint method, which is defined by 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)

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

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

从字节、字符串和字典导入密钥的类方法。当 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 -- determine whether this method should output private key or not
params -- other parameters added into this key

触发:

ValueError

check_alg(alg: str) → None¶

Check if this key supports the given "alg".

参数:: alg -- the algorithm this key is intended to be used, e.g. "HS256", "ECDH-EC"
触发:: UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None¶

Check if the given key_op is supported by this key.

参数:: operation -- key operation value, such as "sign", "encrypt".
触发:: UnsupportedKeyOperationError

check_use(use: str) → None¶

Check if this key supports the given "use".

Values defined by this specification are:

"sig" (signature)
"enc" (encryption)

Other values MAY be used. The "use" value is a case-sensitive string. Use of the "use" member is OPTIONAL, unless the application requires its presence.

参数:: use -- this key is used for, e.g. "sig", "enc"
触发:: UnsupportedKeyUseError

property dict_value: dict[str, str | list[str]]¶: Property of the Key in Dict (JSON).

ensure_kid() → None¶: Ensure this key has a kid. If kid is not provided by default, it will generate the kid with .thumbprint method, which is defined by 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 -- determine whether this method should output private key or not
params -- other parameters added into this key

触发:

ValueError

check_alg(alg: str) → None¶

Check if this key supports the given "alg".

参数:: alg -- the algorithm this key is intended to be used, e.g. "HS256", "ECDH-EC"
触发:: UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None¶

Check if the given key_op is supported by this key.

参数:: operation -- key operation value, such as "sign", "encrypt".
触发:: UnsupportedKeyOperationError

check_use(use: str) → None¶

Check if this key supports the given "use".

Values defined by this specification are:

"sig" (signature)
"enc" (encryption)

Other values MAY be used. The "use" value is a case-sensitive string. Use of the "use" member is OPTIONAL, unless the application requires its presence.

参数:: use -- this key is used for, e.g. "sig", "enc"
触发:: UnsupportedKeyUseError

property dict_value: dict[str, str | list[str]]¶: Property of the Key in Dict (JSON).

ensure_kid() → None¶: Ensure this key has a kid. If kid is not provided by default, it will generate the kid with .thumbprint method, which is defined by 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¶: A symmetric key will always be private.

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¶: The raw key in 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 -- determine whether this method should output private key or not
params -- other parameters added into this key

触发:

ValueError

check_alg(alg: str) → None¶

Check if this key supports the given "alg".

参数:: alg -- the algorithm this key is intended to be used, e.g. "HS256", "ECDH-EC"
触发:: UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None¶

Check if the given key_op is supported by this key.

参数:: operation -- key operation value, such as "sign", "encrypt".
触发:: UnsupportedKeyOperationError

check_use(use: str) → None¶

Check if this key supports the given "use".

Values defined by this specification are:

"sig" (signature)
"enc" (encryption)

Other values MAY be used. The "use" value is a case-sensitive string. Use of the "use" member is OPTIONAL, unless the application requires its presence.

参数:: use -- this key is used for, e.g. "sig", "enc"
触发:: UnsupportedKeyUseError

property dict_value: dict[str, str | list[str]]¶: Property of the Key in Dict (JSON).

ensure_kid() → None¶: Ensure this key has a kid. If kid is not provided by default, it will generate the kid with .thumbprint method, which is defined by 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: Generating key according to the given key type. When key_type is "oct" and "RSA", the second parameter SHOULD be a key size in bits. When key_type is "EC" and "OKP", the second parameter SHOULD be a "crv" string.

从各种来源猜测密钥。

参数:

key -- 非常灵活的密钥
obj -- 具有 headers 和 set_kid 方法的协议
random -- 从密钥集中随机选择一个密钥
use -- optional "use" value

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

Importing a key from bytes, string, and dict. When value is a dict, this method can tell the key type automatically, otherwise, developers SHOULD pass the key_type themselves.

参数:

data -- 字节、字符串或字典形式的密钥数据。
key_type -- 可选的密钥类型字符串。
parameters -- 额外的密钥参数

返回:

OctKey、RSAKey、ECKey 或 OKPKey

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

Calculate the thumbprint value of a Key, per 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¶

Calculate JWK thumbprint URI, defined by RFC9278.

from joserfc import jwk

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