# 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