Signing — Aquilia Documentation
Comprehensive guide and documentation for Signing in the Aquilia framework. View API reference, examples, and implementation patterns.
SIGNING SYSTEM / OVERVIEW Cryptographic Signing Overview Secure data payload transit across untrusted environments. Learn about Aquilia's zero-dependency, OWASP-aligned cryptographic signing subsystem. Core Design Principles The signing subsystem allows Aquilia applications to delegate state storage to clients (in cookies, tokens, or URL query parameters) without risking payload tampering. It is designed around the following architectural guidelines: Zero Mandatory Dependencies: By default, all HMAC implementations use Python's standard library (e.g. hmac, hashlib). Namespace Isolation (Salting): Using salt values mixes namespaces into derived sub-keys, rendering signatures generated by different signers incompatible even when sharing the same master key. Constant-Time Comparisons: Signature validation utilizes hmac.compare_digest to protect against side-channel timing attacks. Algorithm Agility: Supports standard HMAC algorithms (HS256, HS384, HS512) and asymmetric signatures (RS256, ES256, EdDSA) via the optional cryptography package. Signing Faults & Exceptions Aquilia maps its standard faults to legacy exceptions, keeping client-code integration straightforward: class SigningError(SigningFault): """Base exception for all signing-related operations.""" class BadSignature(BadSignatureFault): """Raised when signature verification fails.""" class SignatureExpired(SignatureExpiredFault): """Raised when signature validation succeeds but timestamp age exceeds max_age.""" class SignatureMalformed(SignatureMalformedFault): """Raised when the token format or encoding is corrupted.""" class UnsupportedAlgorithmError(UnsupportedAlgorithmFault): """Raised when an algorithm is selected but its dependencies are missing.""" Low-Level Cryptographic Primitives The module exposes pure utility functions for URL-safe base64 encoding and sub-key derivation: def b64_encode(data: bytes) -> str: """URL-safe, no-padding Base64 encoder.""" def b64_decode(data: str | bytes) -> bytes: """URL-safe, no-padding Base64 decoder. Validates canonical encoding.""" def constant_time_compare(a: bytes | str, b: bytes | str) -> bool: """Compares strings in constant time to prevent timing attacks.""" def derive_key(secret: str | bytes, salt: str, algorithm: str = "HS256") -> bytes: """Derives a namespace-specific sub-key using HKDF-lite to prevent cross-confusion.""" Resource Management Core Signers )
Go to Homepage