Blake2Signer

The goal of this project is to provide a simple and straightforward way to securely sign data using BLAKE in keyed hashing mode, using a secret key. This can be used, for example, when you need to send some data that could be tampered by the user, like a payment authorization, or a login token. This data goes as plaintext, and can be read, but it can't be modified in any way once signed!.

Looking for another documentation version?

Check out stable (current tagged version), latest (current development version) or each tagged version.

Have questions?

For help, support, and discussions, come to our Matrix room.

Why would I need to use it?

To sign data that needs to be sent through an untrusted channel

You may want to provide a cookie to a user so that your system can know that they are authorized. However, you must sign that cookie, otherwise an attacker may change its value to trick the system into thinking they are logged in, or may likewise impersonate another user.
This is a common scenario where the server needs to provide a value, and then read it back from the user. With this lib, you can sign said value, and verify the signature when read so that you know it wasn't tampered with.

To save database lookups by checking signed data

When you need to activate a user account, or generate a password reset, you can sign the account id, and send a link to the user, so that you can verify it by unsigning it: this saves generating a one-time token, or other similar processes that requires database lookups, and write operations.

To easily express intent when signing data

When you need to sign different data in your app, you can create different signers using a single secret (simplified app configuration): just set the personalisation value of each signer uniquely, as shown in the examples. This ensures that a value signed by a signer can't be unsigned by another signer: i.e. a malicious user can't use their signed id value for account reset to upgrade their account plan.

To prevent data tampering

When you need to store some value in a form but then need to act upon it, i.e. indicating if a user is an admin or regular user in a hidden field, then you must sign said value to prevent a malicious user tampering it.

In short, never trust user input, always verify it. This lib helps you do that.

Why would I want to use it?

Small, easy-to-use, customizable, and fast

Because it is a relatively small (around 900 logical lines of code, core around 400), easy-to-use (the public API has only a couple of methods) yet very customizable, and fast data signer. My idea is to keep it as uncomplicated as possible without room to become a footgun. All defaults are very correct (secure), and everything just works out of the box.

Other alternatives to this lib?

If you think this lib doesn't fulfill your requirements, please leave a feature request, and consider using other great libs like itsdangerous, Django's signer, pypaseto, or pyjwt.

Quickstart

This lib has been designed to be easy-to-use with many knobs to provide adaptability, but safe defaults, and limits to prevent footguns. All methods, classes and functions are properly documented in these docs, and in docstrings, so you can always use your IDE's autocompletion, and Python's help(...).

Quickstart Example

"""Quickstart example.

Run with: SECRET="some secure and random secret" python3 quickstart.py

See `blake2signer.utils.generate_secret` to generate a secure one.
"""
import os
from datetime import timedelta

from blake2signer import Blake2SerializerSigner
from blake2signer import errors

secret = os.getenv('SECRET')  # See `blake2signer.utils.generate_secret`
assert secret

# Some arbitrary data to sign
data = {
    'user_id': 1,
    'is_admin': True,
    'username': 'hackan',
}

signer = Blake2SerializerSigner(
    secret,
    max_age=timedelta(days=1),  # Set the signature expiration time
    # Use any particular string to distinctly identify this signer (not secret, hardcoded)
    personalisation=b'the-cookie-signer',
)

# Sign and i.e. store the data in a cookie
signed = signer.dumps(data)  # Compression is enabled by default

# If compressing data turns out to be detrimental, then data won't be compressed.
# If you know that from beforehand and don't need compression, you can disable it:
# signed = signer.dumps(data, compress=False)
# Additionally, you can force compression nevertheless:
# signed = signer.dumps(data, force_compression=True)

cookie = {
    'data': signed,
}

# To verify and recover data, use `loads`: you will either get the data,
# or a `SignerError` subclass exception.
try:
    unsigned = signer.loads(cookie.get('data', ''))
except errors.SignedDataError:
    # Can't trust on given data
    unsigned = {}

print(unsigned)  # {'user_id': 1, 'is_admin': True, 'username': 'hackan'}

There are plenty of examples for each of the existing features, as well as well-documented details about them, so check them out!

Better performance

Despite this lib being fast, there are ways to improve its performance. Check out the respective docs to implement signers the most efficient way possible.

Goals

• Be safe and secure.
• Be easy-to-use and straightforward.
• Follow semver.
• Be always typed.
• No dependencies (besides dev).
• 100% coverage.

Secondary goals

• If possible, maintain current active Python versions (3.9+).
• If possible, support Python implementations other than CPython.

Installing

This package is hosted on PyPi:

• python3 -m pip install blake2signer
• poetry add blake2signer
• pipenv install blake2signer
• uv add blake2signer

You can check the releases' page for package hashes and signatures.

Using BLAKE3 (needs optional dependency)

If you want to use BLAKE3, you need to install the blake3 package, until it arrives to core (which may, or may not happen). Alternatively, you can install this package with extras:

• python3 -m pip install blake2signer[blake3]
• poetry add blake2signer[blake3]
• pipenv install blake2signer[blake3]
• uv add blake2signer[blake3]

Requirements

Info

Only Python is required; this module doesn't have dependencies besides those used for development, and the optional blake3.

Versions currently tested (check the pipelines):

• CPython 3.9
• CPython 3.10
• CPython 3.11
• CPython 3.12
• CPython 3.13
• CPython 3.14-pre
• PyPy 3.9
• PyPy 3.10
• PyPy 3.11

PyPy

If you are contributing to this project under PyPy, read the contrib notes first.

What happened with Stackless?

We used to verify support on Stackless, but the project has been archived, and with Python 3.8 being EOL, we dropped it.

Documentation

These docs are generously hosted by ReadTheDocs. Check the project page to know more and see different versions of these docs.

There are two major documentation versions, besides each tagged version: stable (current tagged version), and latest (current development version).

Getting help

For help, support, and discussions, come to our Matrix room. For issues, please use the Gitlab issue tracker.

Notice

I'm not a cryptoexpert, so this project needs a security review. If you are one and can do it, please contact me.

Contributors

In alphabetical ordering, with short description about contribution:

• Erus: docs title logo, code review.
• NoonSleeper: project icons, infra.

License

Blake2Signer is made by HacKan under MPL v2.0. You are free to use, share, modify and share modifications under the terms of that license. Derived works may link back to the canonical repository: https://gitlab.com/hackancuba/blake2signer.

Copyright (C) 2020-2025 HacKan (https://hackan.net)
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at https://mozilla.org/MPL/2.0/.

---

Blake2Signer icons by NoonSleeper are licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. You are free to use, share, modify and share modifications under the terms of that license. They were based on Blake2Signer logo by HacKan which was based on this sword by Hamza Wahbi and this signature by Nick Bluth, both licensed under CC BY 3.0, and inspired by It's dangerous logo.
Check them out in the icons subdir.

Blake2Signer with Logo by Erus is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. You are free to use, share, modify and share modifications under the terms of that license. It uses OFL licensed Bilbo font.