JSON Web Key (JWK)¶

The jwk Module implements the JSON Web Key standard. A JSON Web Key is represented by a JWK object, related utility classes and functions are availbale in this module too.

Classes¶

class jwcrypto.jwk.JWK(**kwargs)¶

Bases: object

JSON Web Key object

This object represent a Key. It must be instantiated by using the standard defined key/value pairs as arguents of the initialization function.

Creates a new JWK object.

The function arguments must be valid parameters as defined in the ‘IANA JSON Web Key Set Parameters registry’ and specified in the JWKParamsRegistry variable. The ‘kty’ parameter must always be provided and its value must be a valid one as defined by the ‘IANA JSON Web Key Types registry’ and specified in the JWKTypesRegistry variable. The valid key parameters per key type are defined in the JWKValuesregistry variable.

To generate a new random key call the class method generate() with the appropriate ‘kty’ parameter, and other parameters as needed (key size, public exponents, curve types, etc..)

Valid options per type, when generating new keys:

oct: size(int)
RSA: public_exponent(int), size(int)
EC: curve(str) (one of P-256, P-384, P-521)

Deprecated: Alternatively if the ‘generate’ parameter is provided, with a valid key type as value then a new key will be generated according to the defaults or provided key strenght options (type specific).

Raises:	InvalidJWKType – if the key type is invalid InvalidJWKValue – if incorrect or inconsistent parameters are provided.

export(private_key=True)¶

Exports the key in the standard JSON format.

Parameters:	private_key(bool) – Whether to export the private key. Defaults to True.

export_public()¶: Exports the public key in the standard JSON format. This function is deprecated and maintained only for backwards compatibility, use export(private_key=False) instead.

get_curve(arg)¶

Gets the Elliptic Curve associated with the key.

Parameters:	arg – an optional curve name
Raises:	InvalidJWKType – the key is not an EC key. InvalidJWKValue – if the curve names is invalid.

get_op_key(operation=None, arg=None)¶

Get the key object associated to the requested opration. For example the public RSA key for the ‘verify’ operation or the private EC key for the ‘decrypt’ operation.

Parameters:	operation – The requested operation. The valid set of operations is availble in the `JWKOperationsRegistry` registry. arg – an optional, context specific, argument For example a curve name.
Raises:	InvalidJWKOperation – if the operation is unknown or not permitted with this key. InvalidJWKUsage – if the use constraints do not permit the operation.

thumbprint(hashalg=<cryptography.hazmat.primitives.hashes.SHA256 object>)¶

Returns the key thumbprint as specified by RFC 7638.

Parameters:	hashalg – A hash function (defaults to SHA256)

key_curve¶: The Curve Name.

key_id¶: The Key ID. Provided by the kid parameter if present, otherwise returns None.

key_type¶: The Key type

class jwcrypto.jwk.JWKSet(*args, **kwargs)¶

Bases: dict

A set of JWK objects.

Inherits from the standard ‘dict’ bultin type. Creates a special key ‘keys’ that is of a type derived from ‘set’ The ‘keys’ attribute accepts only jwcrypto.jwk.JWK elements.

export(private_keys=True)¶

Exports a RFC 7517 keyset using the standard JSON format

Parameters:	private_key(bool) – Whether to export private keys. Defaults to True.

classmethod from_json(keyset)¶

Creates a RFC 7517 keyset from the standard JSON format.

Parameters:	keyset – The RFC 7517 representation of a JOSE Keyset.

get_key(kid)¶: Gets a key from the set. :param kid: the ‘kid’ key identifier.

import_keyset(keyset)¶

Imports a RFC 7517 keyset using the standard JSON format.

Parameters:	keyset – The RFC 7517 representation of a JOSE Keyset.

Exceptions¶

class jwcrypto.jwk.InvalidJWKType(value=None)¶

Bases: exceptions.Exception

Invalid JWK Type Exception.

This exception is raised when an invalid parameter type is used.

class jwcrypto.jwk.InvalidJWKValue¶

Bases: exceptions.Exception

Invalid JWK Value Exception.

This exception is raised when an invalid/unknown value is used in the context of an operation that requires specific values to be used based on the key type or other constraints.

class jwcrypto.jwk.InvalidJWKOperation(operation, values)¶

Bases: exceptions.Exception

Invalid JWK Operation Exception.

This exception is raised when an invalid key operation is requested, based on the key type and declared usage constraints.

class jwcrypto.jwk.InvalidJWKUsage(use, value)¶

Bases: exceptions.Exception

Invalid JWK usage Exception.

This exception is raised when an invalid key usage is requested, based on the key type and declared usage constraints.

Registries¶

jwcrypto.jwk.JWKTypesRegistry¶: Registry of valid Key Types

jwcrypto.jwk.JWKValuesRegistry¶: Registry of valid key values

jwcrypto.jwk.JWKParamsRegistry¶: Regstry of valid key parameters

jwcrypto.jwk.JWKEllipticCurveRegistry¶: Registry of allowed Elliptic Curves

jwcrypto.jwk.JWKUseRegistry¶: Registry of allowed uses

jwcrypto.jwk.JWKOperationsRegistry¶: Registry of allowed operations

Examples¶

Create a 256bit symmetric key::

>>> from jwcrypto import jwk
>>> key = jwk.JWK.generate(kty='oct', size=256)

Export the key with::

>>> key.export()
'{"k":"X6TBlwY2so8EwKZ2TFXM7XHSgWBKQJhcspzYydp5Y-o","kty":"oct"}'

Create a 2048bit RSA keypair::

>>> jwk.JWK.generate(kty='RSA', size=2048)

Create a P-256 EC keypair and export the public key::

>>> key = jwk.JWK.generate(kty='EC', crv='P-256')
>>> key.export(private_key=False)
'{"y":"VYlYwBfOTIICojCPfdUjnmkpN-g-lzZKxzjAoFmDRm8",
  "x":"3mdE0rODWRju6qqU01Kw5oPYdNxBOMisFvJFH1vEu9Q",
  "crv":"P-256","kty":"EC"}'

Import a P-256 Public Key::

>>> expkey = {"y":"VYlYwBfOTIICojCPfdUjnmkpN-g-lzZKxzjAoFmDRm8",
              "x":"3mdE0rODWRju6qqU01Kw5oPYdNxBOMisFvJFH1vEu9Q",
              "crv":"P-256","kty":"EC"}
>>> key = jwk.JWK(**expkey)