# Signing Interface

The most basic interface is the signing interface. The `Signer` class can be used to attach a signature to a specific string:

    from itsdangerous import Signer
    s = Signer("secret-key")
    s.sign("my string")
    b'my string.wh6tMHxLgJqB6oY1uT73iMlyrOA'

The signature is appended to the string, separated by a dot. To validate the string, use the `unsign()` method:

    s.unsign(b"my string.wh6tMHxLgJqB6oY1uT73iMlyrOA")
    b'my string'

If unicode strings are provided, an implicit encoding to UTF-8 happens. However after unsigning you won’t be able to tell if it was unicode or a bytestring.

If the value is changed, the signature will no longer match, and unsigning will raise a `BadSignature` exception:

    s.unsign(b"different string.wh6tMHxLgJqB6oY1uT73iMlyrOA")
    Traceback (most recent call last):
      ...
    BadSignature: Signature does not match

To record and validate the age of a signature, see Signing With Timestamps.

class itsdangerous.signer.Signer(secret_key, salt=b'itsdangerous.Signer', sep=b'.', key_derivation=None, digest_method=None, algorithm=None)

  A signer securely signs bytes, then unsigns them to verify that the value hasn’t been changed.

  The secret key should be a random string of `bytes` and should not be saved to code or version control. Different salts should be used to distinguish signing in different contexts. See General Concepts for information about the security of the secret key and salt.

  Parameters:

    - secret_key (str | bytes | cabc.Iterable[str] | cabc.Iterable[bytes]) – The secret key to sign and verify with. Can be a list of keys, oldest to newest, to support key rotation.

    - salt (str | bytes | None) – Extra key to combine with `secret_key` to distinguish signatures in different contexts.

    - sep (str | bytes) – Separator between the signature and value.

    - key_derivation (str | None) – How to derive the signing key from the secret key and salt. Possible values are `concat`, `django-concat`, or `hmac`. Defaults to `default_key_derivation`, which defaults to `django-concat`.

    - digest_method (t.Any | None) – Hash function to use when generating the HMAC signature. Defaults to `default_digest_method`, which defaults to `hashlib.sha1()`. Note that the security of the hash alone doesn’t apply when used intermediately in HMAC.

    - algorithm (SigningAlgorithm | None) – A `SigningAlgorithm` instance to use instead of building a default `HMACAlgorithm` with the `digest_method`.

  Changelog

  Changed in version 2.0: Added support for key rotation by passing a list to `secret_key`.

  Changed in version 0.18: `algorithm` was added as an argument to the class constructor.

  Changed in version 0.14: `key_derivation` and `digest_method` were added as arguments to the class constructor.

  static default_digest_method(string=b'')

    The default digest method to use for the signer. The default is `hashlib.sha1()`, but can be changed to any `hashlib` or compatible object. Note that the security of the hash alone doesn’t apply when used intermediately in HMAC.

    Changelog

    Added in version 0.14.

    Parameters:

      string (bytes)

    Return type:

      Any

  default_key_derivation: str = 'django-concat'

    The default scheme to use to derive the signing key from the secret key and salt. The default is `django-concat`. Possible values are `concat`, `django-concat`, and `hmac`.

    Changelog

    Added in version 0.14.

  secret_keys: list[bytes]

    The list of secret keys to try for verifying signatures, from oldest to newest. The newest (last) key is used for signing.

    This allows a key rotation system to keep a list of allowed keys and remove expired ones.

  property secret_key: bytes

    The newest (last) entry in the `secret_keys` list. This is for compatibility from before key rotation support was added.

  derive_key(secret_key=None)

    This method is called to derive the key. The default key derivation choices can be overridden here. Key derivation is not intended to be used as a security method to make a complex key out of a short password. Instead you should use large random secret keys.

    Parameters:

      secret_key (str | bytes | None) – A specific secret key to derive from. Defaults to the last item in `secret_keys`.

    Return type:

      bytes

    Changelog

    Changed in version 2.0: Added the `secret_key` parameter.

  get_signature(value)

    Returns the signature for the given value.

    Parameters:

      value (str | bytes)

    Return type:

      bytes

  sign(value)

    Signs the given string.

    Parameters:

      value (str | bytes)

    Return type:

      bytes

  verify_signature(value, sig)

    Verifies the signature for the given value.

    Parameters:

      - value (str | bytes)

      - sig (str | bytes)

    Return type:

      bool

  unsign(signed_value)

    Unsigns the given string.

    Parameters:

      signed_value (str | bytes)

    Return type:

      bytes

  validate(signed_value)

    Only validates the given signed value. Returns `True` if the signature exists and is valid.

    Parameters:

      signed_value (str | bytes)

    Return type:

      bool

## Signing Algorithms

class itsdangerous.signer.NoneAlgorithm

  Provides an algorithm that does not perform any signing and returns an empty signature.

class itsdangerous.signer.HMACAlgorithm(digest_method=None)

  Provides signature generation using HMACs.

  Parameters:

    digest_method (Any)