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)
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

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")
classmethod import_key(data: str | bytes | Dict[str, str | List[str]], key_type: str | None = None, parameters: KeyParameters | None = None) OctKey | RSAKey | ECKey | OKPKey

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: str, crv_or_size: str | int | None = None, parameters: KeyParameters | None = None, private: bool = True, auto_kid: bool = False) OctKey | RSAKey | ECKey | 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.

joserfc.jwk.guess_key(key: OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], OctKey | RSAKey | ECKey | OKPKey | KeySet], obj: GuestProtocol, use_random: bool = False) OctKey | RSAKey | ECKey | OKPKey

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: str | None = None, parameters: KeyParameters | None = None) OctKey | RSAKey | ECKey | 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_uri(value: Dict[str, Any], digest_method: Literal['sha256', 'sha384', 'sha512'] = 'sha256') str

Calculate JWK thumbprint URI, defined by RFC9278.