Skip to content



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, in 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 travels in 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.

Why would I need to use it?

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

When a user logs into your system, you may want to provide that user a cookie so that every operation in the system can know that they are logged in. 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 package 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, and then 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. This module helps you do that.

Why would I want to use it?

Because it is a relatively small (around 900 logical lines of code, core around 400), simple (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 much room to become a footgun. All defaults are very sane (secure) and everything just works out of the box.

There are much better packages for other or more general use cases so if you feel this doesn't satisfy your needs please leave a feature request or consider using itsdangerous, Django's signer, pypaseto, pyjwt or others like those.


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

Secondary goals

  • If possible, maintain current active Python versions (3.7+).


This package is hosted on PyPi so just:

  • python3 -m pip install blake2signer
  • poetry add blake2signer
  • pipenv install 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]



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):


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).


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


In alphabetical ordering, with short description about contribution:


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:

Copyright (C) 2020, 2021, 2022 HacKan (
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

CC BY-SA 4.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.

CC BY-SA 4.0 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.