# Component: Security & Hardware Identity

## Overview
Provides cryptographic operations (AES-256-CBC encryption/decryption) and hardware fingerprinting. Used for protecting model files in transit and at rest, and for binding API encryption keys to specific machines.

**Pattern**: Utility/service library (static methods)
**Upstream**: None (leaf component)
**Downstream**: API & CDN, Training, Inference

## Modules
- `security` — AES encryption, key derivation (SHA-384), hardcoded model key
- `hardware_service` — cross-platform hardware info collection (CPU, GPU, RAM, drive serial)

## Internal Interfaces

### Security (static methods)
```python
Security.encrypt_to(input_bytes: bytes, key: str) -> bytes
Security.decrypt_to(ciphertext_with_iv: bytes, key: str) -> bytes
Security.calc_hash(key: str) -> str
Security.get_hw_hash(hardware: str) -> str
Security.get_api_encryption_key(creds, hardware_hash: str) -> str
Security.get_model_encryption_key() -> str
```

### hardware_service
```python
get_hardware_info() -> str
```

## Data Access Patterns
- `hardware_service` executes shell commands to query OS/hardware info
- `security` performs in-memory cryptographic operations only

## Implementation Details
- **Encryption**: AES-256-CBC. Key = SHA-256(key_string). IV = 16 random bytes prepended to ciphertext. PKCS7 padding.
- **Key derivation hierarchy**:
  1. `get_model_encryption_key()` → hardcoded secret → SHA-384 → base64
  2. `get_hw_hash(hardware_string)` → salted hardware string → SHA-384 → base64
  3. `get_api_encryption_key(creds, hw_hash)` → email+password+hw_hash+salt → SHA-384 → base64
- **Hardware fingerprint format**: `CPU: {cpu}. GPU: {gpu}. Memory: {memory}. DriveSerial: {serial}`

## Caveats
- **Hardcoded model encryption key** in `get_model_encryption_key()` — anyone with source code access can derive the key
- **Shell command injection risk**: `hardware_service` uses `shell=True` subprocess — safe since no user input is involved, but fragile
- **PKCS7 unpadding** in `decrypt_to` uses manual check instead of the `cryptography` library's unpadder — potential padding oracle if error handling is observed
- `BUFFER_SIZE` constant declared but unused in security.py

## Dependency Graph
```mermaid
graph TD
    hardware_service --> api_client[API & CDN: api_client]
    security --> api_client
    security --> training[Training]
    security --> inference[Inference: start_inference]
```

## Logging Strategy
None — operations are silent except for exceptions.