Signer

This class provides mechanisms for securely signing and unsigning values to ensure data integrity and prevent tampering. It supports HMAC-based signatures with customizable algorithms, separators, and salts, while also offering support for key rotation through fallback keys. Additionally, it includes methods for signing complex objects using serialization and optional zlib compression.

Attributes

Attribute	Type	Description
key	string = settings.SECRET_KEY	The primary secret key used for generating HMAC signatures.
fallback_keys	list of strings = settings.SECRET_KEY_FALLBACKS	A list of additional secret keys used to validate signatures if the primary key fails.
sep	string = ":"	The separator string used to join the original value and its signature, which cannot be empty or consist solely of URL-safe characters.
salt	string = "self.class.module.Signer"	A string used to create a unique namespace for the signature to prevent collisions across different parts of the application.
algorithm	string = "sha256"	The hashing algorithm used by the HMAC function to generate the signature.

---

Constructor

Signature

def Signer(
    key: string | bytes | None = None,
    sep: string = ":",
    salt: string | None = None,
    algorithm: string | None = None,
    fallback_keys: list[string | bytes]| None = None
)

Parameters

Name	Type	Description
key	`string	bytes
sep	string = ":"	The separator used between the value and the signature.
salt	`string	None` = None
algorithm	`string	None` = None
fallback_keys	`list[string	bytes]

---

Signature

def Signer(
    key: string = None,
    sep: string = ":",
    salt: string = None,
    algorithm: string = None,
    fallback_keys: list = None
) - > null

Parameters

Name	Type	Description
key	string = None	The primary secret key used for generating HMAC signatures; defaults to the project secret key.
sep	string = ":"	The character used to separate the original value from its signature; must not be alphanumeric or URL-safe characters.
salt	string = None	A unique string used to salt the HMAC to prevent cross-application signature collisions.
algorithm	string = None	The hashing algorithm to use for the signature, defaulting to sha256.
fallback_keys	list = None	A list of secondary keys to attempt during unsigning if the primary key fails.

---

Methods

---

signature()

@classmethod
def signature(
    value: string,
    key: string = None
) - > string

Generates a base64-encoded HMAC signature for a given value using the specified or default key.

Parameters

Name	Type	Description
value	string	The raw string content that needs to be signed.
key	string = None	An optional specific key to use for this signature operation instead of the instance's primary key.

Returns

Type	Description
string	The base64-encoded HMAC signature string.

---

sign()

@classmethod
def sign(
    value: string
) - > string

Appends a cryptographic signature to a value, joined by the configured separator.

Parameters

Name	Type	Description
value	string	The string value to be signed.

Returns

Type	Description
string	The signed string containing the original value, the separator, and the signature.

---

unsign()

@classmethod
def unsign(
    signed_value: string
) - > string

Verifies the signature of a signed value and returns the original content if valid. Raises BadSignature if the separator is missing or the signature does not match any known keys.

Parameters

Name	Type	Description
signed_value	string	The signed string containing both the value and the HMAC signature.

Returns

Type	Description
string	The original value with the signature removed.

---

sign_object()

@classmethod
def sign_object(
    obj: any,
    serializer: class = JSONSerializer,
    compress: boolean = False
) - > string

Return URL-safe, hmac signed base64 compressed JSON string. If compress is True (not the default), check if compressing using zlib can save some space. Prepend a '.' to signify compression. This is included in the signature, to protect against zip bombs. The serializer is expected to return a bytestring.

Parameters

Name	Type	Description
obj	any	The Python object to serialize and sign.
serializer	class = JSONSerializer	The serialization class used to convert the object into a bytestring.
compress	boolean = False	Whether to attempt zlib compression on the serialized data to reduce output size.

Returns

Type	Description
string	A signed, base64-encoded string representing the serialized (and optionally compressed) object.

---

unsign_object()

@classmethod
def unsign_object(
    signed_obj: string,
    serializer: class = JSONSerializer,
    **kwargs: dict
) - > any

Verifies a signed object string, handles optional decompression, and deserializes it back into a Python object.

Parameters

Name	Type	Description
signed_obj	string	The signed, base64-encoded string produced by sign_object.
serializer	class = JSONSerializer	The serialization class used to decode the bytestring back into an object.
**kwargs	dict	Additional keyword arguments passed to the unsign method.

Returns

Type	Description
any	The deserialized Python object recovered from the signed string.

---