# ItsDangerous

Sometimes you want to send some data to untrusted environments, then get it back later. To do this safely, the data must be signed to detect changes.

Given a key only you know, you can cryptographically sign your data and hand it over to someone else. When you get the data back you can ensure that nobody tampered with it.

The receiver can see the data, but they can not modify it unless they also have your key. So if you keep the key secret and complex, you will be fine.

## Installing

Install and update using pip:

    pip install -U itsdangerous

## Example Use Cases

- Sign a user ID in a URL and email it to them to unsubscribe from a newsletter. This way you don’t need to generate one-time tokens and store them in the database. Same thing with any kind of activation link for accounts and similar things.

- Signed objects can be stored in cookies or other untrusted sources which means you don’t need to have sessions stored on the server, which reduces the number of necessary database queries.

- Signed information can safely do a round trip between server and client in general which makes them useful for passing server-side state to a client and then back.

## Table of Contents

- General Concepts
  - Serializer vs Signer
  - The Secret Key
  - The Salt
  - Key Rotation
  - Digest Method Security
- Serialization Interface
  - Responding to Failure
  - Fallback Signers
  - API
    - `Serializer`
      - `Serializer.default_serializer`
      - `Serializer.default_signer`
      - `Serializer.default_fallback_signers`
      - `Serializer.secret_keys`
      - `Serializer.secret_key`
      - `Serializer.load_payload()`
      - `Serializer.dump_payload()`
      - `Serializer.make_signer()`
      - `Serializer.iter_unsigners()`
      - `Serializer.dumps()`
      - `Serializer.dump()`
      - `Serializer.loads()`
      - `Serializer.load()`
      - `Serializer.loads_unsafe()`
      - `Serializer.load_unsafe()`
- Signing Interface
  - `Signer`
    - `Signer.default_digest_method()`
    - `Signer.default_key_derivation`
    - `Signer.secret_keys`
    - `Signer.secret_key`
    - `Signer.derive_key()`
    - `Signer.get_signature()`
    - `Signer.sign()`
    - `Signer.verify_signature()`
    - `Signer.unsign()`
    - `Signer.validate()`
  - Signing Algorithms
    - `NoneAlgorithm`
    - `HMACAlgorithm`
- Exceptions
  - `BadData`
  - `BadSignature`
    - `BadSignature.payload`
  - `BadTimeSignature`
    - `BadTimeSignature.date_signed`
  - `SignatureExpired`
  - `BadHeader`
    - `BadHeader.header`
    - `BadHeader.original_error`
  - `BadPayload`
    - `BadPayload.original_error`
- Signing With Timestamps
  - `TimestampSigner`
    - `TimestampSigner.get_timestamp()`
    - `TimestampSigner.timestamp_to_datetime()`
    - `TimestampSigner.sign()`
    - `TimestampSigner.unsign()`
    - `TimestampSigner.validate()`
  - `TimedSerializer`
    - `TimedSerializer.default_signer`
    - `TimedSerializer.iter_unsigners()`
    - `TimedSerializer.loads()`
    - `TimedSerializer.loads_unsafe()`
- URL Safe Serialization
  - `URLSafeSerializer`
  - `URLSafeTimedSerializer`
- Encoding Utilities
  - `base64_encode()`
  - `base64_decode()`
- BSD-3-Clause License
- Changes
  - Version 2.2.0
  - Version 2.1.2
  - Version 2.1.1
  - Version 2.1.0
  - Version 2.0.1
  - Version 2.0.0
  - Version 1.1.0
  - Version 1.0.0
  - Version 0.24
  - Version 0.23
  - Version 0.22
  - Version 0.21
  - Version 0.20
  - Version 0.19
  - Version 0.18
  - Version 0.17
  - Version 0.16
  - Version 0.15
  - Version 0.14
  - Version 0.13
  - Version 0.12
  - Version 0.11
  - Version 0.10