mirror of
https://github.com/azaion/loader.git
synced 2026-04-22 13:16:33 +00:00
Oleksandr Bezdieniezhnykh
82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# 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; manual PKCS7 unpad |
|
||
| `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. Manual PKCS7 unpadding: read last byte as padding length; strip if 1–16
|
||
|
||
### 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.
|