loader/_docs/02_document/components/02_security/description.md

Security

1. High-Level Overview

Purpose: Provides AES-256-CBC encryption/decryption, multiple key derivation strategies, and OS-specific hardware fingerprinting for machine-bound access control.

Architectural Pattern: Utility / Strategy — stateless static methods for crypto operations; hardware fingerprinting with caching.

Upstream dependencies: Core Models (01) — uses Credentials type, constants.log()

Downstream consumers: Resource Management (03) — ApiClient uses all Security and HardwareService methods

2. Internal Interfaces

Interface: Security

Method	Input	Output	Async	Error Types
encrypt_to	bytes input_bytes, str key	bytes	No	cryptography errors
decrypt_to	bytes ciphertext_with_iv, str key	bytes	No	cryptography errors
get_hw_hash	str hardware	str	No	—
get_api_encryption_key	Credentials creds, str hardware_hash	str	No	—
get_resource_encryption_key	—	str	No	—
calc_hash	str key	str	No	—

All methods are @staticmethod cdef (Cython-only visibility).

Interface: HardwareService

Method	Input	Output	Async	Error Types
get_hardware_info	—	str	No	subprocess errors

@staticmethod cdef with module-level caching in _CACHED_HW_INFO.

3. External API Specification

N/A — internal-only component.

4. Data Access Patterns

Caching Strategy

Data	Cache Type	TTL	Invalidation
Hardware info	In-memory (module global)	Process lifetime	Never (static hardware)

5. Implementation Details

Algorithmic Complexity: All crypto operations are O(n) in input size.

State Management: HardwareService has one cached string; Security is fully stateless.

Key Dependencies:

Library	Version	Purpose
cryptography	44.0.2	AES-256-CBC cipher, PKCS7 padding

Error Handling Strategy:

• Crypto errors propagate to caller (no catch)
• subprocess.check_output in HardwareService raises CalledProcessError on failure

Key Derivation Hierarchy:

1. Hardware hash: SHA-384("Azaion_{hw_string}_%$$$)0_") → base64
2. API encryption key: SHA-384("{email}-{password}-{hw_hash}-#%@AzaionKey@%#---") → base64 (per-user, per-machine)
3. Resource encryption key: SHA-384("-#%@AzaionKey@%#---234sdfklgvhjbnn") → base64 (fixed, shared)
4. AES key expansion: SHA-256(string_key) → 32-byte AES key (inside encrypt/decrypt)

6. Extensions and Helpers

None.

7. Caveats & Edge Cases

Known limitations:

• get_resource_encryption_key() returns a fixed key — all users share the same resource encryption key
• Hardware detection uses shell=True subprocess — injection risk if inputs were user-controlled (they are not)
• Linux hardware detection may fail on systems without lscpu, lspci, or /sys/block/sda
• Multiple GPUs: only the first GPU line is captured

Potential race conditions:

• _CACHED_HW_INFO is a module global written without locking — concurrent first calls could race, but the result is idempotent

8. Dependency Graph

Must be implemented after: Core Models (01)

Can be implemented in parallel with: Resource Management (03) depends on this, so Security must be ready first

Blocks: Resource Management (03)

9. Logging Strategy

Log Level	When	Example
INFO	Hardware info gathered	"Gathered hardware: CPU: ... GPU: ... Memory: ... DriveSerial: ..."
INFO	Cached hardware reuse	"Using cached hardware info"

Log format: Via constants.log() — [HH:mm:ss INFO] message

Log storage: Same as Core Models logging configuration