Credential Security — Aquilia Documentation
Comprehensive guide and documentation for Credential Security in the Aquilia framework. View API reference, examples, and implementation patterns.
Secure Credential Store Cryptographic protections, storage layout, and audit logging Local environment security is a cornerstone of the Aquilia deployment pipeline. To prevent API tokens from being stored in plain text, committed to version control, or leaked in history files, the framework incorporates a multi-layered cryptographic store called RenderCredentialStore . Cryptographic Protection Model The credential store implements a defense-in-depth model, securing Render tokens (stored in the credentials.surp binary file) through a series of cryptographic boundaries: 1. Machine-Bound Key Derivation Keys are never saved on disk. Instead, the encryption key is derived dynamically using PBKDF2-HMAC-SHA512 configured with 600,000 iterations. The derivation payload incorporates machine-specific identifiers: host hostname, current user name, hardware platform architecture, and python major/minor version. This prevents credentials from being copied and decrypted on another machine. 2. Authenticated Encryption (AES-256-GCM) The token is encrypted with AES-256-GCM using a unique 96-bit random nonce generated for each write operation. This provides authenticated confidentiality, ensuring that any external manipulation of the ciphertext results in decryption failure. 3. Tamper-Proof Plaintext Canary An encrypted plaintext canary ("AQUILIA_CANARY_OK") is embedded in the binary payload. During the loading process, the canary is decrypted first. If key derivation parameters are incorrect (such as moving the file to another PC), the canary check fails immediately, avoiding partial decrypt errors. 4. In-Memory Security & Zeroing To prevent security leaks via core dumps or system memory scraping, the credential store uses Python's ctypes module to overwrite mutable buffers with zeros (ctypes.memset) immediately after use, ensuring sensitive data is purged from memory. On-Disk Storage Layout Credential items are isolated under the local project workspace configuration folder. The directory is located at: /.aquilia/providers/render/ Binary Envelope Format The credentials.surp file follows a structured binary layout, verified strictly on read: Byte Offset Field Name Size Description 0 - 3 Magic Bytes 4 bytes Standard header signature "AQCR" 4 Version 1 byte Envelope version (currently 2) 5 Cipher ID 1 byte Cipher suite choice (e.g. 1 = AES-GCM) 6 - 13 Timestamp 8 bytes Double float indicating write time (big-endian) 14 - 17 TTL Seconds 4 bytes Expiration limit (0 indicates no expiration) 18 - 49 Salt 32 bytes Cryptographic salt for key derivation 50 - 61 Nonce 12 bytes Random GCM initialization vector 62 - 65 Token Len 4 bytes Size (uint32) of the encrypted payload 66 ... Ciphertext N bytes AES-256-GCM encrypted token ... + 16 GCM Auth Tag 16 bytes GCM integrity authentication tag ... + 64 HMAC 64 bytes HMAC-SHA512 checksum covering all fields Audit Logging Every interaction with the credential store (such as executing aq provider status or deploying via aq deploy render) writes an entry to audit.log. This creates a secure history trail, letting developers audit authentication actions on a local workstation. Next Chapters 03 CLI Reference Guide Complete command flags, environment variable synchronizations, and CLI diagnostics. 01 Providers Overview Deployment strategy, container building pipelines, and configuration approaches. ) } function ArrowRightIcon() { return ( )
Go to Homepage