# 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 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