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._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 callserialize_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
-