Upgrade guide¶
To v2.5¶
Old signatures will work
Data signed with previous versions (>=2.0, <=2.4) will still be valid.
Now the ExpiredSignatureError
exception contains valid unsigned data, which can be safely used. Check out the example to know more.
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 examples.
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 accept as the secret, besides string or bytes, a sequence of string 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