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
. Ifkid
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 likeOctKey
,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. Whenkey_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 thekey_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
. Ifkid
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
. Ifkid
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>}¶
- 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
. Ifkid
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. Whenkey_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
andset_kid
methodsuse_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 thekey_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.