Skip to content

Blake2Signer

Blake2Signer

The goal of this project is to provide a simple and straightforward way to securely sign data using BLAKE in keyed hashing mode.

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 700 logical lines of code), 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.

Goals

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

Installing

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]

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

Documentation

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

Notice

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

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, 2021, 2022 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/.

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.

Back to top