RFC7515: JSON Web Signature¶

API Reference¶

class authlib.jose.JsonWebSignature(algorithms=None, private_headers=None)¶

REGISTERED_HEADER_PARAMETER_NAMES = frozenset({'x5u', 'crit', 'x5c', 'jwk', 'kid', 'cty', 'jku', 'x5t#S256', 'alg', 'x5t', 'typ'})¶

Registered Header Parameter Names defined by Section 4.1

ALGORITHMS_REGISTRY = {'ES256': <authlib.jose.rfc7518._cryptography_backends._jws.ECAlgorithm object>, 'ES384': <authlib.jose.rfc7518._cryptography_backends._jws.ECAlgorithm object>, 'ES512': <authlib.jose.rfc7518._cryptography_backends._jws.ECAlgorithm object>, 'EdDSA': <authlib.jose.rfc8037._jws_cryptography.EdDSAAlgorithm object>, 'HS256': <authlib.jose.rfc7518.jws_algorithms.HMACAlgorithm object>, 'HS384': <authlib.jose.rfc7518.jws_algorithms.HMACAlgorithm object>, 'HS512': <authlib.jose.rfc7518.jws_algorithms.HMACAlgorithm object>, 'PS256': <authlib.jose.rfc7518._cryptography_backends._jws.RSAPSSAlgorithm object>, 'PS384': <authlib.jose.rfc7518._cryptography_backends._jws.RSAPSSAlgorithm object>, 'PS512': <authlib.jose.rfc7518._cryptography_backends._jws.RSAPSSAlgorithm object>, 'RS256': <authlib.jose.rfc7518._cryptography_backends._jws.RSAAlgorithm object>, 'RS384': <authlib.jose.rfc7518._cryptography_backends._jws.RSAAlgorithm object>, 'RS512': <authlib.jose.rfc7518._cryptography_backends._jws.RSAAlgorithm object>, 'none': <authlib.jose.rfc7518.jws_algorithms.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