loader/_docs/02_document/modules/security.md

Module: security

Purpose

Provides AES-256-CBC encryption/decryption and multiple key derivation strategies for API resource protection and hardware-bound access control.

Public Interface

Classes

Security (cdef class)

All methods are @staticmethod cdef — Cython-only visibility, not callable from pure Python.

Method	Signature	Description
encrypt_to	(input_bytes, key) -> bytes	AES-256-CBC encrypt with random IV, PKCS7 padding; returns IV + ciphertext
decrypt_to	(ciphertext_with_iv_bytes, key) -> bytes	AES-256-CBC decrypt; first 16 bytes = IV; PKCS7 via padding.PKCS7(128).unpadder()
get_hw_hash	(str hardware) -> str	Derives hardware hash: SHA-384("Azaion_{hardware}_%$$$)0_") → base64
get_api_encryption_key	(Credentials creds, str hardware_hash) -> str	Derives per-user+hw key: SHA-384("{email}-{password}-{hw_hash}-#%@AzaionKey@%#---") → base64
get_resource_encryption_key	() -> str	Returns fixed shared key: SHA-384("-#%@AzaionKey@%#---234sdfklgvhjbnn") → base64
calc_hash	(str key) -> str	SHA-384 hash → base64 string

Module-level Constants

Name	Value	Status
BUFFER_SIZE	65536	Unused — declared but never referenced

Internal Logic

Encryption (encrypt_to)

1. SHA-256 hash of string key → 32-byte AES key
2. Generate random 16-byte IV
3. PKCS7-pad plaintext to 128-bit block size
4. AES-CBC encrypt
5. Return IV || ciphertext

Decryption (decrypt_to)

1. SHA-256 hash of string key → 32-byte AES key
2. Split input: first 16 bytes = IV, rest = ciphertext
3. AES-CBC decrypt
4. PKCS7 removal via cryptography padding.PKCS7(128).unpadder() (update + finalize)

Key Derivation Hierarchy

• Hardware hash: salted hardware fingerprint → SHA-384 → base64
• API encryption key: combines user credentials + hardware hash + salt → SHA-384 → base64 (per-download key)
• Resource encryption key: fixed salt string → SHA-384 → base64 (shared key for big/small resource split)

Dependencies

• Internal: credentials (for Credentials type in get_api_encryption_key)
• External: base64, hashlib, os (stdlib), cryptography (44.0.2)

Consumers

• api_client — calls encrypt_to, decrypt_to, get_hw_hash, get_api_encryption_key, get_resource_encryption_key

Data Models

None.

Configuration

None.

External Integrations

None.

Security

• AES-256-CBC with PKCS7 padding for data encryption
• SHA-384 for key derivation (with various salts)
• SHA-256 for AES key expansion from string keys
• get_resource_encryption_key() uses a hardcoded salt — the key is static and shared across all users
• get_api_encryption_key() binds encryption to user credentials + hardware — per-user, per-machine keys

Tests

No tests found.