JWK API¶

This part of the documentation covers all the interfaces of 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.

Parameters:

private – determine whether this method should output private key or not
params – other parameters added into this key

Raise:

ValueError

check_alg(alg: str) → None¶

Check if this key supports the given “alg”.

Parameters:: alg – the algorithm this key is intended to be used, e.g. “HS256”, “ECDH-EC”
Raise:: UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None¶

Check if the given key_op is supported by this key.

Parameters:: operation – key operation value, such as “sign”, “encrypt”.
Raise:: UnsupportedKeyOperationError

check_use(use: str) → None¶

Check if this key supports the given “use”.

Parameters:: use – this key is used for, e.g. “sig”, “enc”
Raise:: 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¶

Generate a ECKey with the given “crv” value.

Parameters:

crv – ECKey curve name
parameters – extra parameter in JWK
private – generate a private key or public key
auto_kid – add kid automatically

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>}¶: Registry definition for EC Key https://www.rfc-editor.org/rfc/rfc7518#section-6.2

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

class joserfc.jwk.JWKRegistry¶

A registry for JWK to record joserfc supported key types. Normally, you would use explicit key types like OctKey, RSAKey; This registry provides a way to dynamically import and generate keys. For instance:

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)

A class method for 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.

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

A class method for 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.

Parameters:

data – the key data in bytes, string, or dict.
key_type – an optional key type in string.
parameters – extra key parameters

Returns:

OctKey, RSAKey, ECKey, or 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)¶

Key class of the OKP key type.

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.

Parameters:

private – determine whether this method should output private key or not
params – other parameters added into this key

Raise:

ValueError

check_alg(alg: str) → None¶

Check if this key supports the given “alg”.

Parameters:: alg – the algorithm this key is intended to be used, e.g. “HS256”, “ECDH-EC”
Raise:: UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None¶

Check if the given key_op is supported by this key.

Parameters:: operation – key operation value, such as “sign”, “encrypt”.
Raise:: UnsupportedKeyOperationError

check_use(use: str) → None¶

Check if this key supports the given “use”.

Parameters:: use – this key is used for, e.g. “sig”, “enc”
Raise:: 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¶

Generate a OKPKey with the given “crv” value.

Parameters:

crv – OKPKey curve name
parameters – extra parameter in JWK
private – generate a private key or public key
auto_kid – add kid automatically

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>}¶: Registry definition for OKP Key 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 is a symmetric key, defined by RFC7518 Section 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.

Parameters:

private – determine whether this method should output private key or not
params – other parameters added into this key

Raise:

ValueError

check_alg(alg: str) → None¶

Check if this key supports the given “alg”.

Parameters:: alg – the algorithm this key is intended to be used, e.g. “HS256”, “ECDH-EC”
Raise:: UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None¶

Check if the given key_op is supported by this key.

Parameters:: operation – key operation value, such as “sign”, “encrypt”.
Raise:: UnsupportedKeyOperationError

check_use(use: str) → None¶

Check if this key supports the given “use”.

Parameters:: use – this key is used for, e.g. “sig”, “enc”
Raise:: 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¶

Generate a OctKey with the given bit size (not bytes).

Parameters:

key_size – size in bit
parameters – extra parameter in JWK
private – must be True
auto_kid – add kid automatically

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.

Parameters:

private – determine whether this method should output private key or not
params – other parameters added into this key

Raise:

ValueError

check_alg(alg: str) → None¶

Check if this key supports the given “alg”.

Parameters:: alg – the algorithm this key is intended to be used, e.g. “HS256”, “ECDH-EC”
Raise:: UnsupportedKeyAlgorithmError

check_key_op(operation: str) → None¶

Check if the given key_op is supported by this key.

Parameters:: operation – key operation value, such as “sign”, “encrypt”.
Raise:: UnsupportedKeyOperationError

check_use(use: str) → None¶

Check if this key supports the given “use”.

Parameters:: use – this key is used for, e.g. “sig”, “enc”
Raise:: 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¶

Generate a RSAKey with the given bit size (not bytes).

Parameters:

key_size – size in bit
parameters – extra parameter in JWK
private – generate a private key or public key
auto_kid – add kid automatically

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>}¶: Registry definition for RSA Key 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.

Guess key from a various sources.

Parameters:

key – a very flexible key
obj – a protocol that has headers and set_kid methods
use_random – pick a random key from key set

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.

Parameters:

data – the key data in bytes, string, or dict.
key_type – an optional key type in string.
parameters – extra key parameters

Returns:

OctKey, RSAKey, ECKey, or 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'