RFC7515: JSON Web Signature#

This section contains the generic implementation of RFC7515. Find how to use it in JWS Guide.

API Reference#

class authlib.jose.JsonWebSignature(algorithms=None, private_headers=None)#
REGISTERED_HEADER_PARAMETER_NAMES = frozenset({'alg', 'crit', 'cty', 'jku', 'jwk', 'kid', 'typ', 'x5c', 'x5t', 'x5t#S256', 'x5u'})#

Registered Header Parameter Names defined by Section 4.1

ALGORITHMS_REGISTRY = {'ES256': <authlib.jose.rfc7518.jws_algs.ECAlgorithm object>, 'ES256K': <authlib.jose.rfc7518.jws_algs.ECAlgorithm object>, 'ES384': <authlib.jose.rfc7518.jws_algs.ECAlgorithm object>, 'ES512': <authlib.jose.rfc7518.jws_algs.ECAlgorithm object>, 'EdDSA': <authlib.jose.rfc8037.jws_eddsa.EdDSAAlgorithm object>, 'HS256': <authlib.jose.rfc7518.jws_algs.HMACAlgorithm object>, 'HS384': <authlib.jose.rfc7518.jws_algs.HMACAlgorithm object>, 'HS512': <authlib.jose.rfc7518.jws_algs.HMACAlgorithm object>, 'PS256': <authlib.jose.rfc7518.jws_algs.RSAPSSAlgorithm object>, 'PS384': <authlib.jose.rfc7518.jws_algs.RSAPSSAlgorithm object>, 'PS512': <authlib.jose.rfc7518.jws_algs.RSAPSSAlgorithm object>, 'RS256': <authlib.jose.rfc7518.jws_algs.RSAAlgorithm object>, 'RS384': <authlib.jose.rfc7518.jws_algs.RSAAlgorithm object>, 'RS512': <authlib.jose.rfc7518.jws_algs.RSAAlgorithm object>, 'none': <authlib.jose.rfc7518.jws_algs.NoneAlgorithm object>}#

Defined available JWS algorithms in the registry

serialize_compact(protected, payload, key)#

Generate a JWS Compact Serialization. The JWS Compact Serialization represents digitally signed or MACed content as a compact, URL-safe string, per Section 7.1.

BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload) || '.' ||
BASE64URL(JWS Signature)
Parameters:

  • protected – A dict of protected header

  • payload – A bytes/string of payload

  • key – Private key used to generate signature

Returns:

byte

deserialize_compact(s, key, decode=None)#

Exact JWS Compact Serialization, and validate with the given key. If key is not provided, the returned dict will contain the signature, and signing input values. Via Section 7.1.

Parameters:

  • s – text of JWS Compact Serialization

  • key – key used to verify the signature

  • decode – a function to decode payload data

Returns:

JWSObject

Raise:

BadSignatureError

serialize_json(header_obj, payload, key)#

Generate a JWS JSON Serialization. The JWS JSON Serialization represents digitally signed or MACed content as a JSON object, per Section 7.2.

Parameters:

  • header_obj – A dict/list of header

  • payload – A string/dict of payload

  • key – Private key used to generate signature

Returns:

JWSObject

Example header_obj of JWS JSON Serialization:

{
    "protected: {"alg": "HS256"},
    "header": {"kid": "jose"}
}

Pass a dict to generate flattened JSON Serialization, pass a list of header dict to generate standard JSON Serialization.

deserialize_json(obj, key, decode=None)#

Exact JWS JSON Serialization, and validate with the given key. If key is not provided, it will return a dict without signature verification. Header will still be validated. Via Section 7.2.

Parameters:

  • obj – text of JWS JSON Serialization

  • key – key used to verify the signature

  • decode – a function to decode payload data

Returns:

JWSObject

Raise:

BadSignatureError

serialize(header, payload, key)#

Generate a JWS Serialization. It will automatically generate a Compact or JSON Serialization depending on the given header. If a header is in a JSON header format, it will call serialize_json(), otherwise it will call serialize_compact().

Parameters:

  • header – A dict/list of header

  • payload – A string/dict of payload

  • key – Private key used to generate signature

Returns:

byte/dict

deserialize(s, key, decode=None)#

Deserialize JWS Serialization, both compact and JSON format. It will automatically deserialize depending on the given JWS.

Parameters:

  • s – text of JWS Compact/JSON Serialization

  • key – key used to verify the signature

  • decode – a function to decode payload data

Returns:

dict

Raise:

BadSignatureError

If key is not provided, it will still deserialize the serialization without verification.

class authlib.jose.JWSHeader(protected, header)#

Header object for JWS. It combine the protected header and unprotected header together. JWSHeader itself is a dict of the combined dict. e.g.

>>> protected = {"alg": "HS256"}
>>> header = {"kid": "a"}
>>> jws_header = JWSHeader(protected, header)
>>> print(jws_header)
{'alg': 'HS256', 'kid': 'a'}
>>> jws_header.protected == protected
>>> jws_header.header == header
Parameters:

  • protected – dict of protected header

  • header – dict of unprotected header

class authlib.jose.JWSObject(header, payload, type='compact')#

A dict instance to represent a JWS object.

class authlib.jose.JWSAlgorithm#

Interface for JWS algorithm. JWA specification (RFC7518) SHOULD implement the algorithms for JWS with this base implementation.

prepare_key(raw_data)#

Prepare key for signing and verifying signature.

sign(msg, key)#

Sign the text msg with a private/sign key.

Parameters:

  • msg – message bytes to be signed

  • key – private key to sign the message

Returns:

bytes

verify(msg, sig, key)#

Verify the signature of text msg with a public/verify key.

Parameters:

  • msg – message bytes to be signed

  • sig – result signature to be compared

  • key – public key to verify the signature

Returns:

boolean