Core Signers — Aquilia Documentation
Comprehensive guide and documentation for Core Signers in the Aquilia framework. View API reference, examples, and implementation patterns.
SIGNING SYSTEM / CORE SIGNERS Core Signer Classes Discover the primary APIs for cryptographic signing: the stateless Signer class and the time-aware TimestampSigner. Signer API Reference The Signer class verifies simple string values. The output signature is appended as a Base64 block separated by a specified character (default :). class Signer: def __init__(self, secret: str | bytes | None = None, *, salt: str = "aquilia.signing", sep: str = ":", algorithm: str = "HS256", backend: SignerBackend | None = None) def sign(self, value: str) -> str: """Sign value and return ' : '.""" def unsign(self, signed_value: str) -> str: """Verify signature and return original value. Raises BadSignature on mismatch.""" def sign_bytes(self, data: bytes) -> bytes: """Sign binary blobs and return raw data + separator + signature.""" def unsign_bytes(self, signed_data: bytes) -> bytes: """Verify binary signature and return original bytes.""" def sign_object(self, obj: Any) -> str: """Serialise a JSON-compatible Python object, sign, and encode.""" def unsign_object(self, token: str) -> Any: """Verify signature and deserialise the JSON payload.""" TimestampSigner API Reference The TimestampSigner class embeds a UTC timestamp in microsecond precision (offset from 2020-01-01) inside the payload before signing. This enables enforcing token lifetimes at verification time. class TimestampSigner(Signer): def __init__(self, secret: str | bytes | None = None, *, salt: str = "aquilia.signing.ts", sep: str = ":", algorithm: str = "HS256", backend: SignerBackend | None = None) def sign(self, value: str, *, timestamp: datetime | None = None) -> str: """Sign value with an embedded timestamp.""" def unsign(self, signed_value: str, max_age: float | int | timedelta | None = None) -> str: """Verify signature and enforce age. Raises SignatureExpired if older than max_age.""" def unsign_with_timestamp(self, signed_value: str, max_age: float | int | timedelta | None = None) -> tuple[str, datetime]: """Verify signature and return tuple of (original_value, datetime_when_signed).""" Scenario Walkthroughs Scenario 1: Basic String Verification Verify stateless data elements passed in query parameters or custom HTTP headers: from aquilia.signing import Signer, BadSignature # 1. Initialize signer with a master key signer = Signer(secret="my-super-secret-key-32-bytes-minimum") # 2. Sign a username string signed_token = signer.sign("john_doe") print(signed_token) # e.g. "john_doe:aBcDeFgHiJ..." # 3. Verify signature on read try: username = signer.unsign(signed_token) except BadSignature: print("Tampered token detected!") Scenario 2: Binary Blob Integrity Maintain serialization integrity of binary objects, e.g. signed pickle payloads or encrypted files: import pickle from aquilia.signing import Signer signer = Signer(secret="my-super-secret-key-32-bytes-minimum") data = pickle_data = pickle.dumps(data) # Sign binary bytes signed_payload = signer.sign_bytes(pickle_data) # Unsign binary bytes and deserialize original_bytes = signer.unsign_bytes(signed_payload) restored_data = pickle.loads(original_bytes) Scenario 3: Expirable Tokens Enforce age validation on cryptographic signatures, automatically discarding tokens older than a set duration: import time from aquilia.signing import TimestampSigner, SignatureExpired, BadSignature ts = TimestampSigner(secret="my-super-secret-key-32-bytes-minimum") # Sign token (embeds current time) token = ts.sign("premium_user") # Sleep to simulate delay time.sleep(5) # Verify with max_age restriction (3 seconds) try: user = ts.unsign(token, max_age=3) except SignatureExpired as exc: print(f"Token expired! Signed at: ") except BadSignature: print("Invalid signature!") Overview Specialized Signers )
Go to Homepage