Upgrade guide¶
To v3¶
Old signatures will work
Data signed with previous versions (>=2.0, <=3.0) will still be valid.
The biggest change in this version was to drop Python 3.7. Other than that, file-related operations have been normalized internally so that using bytes
always performs better, and the utility functions force_bytes
and force_string
now only accept either bytes
or str
, and raises TypeError
otherwise.
All in all, not very big changes, and thus normal usage is not affected. However, if you were using the utility functions, or had a custom serializer signer, then YMMV.
To v2.5¶
Old signatures will work
Data signed with previous versions (>=2.0, <=2.5) will still be valid.
Now the ExpiredSignatureError
exception contains valid unsigned data, which can be safely used. Check out the example to know more.
Python 3.7 is EOL
As Python 3.7 has reached its end-of-life, this is the last version supporting it.
To v2.4¶
Old signatures will work
Data signed with previous versions (>=2.0, <=2.4) will still be valid.
Both the public and private API of Blake2TimestampSigner for unsign
and unsign_parts
now accepts max_age=None
to omit checking the signature timestamp (but note that there is no default! it has to be explicit). This happens after checking the signature, which must be valid.
Checkout the example for more information.
To v2.3¶
Old signatures will work
Data signed with previous versions (>=2.0, <=2.3) will still be valid.
For the public API, the constructor for signers now accepts as the secret, besides strings or bytes, a sequence of strings or bytes, to allow for secret rotation. This means you don't have to change anything unless you want to start using said feature.
Regarding the private API, a few internal methods were modified to work with this sequence of secrets. Check out the corresponding commit:
5a0b22d5
- ✨ Support secret rotation
To v2.2¶
Old signatures will work
Data signed with previous versions (>=2.0, <=2.2) will still be valid.
No public API was changed, so there's no change for you except that you can now choose to use blake3
.
Regarding the private API, several internal methods of the signers changed, and many were transferred to the BLAKEHasher
class, and subclasses. Check out the corresponding commit and docs:
abd17905
- ✨ Add support for BLAKE3
To v2.1¶
Old signatures will work
Data signed with previous versions (>=2.0, <=2.1) will still be valid.
The default compression level was hardcoded to 6 no matter which compressor was being used. This has changed so that the corresponding default compression level for the compressor is used.
If you were using the Zlib compressor (default), then there's no change for you. However, if you were using the Gzip compressor, the default level will now be 9 instead of 6. To continue using 6 as compression level, change the line calling the corresponding method (dump
, dumps
, or dumps_parts
) and use the parameter compression_level=6
:
from blake2signer import Blake2SerializerSigner
secret = b'secure-secret-that-nobody-knows!'
data = {'user_id': 1, 'is_admin': True, 'username': 'hackan'}
signer = Blake2SerializerSigner(
secret,
personalisation=b'some-signer',
)
# ...
signed = signer.dumps(data, compression_level=6) # Add the compression_level parameter
See the examples for more information.
Moreover, if you have created a custom compressor, then you need to add the default_compression_level
property:
from blake2signer.interfaces import CompressorInterface
class MyCompressor(CompressorInterface):
"""My compressor."""
@property
def default_compression_level(self) -> int:
"""Get the default compression level."""
return 8
...
See the examples for more information.
To v2¶
Generally speaking, v2 broke the public API a bit, so most projects using v1 could probably work as-is with v2. However, the private API changed a lot.
Old signatures will fail
Data signed with previous versions fails with InvalidSignatureError
.
Public API changes¶
Blake2Signer|Blake2TimestampSigner|Blake2SerializerSigner.SEPARATOR
class attribute is replaced by theseparator
instance attribute and is now checked to be ASCII only and not belong to the encoder alphabet.Blake2SerializerSigner.COMPRESSION_FLAG
class attribute is replaced by thecompression_flag
instance attribute and is now checked to be ASCII only.Blake2SerializerSigner.COMPRESSION_RATIO
class attribute is replaced by thecompression_ratio
instance attribute and is now checked to be ASCII only.- The default digest size for all signers is set to 16 bytes. Previously,
Blake2Signer
andBlake2TimestampSigner
defaulted to the maximum allowed size for the hasher. - The compression parameter used in
Blake2SerializerSigner
nameduse_compression
is renamed tocompress
.
Private API changes¶
The private API changed a lot, so if you were using some private methods please review them for changes! Unfortunately I can't list them all here but mainly check these commits:
c6acaa0a
- 🏗 Split classes into own modules by type0b1d0a6c
- ✨ Allow changing encoder in every signerc9bcd173
- ✨ Make separator an instance attribute675389de
- ✨ Make comp flag and ratio an instance attribute8618e663
- ♻ Refactor serializer signer base methods40ccbd40
- ✨ Add new methods to get data and sig separatelyb2d69910
- ♻ Renameuse_compression
tocompress