[](https://gitlab.com/hackancuba/blake2signer/-/commits/develop)
[](https://gitlab.com/hackancuba/blake2signer/-/pipelines?page=1&scope=all&ref=develop)
[](https://blake2signer.hackan.net/en/stable/?badge=stable)
[](https://pypi.org/project/blake2signer)
[](https://pypi.org/project/blake2signer)
[](https://gitlab.com/hackancuba/blake2signer/-/blob/main/LICENSE)
[](https://twitter.com/hackancuba)
#  Blake2Signer
The goal of this project is to provide a simple and straightforward way to securely sign data using [BLAKE in keyed hashing mode](https://docs.python.org/3/library/hashlib.html#keyed-hashing), 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!.
## Why would I need to use it?
* To sign data that needs to be sent through an untrusted channel, like signing a cookie with user data and providing it to the user, so they can identify themselves with the rest of the system safely.
* To save database lookups by checking signed data, like an account activation, or password reset link, where you can sign the user id, and then verify it securely.
* To prevent data tampering, like signing some value that goes in a form hidden field such as the user type (admin, or unprivileged), so that the user can't modify that value.
* To easily express intent when signing data, like sharing a single secret key between signers to simplify app configuration and use the `personalisation` parameter to prevent signed data misuse.
In short, **never trust** user input, **always verify** it. This lib 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 room to become a [footgun](https://en.wiktionary.org/wiki/footgun). All *defaults are very correct* (secure), and everything *just works* out of the box.
If you think this lib doesn't fulfill your requirements, please [leave a feature request](https://gitlab.com/hackancuba/blake2signer/-/issues), and consider using other great libs like [itsdangerous](https://itsdangerous.palletsprojects.com), [Django's signer](https://docs.djangoproject.com/en/dev/topics/signing), [pypaseto](https://github.com/rlittlefield/pypaseto), or [pyjwt](https://github.com/jpadilla/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 [the docs](https://blake2signer.hackan.net/), and in docstrings, so you can always use your IDE's autocompletion, and Python's `help(...)`.
```python
"""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](https://blake2signer.hackan.net/en/stable/examples) for each of the existing features, as well as well-documented [details](https://blake2signer.hackan.net/en/stable/details) about them, so check them out!
Despite this lib being _fast_, there are ways to improve its [performance](https://blake2signer.hackan.net/en/stable/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](https://semver.org/).
* 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](https://pypi.org/project/blake2signer):
* `python3 -m pip install blake2signer`
* `poetry add blake2signer`
* `pipenv install blake2signer`
* `uv add blake2signer`
You can check the [releases' page](https://gitlab.com/hackancuba/blake2signer/-/releases) for package hashes and signatures.
Note: if you want to use BLAKE3, you need to install the [`blake3`](https://pypi.org/project/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
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](https://gitlab.com/hackancuba/blake2signer/-/pipelines)):
* CPython 3.9
* CPython 3.10
* CPython 3.11
* CPython 3.12
* CPython 3.13
* CPython 3.14-pre
* [PyPy](https://www.pypy.org) 3.9
* [PyPy](https://www.pypy.org) 3.10
* [PyPy](https://www.pypy.org) 3.11
Note: If you are contributing to this project under PyPy, [read the contrib notes first](CONTRIB.md#working-under-pypy).
Note: We used to verify support on [Stackless](https://github.com/stackless-dev/stackless/wiki), but the project has been archived, and with Python 3.8 being EOL, we dropped it.
## Signers
This module provides three signer classes:
* **Blake2SerializerSigner**: a signer class that handles data serialization, compression and encoding along with salted signing and salted timestamped signing. Its public methods are `dumps`, `loads`, `dumps_parts` and `loads_parts`, and `dump` and `load` for files.
* **Blake2Signer**: a signer class that signs plain `bytes` or `str` data. Its public methods are `sign`, `unsign`, `sign_parts` and `unsign_parts`.
* **Blake2TimestampSigner**: a signer class that timestamp signs plain `bytes` or `str` data. Its public methods are `sign`, `unsign`, `sign_parts` and `unsign_parts`.
**You should generally go for Blake2SerializerSigner**, given that it's the most versatile of the three, unless you need to deal with plain `bytes` or strings. Check [details about signers](https://blake2signer.hackan.net/en/stable/details) and [usage examples](https://blake2signer.hackan.net/en/stable/examples) to learn more.
## Documentation
Check out this [project docs online](https://blake2signer.hackan.net), or locally with `inv docs`. Alternatively, build them locally using `inv docs --build`.
## Getting help
For help, support, and discussions, come to our [Matrix room](https://matrix.to/#/#blake2signer:mozilla.org). For issues, please use the [Gitlab issue tracker](https://gitlab.com/hackancuba/blake2signer/-/issues).
## Notice
I'm not a cryptoexpert, so *this project needs a security review*. If you are one and can do it, please [contact me](https://hackan.net).
## Contributors
In alphabetical ordering, with short description about contribution:
* [Erus](https://gitlab.com/erudin): docs title logo, code review.
* [NoonSleeper](https://gitlab.com/noonsleeper): project icons, infra.
## License
**Blake2Signer** is made by [HacKan](https://hackan.net) under MPL v2.0. You are free to use, share, modify and share modifications under the terms of that [license](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/.
----
[](https://creativecommons.org/licenses/by-sa/4.0/) *Blake2Signer icons* by [Erus](https://gitlab.com/erudin), originally by [NoonSleeper](https://gitlab.com/noonsleeper) are licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/). You are free to use, share, modify and share modifications under the terms of that [license](https://creativecommons.org/licenses/by-sa/4.0/). They were based on *Blake2Signer logo* by [HacKan](https://hackan.net) which was based on [this sword](https://thenounproject.com/term/samurai-sword/2044449/) by *Hamza Wahbi* and [this signature](https://thenounproject.com/term/sign/184638/) by *Nick Bluth*, both licensed under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/), and inspired by [It's dangerous logo](https://itsdangerous.palletsprojects.com/en/1.1.x/_images/itsdangerous-logo.png).
Check them out in the [icons](https://gitlab.com/hackancuba/blake2signer/-/blob/develop/icons) subdir.
[](https://creativecommons.org/licenses/by-sa/4.0/) *[Blake2Signer with Logo](https://gitlab.com/hackancuba/blake2signer/-/blob/develop/docs/docs/img/title.svg)* by [Erus](https://gitlab.com/erudin) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/). You are free to use, share, modify and share modifications under the terms of that [license](https://creativecommons.org/licenses/by-sa/4.0/). It uses OFL licensed [Bilbo font](https://fontesk.com/bilbo-font).
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/hackancuba/blake2signer",
"name": "blake2signer",
"maintainer": "Erus",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "erudyn@protonmail.com",
"keywords": "blake, crypto, cryptography, digest, hashing, keyed-hashing, mac, signature, signer",
"author": "HacKan",
"author_email": "hackan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ac/51/8b99df8e3461a299144a6d55453ce4ac07d590d83f3e58bd07e27446d96b/blake2signer-4.0.0.tar.gz",
"platform": null,
"description": "[](https://gitlab.com/hackancuba/blake2signer/-/commits/develop)\n[](https://gitlab.com/hackancuba/blake2signer/-/pipelines?page=1&scope=all&ref=develop)\n[](https://blake2signer.hackan.net/en/stable/?badge=stable)\n[](https://pypi.org/project/blake2signer)\n[](https://pypi.org/project/blake2signer)\n[](https://gitlab.com/hackancuba/blake2signer/-/blob/main/LICENSE)\n[](https://twitter.com/hackancuba)\n\n#  Blake2Signer\n\nThe goal of this project is to provide a simple and straightforward way to securely sign data using [BLAKE in keyed hashing mode](https://docs.python.org/3/library/hashlib.html#keyed-hashing), 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!.\n\n## Why would I need to use it?\n\n* To sign data that needs to be sent through an untrusted channel, like signing a cookie with user data and providing it to the user, so they can identify themselves with the rest of the system safely.\n* To save database lookups by checking signed data, like an account activation, or password reset link, where you can sign the user id, and then verify it securely.\n* To prevent data tampering, like signing some value that goes in a form hidden field such as the user type (admin, or unprivileged), so that the user can't modify that value.\n* To easily express intent when signing data, like sharing a single secret key between signers to simplify app configuration and use the `personalisation` parameter to prevent signed data misuse.\n\nIn short, **never trust** user input, **always verify** it. This lib helps you do that.\n\n## Why would I want to use it?\n\nBecause 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 room to become a [footgun](https://en.wiktionary.org/wiki/footgun). All *defaults are very correct* (secure), and everything *just works* out of the box.\n\nIf you think this lib doesn't fulfill your requirements, please [leave a feature request](https://gitlab.com/hackancuba/blake2signer/-/issues), and consider using other great libs like [itsdangerous](https://itsdangerous.palletsprojects.com), [Django's signer](https://docs.djangoproject.com/en/dev/topics/signing), [pypaseto](https://github.com/rlittlefield/pypaseto), or [pyjwt](https://github.com/jpadilla/pyjwt).\n\n## Quickstart\n\nThis 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 [the docs](https://blake2signer.hackan.net/), and in docstrings, so you can always use your IDE's autocompletion, and Python's `help(...)`.\n\n```python\n\"\"\"Quickstart example.\n\nRun with: SECRET=\"some secure and random secret\" python3 quickstart.py\n\nSee `blake2signer.utils.generate_secret` to generate a secure one.\n\"\"\"\nimport os\nfrom datetime import timedelta\n\nfrom blake2signer import Blake2SerializerSigner\nfrom blake2signer import errors\n\nsecret = os.getenv('SECRET') # See `blake2signer.utils.generate_secret`\nassert secret\n\n# Some arbitrary data to sign\ndata = {\n 'user_id': 1,\n 'is_admin': True,\n 'username': 'hackan',\n}\n\nsigner = Blake2SerializerSigner(\n secret,\n max_age=timedelta(days=1), # Set the signature expiration time\n # Use any particular string to distinctly identify this signer (not secret, hardcoded)\n personalisation=b'the-cookie-signer',\n)\n\n# Sign and i.e. store the data in a cookie\nsigned = signer.dumps(data) # Compression is enabled by default\n\n# If compressing data turns out to be detrimental, then data won't be compressed.\n# If you know that from beforehand and don't need compression, you can disable it:\n# signed = signer.dumps(data, compress=False)\n# Additionally, you can force compression nevertheless:\n# signed = signer.dumps(data, force_compression=True)\n\ncookie = {\n 'data': signed,\n}\n\n# To verify and recover data, use `loads`: you will either get the data,\n# or a `SignerError` subclass exception.\ntry:\n unsigned = signer.loads(cookie.get('data', ''))\nexcept errors.SignedDataError:\n # Can't trust on given data\n unsigned = {}\n\nprint(unsigned) # {'user_id': 1, 'is_admin': True, 'username': 'hackan'}\n```\n\nThere are plenty of [examples](https://blake2signer.hackan.net/en/stable/examples) for each of the existing features, as well as well-documented [details](https://blake2signer.hackan.net/en/stable/details) about them, so check them out!\n\nDespite this lib being _fast_, there are ways to improve its [performance](https://blake2signer.hackan.net/en/stable/performance). Check out the respective docs to implement signers the most efficient way possible.\n\n## Goals\n\n* Be safe and secure.\n* Be easy-to-use and straightforward.\n* Follow [semver](https://semver.org/).\n* Be always typed.\n* No dependencies (besides dev).\n* 100% coverage.\n\n### Secondary goals\n\n* If possible, maintain current active Python versions (3.9+).\n* If possible, support Python implementations other than CPython.\n\n## Installing\n\nThis package is hosted on [PyPi](https://pypi.org/project/blake2signer):\n\n* `python3 -m pip install blake2signer`\n* `poetry add blake2signer`\n* `pipenv install blake2signer`\n* `uv add blake2signer`\n\nYou can check the [releases' page](https://gitlab.com/hackancuba/blake2signer/-/releases) for package hashes and signatures.\n\nNote: if you want to use BLAKE3, you need to install the [`blake3`](https://pypi.org/project/blake3/) package, until it arrives to core (which may, or may not happen). Alternatively, you can install this package with extras:\n\n* `python3 -m pip install blake2signer[blake3]`\n* `poetry add blake2signer[blake3]`\n* `pipenv install blake2signer[blake3]`\n* `uv add blake2signer[blake3]`\n\n### Requirements\n\nOnly Python is required; this module doesn't have dependencies besides those used for development, and the optional `blake3`.\n\nVersions currently tested (check the [pipelines](https://gitlab.com/hackancuba/blake2signer/-/pipelines)):\n\n* CPython 3.9\n* CPython 3.10\n* CPython 3.11\n* CPython 3.12\n* CPython 3.13\n* CPython 3.14-pre\n* [PyPy](https://www.pypy.org) 3.9\n* [PyPy](https://www.pypy.org) 3.10\n* [PyPy](https://www.pypy.org) 3.11\n\nNote: If you are contributing to this project under PyPy, [read the contrib notes first](CONTRIB.md#working-under-pypy).\n\nNote: We used to verify support on [Stackless](https://github.com/stackless-dev/stackless/wiki), but the project has been archived, and with Python 3.8 being EOL, we dropped it.\n\n## Signers\n\nThis module provides three signer classes:\n\n* **Blake2SerializerSigner**: a signer class that handles data serialization, compression and encoding along with salted signing and salted timestamped signing. Its public methods are `dumps`, `loads`, `dumps_parts` and `loads_parts`, and `dump` and `load` for files.\n* **Blake2Signer**: a signer class that signs plain `bytes` or `str` data. Its public methods are `sign`, `unsign`, `sign_parts` and `unsign_parts`.\n* **Blake2TimestampSigner**: a signer class that timestamp signs plain `bytes` or `str` data. Its public methods are `sign`, `unsign`, `sign_parts` and `unsign_parts`.\n\n**You should generally go for Blake2SerializerSigner**, given that it's the most versatile of the three, unless you need to deal with plain `bytes` or strings. Check [details about signers](https://blake2signer.hackan.net/en/stable/details) and [usage examples](https://blake2signer.hackan.net/en/stable/examples) to learn more.\n\n## Documentation\n\nCheck out this [project docs online](https://blake2signer.hackan.net), or locally with `inv docs`. Alternatively, build them locally using `inv docs --build`.\n\n## Getting help\n\nFor help, support, and discussions, come to our [Matrix room](https://matrix.to/#/#blake2signer:mozilla.org). For issues, please use the [Gitlab issue tracker](https://gitlab.com/hackancuba/blake2signer/-/issues).\n\n## Notice\n\nI'm not a cryptoexpert, so *this project needs a security review*. If you are one and can do it, please [contact me](https://hackan.net).\n\n## Contributors\n\nIn alphabetical ordering, with short description about contribution:\n\n* [Erus](https://gitlab.com/erudin): docs title logo, code review.\n* [NoonSleeper](https://gitlab.com/noonsleeper): project icons, infra.\n\n## License\n\n**Blake2Signer** is made by [HacKan](https://hackan.net) under MPL v2.0. You are free to use, share, modify and share modifications under the terms of that [license](LICENSE). Derived works may link back to the canonical repository: `https://gitlab.com/hackancuba/blake2signer`.\n\n Copyright (C) 2020-2025 HacKan (https://hackan.net)\n This Source Code Form is subject to the terms of the Mozilla Public\n License, v. 2.0. If a copy of the MPL was not distributed with this\n file, You can obtain one at https://mozilla.org/MPL/2.0/.\n\n----\n\n[](https://creativecommons.org/licenses/by-sa/4.0/) *Blake2Signer icons* by [Erus](https://gitlab.com/erudin), originally by [NoonSleeper](https://gitlab.com/noonsleeper) are licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/). You are free to use, share, modify and share modifications under the terms of that [license](https://creativecommons.org/licenses/by-sa/4.0/). They were based on *Blake2Signer logo* by [HacKan](https://hackan.net) which was based on [this sword](https://thenounproject.com/term/samurai-sword/2044449/) by *Hamza Wahbi* and [this signature](https://thenounproject.com/term/sign/184638/) by *Nick Bluth*, both licensed under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/), and inspired by [It's dangerous logo](https://itsdangerous.palletsprojects.com/en/1.1.x/_images/itsdangerous-logo.png).\n\nCheck them out in the [icons](https://gitlab.com/hackancuba/blake2signer/-/blob/develop/icons) subdir.\n\n[](https://creativecommons.org/licenses/by-sa/4.0/) *[Blake2Signer with Logo](https://gitlab.com/hackancuba/blake2signer/-/blob/develop/docs/docs/img/title.svg)* by [Erus](https://gitlab.com/erudin) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/). You are free to use, share, modify and share modifications under the terms of that [license](https://creativecommons.org/licenses/by-sa/4.0/). It uses OFL licensed [Bilbo font](https://fontesk.com/bilbo-font).\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "A library to use BLAKE in keyed hashing mode to sign and verify signed data",
"version": "4.0.0",
"project_urls": {
"Changelog": "https://blake2signer.hackan.net/en/latest/changelog",
"Documentation": "https://blake2signer.hackan.net",
"Homepage": "https://gitlab.com/hackancuba/blake2signer",
"Issues": "https://gitlab.com/hackancuba/blake2signer/-/issues",
"Repository": "https://gitlab.com/hackancuba/blake2signer"
},
"split_keywords": [
"blake",
" crypto",
" cryptography",
" digest",
" hashing",
" keyed-hashing",
" mac",
" signature",
" signer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d7968c0b1a46233a7669f1f8cc9b59aaf81673c714f70d111bd58c9afe2ff585",
"md5": "d4257f5bfdf6ae3393a7e41d476eadfe",
"sha256": "961412850496d428fa43c21f97f517b7ba294c09df86d06fd765781a4dd40b1f"
},
"downloads": -1,
"filename": "blake2signer-4.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4257f5bfdf6ae3393a7e41d476eadfe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 57754,
"upload_time": "2025-08-22T04:20:49",
"upload_time_iso_8601": "2025-08-22T04:20:49.758273Z",
"url": "https://files.pythonhosted.org/packages/d7/96/8c0b1a46233a7669f1f8cc9b59aaf81673c714f70d111bd58c9afe2ff585/blake2signer-4.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac518b99df8e3461a299144a6d55453ce4ac07d590d83f3e58bd07e27446d96b",
"md5": "b9a9619086e6e5dbb93da63d4ce4947e",
"sha256": "05dc4b01bec0372df6420bae268e06e315d5ed8d9b447d111b11a9931feefa47"
},
"downloads": -1,
"filename": "blake2signer-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b9a9619086e6e5dbb93da63d4ce4947e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 51329,
"upload_time": "2025-08-22T04:20:51",
"upload_time_iso_8601": "2025-08-22T04:20:51.540894Z",
"url": "https://files.pythonhosted.org/packages/ac/51/8b99df8e3461a299144a6d55453ce4ac07d590d83f3e58bd07e27446d96b/blake2signer-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 04:20:51",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "hackancuba",
"gitlab_project": "blake2signer",
"lcname": "blake2signer"
}
JSON