RFC7515: JSON Web Signature

This section contains the generic implementation of RFC 7515. 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 RFC 7515 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 RFC 7515 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 RFC 7515 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 RFC 7515 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