# 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.