cryptocoreedu 2.0.2
Educational cryptography toolkit with AES, SHA-256, SHA3-256, HMAC, PBKDF2
License: MIT
Requires Python: >=3.10
Keywords: cryptography, educational, aes, sha256, sha3, hmac, pbkdf2, encryption, hashing

# CryptoCoreEdu

**CryptoCoreEdu** — утилита командной строки для блочного шифрования файлов с использованием AES-128 в различных режимах работы, включая аутентифицированное шифрование. Проект разработан в образовательных целях для демонстрации принципов работы блочных шифров и криптографической аутентификации.

## Установка

### Способ 1: Установка из PyPI (рекомендуется)
```bash
# Установите пакет
pip install cryptocoreedu

# Или конкретной версии
pip install cryptocoreedu==2.0.2
```

### Способ 2: Установка из исходного кода
```bash
# Клонируйте репозиторий
git clone https://github.com/michaaans/CryptoCoreEdu.git
cd CryptoCoreEdu
# Установите виртуальное окружение
python3 -m venv vevn
# Активируйте виртуальное окружение
source venv/bin/activate
# Установите в режиме разработки
pip install -e .
```

## Проверка установки
### Windows (PowerShell)

```shell
# Проверьте что пакет установился (Windows)
pip list | findstr cryptocoreedu

# Проверьте работу утилиты
crypto --help 
# или 
crypto -h
```

### Linux/macOS/WSL (Bash)

```bash
# Проверьте что пакет установился
pip list | grep cryptocoreedu

# Проверьте работу утилиты
crypto --help
```

## Использование

### Поддерживаемые режимы
* ECB (Electronic Codebook) - базовый режим, требует паддинг

* CBC (Cipher Block Chaining) - блочный режим с цепочкой, требует паддинг

* CFB (Cipher Feedback) - потоковый режим, без паддинга

* OFB (Output Feedback) - потоковый режим, без паддинга

* CTR (Counter) - потоковый режим, без паддинга

* GCM (Galois/Counter Mode) - аутентифицированное шифрование по стандарту NIST SP 800-38D

* ETM (Encrypt-then-MAC) - составной режим CTR + HMAC-SHA256

### Базовые команды шифрования

**Вектор инициализации (IV) генерируется автоматически с помощью криптографически стойкого генератора псевдослучайных чисел**

```shell
# ECB режим (без IV)
crypto -alg aes -m ecb -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc

# CBC режим (IV генерируется автоматически)
crypto -alg aes -m cbc -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc

# CFB режим (потоковый)
crypto -alg aes -m cfb -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc

# OFB режим (потоковый)  
crypto -alg aes -m ofb -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc

# CTR режим (потоковый)
crypto -alg aes -m ctr -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc
```

```bash
# ECB режим (без IV)
crypto -alg aes -m ecb -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc

# CBC режим (IV генерируется автоматически)
crypto -alg aes -m cbc -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc

# CFB режим (потоковый)
crypto -alg aes -m cfb -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc

# OFB режим (потоковый)
crypto -alg aes -m ofb -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc

# CTR режим (потоковый)
crypto -alg aes -m ctr -enc -k 000102030405060708090a0b0c0d0e0f -i tests/document.txt -o tests/document.enc
```

### Базовые команды дешифрования

```shell
# ECB режим (без IV)
crypto -alg aes -m ecb -dec -k 000102030405060708090a0b0c0d0e0f -i tests/document.enc -o tests/document_decrypted.txt

# CBC режим (IV извлекается из файла)
crypto -alg aes -m cbc -dec -k 000102030405060708090a0b0c0d0e0f -i tests/document.enc -o tests/document_decrypted.txt

# CBC режим (IV передается явно)
crypto -alg aes -m cbc -dec -k 000102030405060708090a0b0c0d0e0f --iv AABBCCDDEEFF00112233445566778899 -i tests/document.enc -o tests/document_decrypted.txt

# Потоковые режимы (CFB, OFB, CTR) - аналогично CBC
crypto -alg aes -m cfb -dec -k 000102030405060708090a0b0c0d0e0f -i tests/document.enc -o tests/document_decrypted.txt
```

```bash
# ECB режим (без IV)
crypto -alg aes -m ecb -dec -k 000102030405060708090a0b0c0d0e0f -i tests/document.enc -o tests/document_decrypted.txt

# CBC режим (IV извлекается из файла)
crypto -alg aes -m cbc -dec -k 000102030405060708090a0b0c0d0e0f -i tests/document.enc -o tests/document_decrypted.txt

# CBC режим (IV передается явно)
crypto -alg aes -m cbc -dec -k 000102030405060708090a0b0c0d0e0f --iv AABBCCDDEEFF00112233445566778899 -i tests/document.enc -o tests/document_decrypted.txt

# Потоковые режимы (CFB, OFB, CTR) - аналогично CBC
crypto -alg aes -m cfb -dec -k 000102030405060708090a0b0c0d0e0f -i tests/document.enc -o tests/document_decrypted.txt
```

### Параметры командной строки
- `--algorithm (-alg)`: Алгоритм шифрования (`aes`)
- `--mode (-m)`: Режим работы (`ecb`, `cbc`, `cfb`, `ofb`, `ctr`, `gcm`, `etm`)  
- `--encrypt (-enc)`: Режим шифрования
- `--decrypt (-dec)`: Режим дешифрования
- `--key (-k)`: Ключ шифрования (16 байт в hex-формате, необязателен при шифровании)
- `--iv`: Вектор инициализации (16 байт в hex-формате; только в режиме дешифрования)
- `--nonce (-n)`: Nonce для GCM (12 байт в hex; алиас для --iv)
- `--aad`: Associated Authenticated Data в hex (для GCM/ETM)
- `--input (-i)`: Входной файл
- `--output (-o)`: Выходной файл

### Свойства безопасности AEAD
| Свойство | Описание |
|----------|-----------|
| Защита от подмены      | Изменение любого бита ciphertext или tag приводит к ошибке аутентификации       |
| Защита AAD      | Изменение AAD также приводит к ошибке, хотя AAD не шифруется        |
| Катастрофический отказ      | При ошибке аутентификации НЕ выводятся никакие данные        |
| Уникальность nonce      | Каждое шифрование использует уникальный случайный nonce        |


### GCM Mode (Galois/Counter Mode)
#### Описание
GCM — стандартизированный режим аутентифицированного шифрования (NIST SP 800-38D), широко используемый в TLS, IPsec, SSH.

Характеристики:
* Nonce: 12 байт (96 бит)
* Tag: 16 байт (128 бит)
* Использует умножение в поле Галуа GF(2¹²⁸)
* Формат вывода: Nonce (12) || Ciphertext || Tag (16)

```bash
   # Шифрование с AAD
   crypto -alg aes -m gcm -enc \
       -k 00112233445566778899aabbccddeeff \
       --aad 48656c6c6f576f726c64 \
       -i tests/plain.txt \
       -o tests/cipher.bin
   
   # Шифрование без AAD
   crypto -alg aes -m gcm -enc \
       -k 00112233445566778899aabbccddeeff \
       -i tests/plain.txt \
       -o tests/cipher.bin
   
   # Расшифрование (nonce читается из файла автоматически)
   crypto -alg aes -m gcm -dec \
       -k 00112233445566778899aabbccddeeff \
       --aad 48656c6c6f576f726c64 \
       -i tests/cipher.bin \
       -o tests/decrypted.txt
   
   # Расшифрование с внешним nonce (через --nonce или --iv)
   crypto -alg aes -m gcm -dec \
       -k 00112233445566778899aabbccddeeff \
       --nonce 000102030405060708090a0b \
       --aad 48656c6c6f576f726c64 \
       -i tests/ciphertext_without_nonce.bin \
       -o tests/decrypted.txt

```

```bash
   # 1. Создаём тестовый файл
   echo -n "Secret message for GCM test" > tests/gcm_plain.txt
   
   # 2. Шифруем с AAD
   crypto -alg aes -m gcm -enc \
       -k 00112233445566778899aabbccddeeff \
       --aad 4d657461646174613132333435 \
       -i tests/gcm_plain.txt \
       -o tests/gcm_cipher.bin
   # Вывод: [INFO] Файл успешно зашифрован (GCM authenticated) в режиме GCM
   
   # 3. Расшифровываем с тем же AAD
   crypto -alg aes -m gcm -dec \
       -k 00112233445566778899aabbccddeeff \
       --aad 4d657461646174613132333435 \
       -i tests/gcm_cipher.bin \
       -o tests/gcm_decrypted.txt
   # Вывод: [INFO] Файл успешно расшифрован (GCM аутентификация успешна) в режиме GCM
   
   # 4. Проверяем
   diff -s tests/gcm_plain.txt tests/gcm_decrypted.txt
   # Вывод: Files tests/gcm_plain.txt and tests/gcm_decrypted.txt are identical
```

```bash
   # Расшифровываем с НЕВЕРНЫМ AAD
   crypto -a aes -m gcm -d \
       -k 00112233445566778899aabbccddeeff \
       --aad 576f726e6741414421 \
       -i tests/gcm_cipher.bin \
       -o tests/should_not_exist.txt
   
   # Вывод:
   # [ERROR] Ошибка аутентификации
   # [DETAILS] Authentication failed: AAD mismatch or ciphertext tampered
   #          Возможные причины:
   #          - Неверный AAD
   #          - Повреждённые данные
   #          - Неверный ключ
   
   # Файл НЕ создан
   ls tests/should_not_exist.txt
   # ls: cannot access 'tests/should_not_exist.txt': No such file or directory
```

### ETM Mode (Encrypt-then-MAC)
#### Описание
ETM — составной режим аутентифицированного шифрования, комбинирующий CTR mode для шифрования и HMAC-SHA256 для аутентификации.

Характеристики:
* IV: 16 байт (128 бит)
* Tag: 32 байта (256 бит, HMAC-SHA256)
* Использует раздельные ключи для шифрования и MAC (key separation)
* Формат вывода: IV (16) || Ciphertext || HMAC Tag (32)

Конструкция:

HMAC(K_m, Ciphertext || AAD) = Tag,
где K_e, K_m = DeriveKeys(MasterKey)

```bash
   # Шифрование с AAD
   crypto -alg aes -m etm -enc \
       -k 00112233445566778899aabbccddeeff \
       --aad 616263 \
       -i tests/plain.txt \
       -o tests/cipher.bin
   
   # Шифрование без AAD
   crypto -a aes -m etm -enc \
       -k 00112233445566778899aabbccddeeff \
       -i tests/plain.txt \
       -o tests/cipher.bin
   
   # Расшифрование
   crypto -alg aes -m etm -dec \
       -k 00112233445566778899aabbccddeeff \
       --aad 616263 \
       -i tests/cipher.bin \
       -o tests/decrypted.txt
```

```bash
   # 1. Создаём тестовый файл
   echo -n "Secret message for ETM test" > tests/etm_plain.txt
   
   # 2. Шифруем
   crypto -alg aes -m etm -enc \
       -k 00112233445566778899aabbccddeeff \
       --aad 746573745f616164 \
       -i tests/etm_plain.txt \
       -o tests/etm_cipher.bin
   # Вывод: [INFO] Файл успешно зашифрован (ETM (CTR+HMAC) authenticated) в режиме ETM
   
   # 3. Расшифровываем
   crypto -alg aes -m etm -dec \
       -k 00112233445566778899aabbccddeeff \
       --aad 746573745f616164 \
       -i tests/etm_cipher.bin \
       -o tests/etm_decrypted.txt
   # Вывод: [INFO] Файл успешно расшифрован (ETM (CTR+HMAC) аутентификация успешна) в режиме ETM
   
   # 4. Проверяем
   diff -s tests/etm_plain.txt tests/etm_decrypted.txt
   # Вывод: Files tests/etm_plain.txt and tests/etm_decrypted.txt are identical****
```

### AAD (Associated Authenticated Data)
#### Что такое AAD?

AAD — это дополнительные данные, которые:
* НЕ шифруются (остаются в открытом виде)
* Аутентифицируются (защищены от подмены)
* Используются для метаданных: заголовков, ID, timestamp и т.д.

#### Формат AAD
AAD передаётся как hex-строка, например, 48656c6c6f

### Команды хэширования и HMAC

```shell
  # Хэширование без указания выходного файла (Windows)
  crypto dgst -alg sha256 -i document.pdf
  5d5b09f6dcb2d53a5fffc60c4ac0d55fb052072fa2fe5d95f011b5d5d5b0b0b5  document.pdf
  # Хэширование с указанием выходного файла
  crypto dgst -alg sha3-256 -i backup.tar -o backup.sha3
```

```bash
   # Хэширование без указания выходного файла (Linux/MacOS/WSL)
  crypto dgst -alg sha256 -i document.pdf
  5d5b09f6dcb2d53a5fffc60c4ac0d55fb052072fa2fe5d95f011b5d5d5b0b0b5  document.pdf
  # Хэширование с указанием выходного файла
  crypto dgst -alg sha3-256 -i backup.tar -o backup.sha3
```

```bash
   # HMAC без указания выходного файла (Linux/MacOS/WSL)
  crypto dgst -alg sha256 --hmac -k 00112233445566778899aabbccddeeff -i tests/message.txt
  # HMAC с указанием выходного файла
  crypto dgst -alg sha256 --hmac -k 00112233445566778899aabbccddeeff -i tests/message.txt -o tests/hmac.txt
  # HMAC с указанием флага для верификации
  crypto dgst -alg sha256 --hmac -k 00112233445566778899aabbccddeeff -i tests/message.txt -v tests/hmac.txt
  #Вывод: [OK] Проверка HMAC успешна
```
### Параметры хэш-функций и их особенности
#### Параметры хэширования:
- `--algorithm (-alg)`: Алгоритм хэширования (`sha256`, `sha3-256`)
- `--input (-i)`: Входной файл
- `--output (-o)`: Выходной файл (опционально)
#### Параметры HMAC:
- `--algorithm (-alg)`: Алгоритм хэширования (`sha256`, `sha3-256`)
- `--hmac`: Флаг для вычисления HMAC
- `--key (-k)`: Ключ для вычисления HMAC (обязателен для флага --hmac; может быть любой длины от 1 байта)
- `--input (-i)`: Входной файл
- `--output (-o)`: Выходной файл (опционально)
- `--verify (-v)`: Флаг для проверки сообщения

**Формат вывода хэша и HMAC**:
#### 5d5b09f6dcb2d53a5fffc60c4ac0d55fb052072fa2fe5d95f011b5d5d5b0b0b5  document.pdf

#### Особенности:

1. **Алгоритм SHA256**:
   - Реализован в соответствии со стандартом NIST FIPS 180-4
   - Использует конструкцию Меркля-Дамгарда
   - корретно реализует схему дополнения
   - реализует все константы SHA-256 и функции раундов.
   - Размер чанка 8192 байт.
   - Обработка больщих файлов (>1gb)

2. **Алгоритм SHA3-256**:
   - Реализован в соответствии со стандартом NIST FIPS 202
   - Использует губчатую конструкцию Keccak
   - Размер чанка 8192 байт.
   - Обработка больщих файлов (>1gb)

3. **Алгоритм HMAC-SHA-256**:
   - Реализован в соответствии со стандартом RFC 2104
   - Использует HMAC(K, m) = H((K ⊕ opad) ∥ H((K ⊕ ipad) ∥ m))
   - Обработка больщих файлов (>1gb)
   - Полностью соответствует RFC 4231
   - constant-time сравнение для верификации
   - ключи любой длины

### Размер ключа, IV и Nonce

| Параметр           | Размер            | Режимы                       |
|--------------------|-------------------|------------------------------|
| Ключ               | 16 байт (32 hex)  | Все режимы                   |
| IV                 | 16 байт (32 hex)  | ECB, CBC, CFB, OFB, CTR, ETM |
| Nonce              | 12 байт (24 hex)  | GCM                          |


```
Правильный ключ: 000102030405060708090a0b0c0d0e0f (32 символа)
Неправильно: mykey123 (8 байт)
```
```
Правильный IV: AABBCCDDEEFF00112233445566778899 (32 символа)
Неправильно: ASFSAFSA909DAS9DA99129129DNNBN
```
```
Правильный Nonce: 000102030405060708090a0b (24 символа)
```

### Команды PBKDF2 и HKDF

#### PBKDF2 (Password-Based Key Derivation Function 2):
PBKDF2 используется для безопасного выведения криптографических ключей из паролей.

- **Назначение**: Безопасное преобразование паролей в криптографические ключи
- **Стойкость к brute-force**: Большое количество итераций замедляет атаки
- **Уникальность ключей**: Использование соли гарантирует разные ключи для одинаковых паролей
- **Рекомендации по безопасности**:
    - Минимум 100,000 итераций для современных систем
    - Использование уникальной соли для каждого ключа
    - Длина ключа не менее 32 байт (256 бит)

#### Особенности реализации:
- **Алгоритм**: PBKDF2-HMAC-SHA256
- **Стандарт**: RFC 2898
- **Функция псевдослучайности**: HMAC-SHA256
- **Соль**: 16 байт (генерируется случайно если не указана)
- **Итерации**: По умолчанию 100,000 (настраивается)
- **Длина ключа**: Произвольная (по умолчанию 32 байта)

#### Формула PBKDF2:
```
DK = PBKDF2(PRF, Password, Salt, c, dkLen)
где:
  DK = derived key (выведенный ключ)
  PRF = HMAC-SHA256
  Password = пароль
  Salt = соль
  c = количество итераций
  dkLen = длина ключа в байтах

Для каждого блока i (от 1 до l, где l = ceil(dkLen / hLen)):
  U1 = PRF(Password, Salt || INT_32_BE(i))
  U2 = PRF(Password, U1)
  ...
  Uc = PRF(Password, Uc-1)
  Ti = U1 ⊕ U2 ⊕ ... ⊕ Uc

DK = T1 || T2 || ... || Tl (обрезается до dkLen байт)
```

#### HKDF (Hierarchical Key Derivation Function):
HKDF используется для детерминированного выведения множества ключей из одного мастер-ключа.

- **Назначение**: Создание множества безопасных ключей из одного мастер-ключа
- **Использование контекста**: Уникальные идентификаторы для разных применений
- **Примеры контекстов**: `"encryption"`, `"authentication"`, `"user:michan"`
- **Преимущества**:
    - Изоляция ключей: компрометация одного ключа не затрагивает другие
    - Детерминизм: одинаковые входные данные дают одинаковые ключи
    - Гибкость: произвольная длина ключей

#### Особенности реализации:
- **Основа**: HMAC-SHA256
- **Контекст**: Уникальная строка для каждого производного ключа
- **Детерминизм**: Одинаковые входные данные дают одинаковый ключ
- **Разделение**: Разные контексты дают статистически независимые ключи

#### Формула HKDF:
```
T1 = HMAC(master_key, context || INT_32_BE(1))
T2 = HMAC(master_key, context || INT_32_BE(2))
...
Tn = HMAC(master_key, context || INT_32_BE(n))

DerivedKey = T1 || T2 || ... || Tn (обрезается до нужной длины)
```


#### Базовое выведение ключа с PBKDF2:

```bash
   # Примеры использования
   
   # Базовое получение ключа с указанием соли
    crypto derive --password "MySecurePassword123!" \
    --salt a1b2c3d4e5f601234567890123456789 \
    --iterations 100000 \
    --length 32
  # Вывод: <KEY_HEX>  a1b2c3d4e5f601234567890123456789

  # Получение ключа с автоматической генерацией соли
   crypto derive --password "AnotherPassword" \
    --iterations 500000 \
    --length 16
  # Вывод: [INFO] Сгенерирована случайная соль: <SALT_HEX>
  #        <KEY_HEX>  <SALT_HEX>
  
  # Запись ключа в файл
  crypto derive --password "app_key" \
    --salt 0123456789abcdef0123456789abcdef \
    --iterations 100000 \
    --length 32 \
    --output tests/derived_key.bin
  # Вывод: [INFO] Ключ (32 байт) записан в файл: derived_key.bin
  #        <KEY_HEX>  0123456789abcdef0123456789abcdef
  
  # С минимальными итерациями (для тестирования RFC 6070 PBKDF2-HMAC-SHA256)
  crypto derive -p "password" -s 73616c74 -c 1 -l 20
  # Вывод: 120fb6cffcf8b32c43e7225256c4f837a86548c9  73616c74
```

#### Параметры команды derive (PBKDF2):
- `--password (-p)`: Пароль для выведения ключа в виде строки
- `--salt (-s)`: Соль в формате hex-строки
- `--iterations (-c)`: Количество итераций PBKDF2
- `--length (-l)`: Длина выведенного ключа в байтах
- `--algorithm (-alg)`: Алгоритм KDF
- `--output (-o)`: Выходной файл для сохранения ключа в бинарном виде

#### Формат вывода для команды derive:
* KEY_HEX SALT_HEX (оба в hex, разделены пробелом)
* Ключ: запрошенной длины в hex
* Соль: использованная соль в hex (предоставленная или сгенерированная)
* При --output: ключ сохраняется как бинарные байты, соль не записывается

#### Иерархическое выведение ключей (HKDF):

```bash
   # Используем master_key для выделения ключей из мастер-ключа
   
python3 -c "
from cryptocoreedu.kdf.hkdf import derive_key

master = b'master_secret_key_for_testing'

key1 = derive_key(master, 'encryption', 32)
key2 = derive_key(master, 'authentication', 32)
key3 = derive_key(master, 'encryption', 32)  # Same as key1
key4 = derive_key(master, 'user:michan', 64)

print(f'Encryption key:     {key1.hex()}')
print(f'Authentication key: {key2.hex()}')
print(f'Encryption key (2): {key3.hex()}')
print(f'User key: {key4.hex()}')
print(f'Deterministic: {key1 == key3}')
print(f'Different contexts produce different keys: {key1 != key2}')
"
```

### Автоматическая генерация ключей
**При шифровании без указания ключа утилита автоматически генерирует криптографически стойкий ключ:**

```bash
    # Выполняем шифрование без указания ключа в параметре
    crypto -alg aes -m ctr -enc -i tests/plain.txt -o tests/cipher.bin
    # Вывод в консоли: 
    [INFO] Сгенерирован случайный ключ: 5fae09f459b9b496cf00c3c5f1f0b613
    [INFO] Файл успешно зашифрован в режиме CFB                            
    [INFO] Входной файл: tests\plain.txt -> Выходной файл: tests\cipher.bin
    
    # или

    # Выполняем шифрование с указанием ключа в параметре
    crypto -alg aes -m ctr -enc -k 000102030405060708090a0b0c0d0e0f -i tests/plain.txt -o tests/cipher.bin
    # Вывод в консоли: 
    [INFO] Файл успешно зашифрован в режиме CTR
    [INFO] Входной файл: tests\plain.txt -> Выходной файл: tests\cipher.bin
```

**При дешифровании параметр --key (-k) все также является обязательным:**
```bash
    # Выполняем дешифрование с указанием ключа 
    crypto -alg aes -m ctr -dec -k 5fae09f459b9b496cf00c3c5f1f0b613 -i tests/cipher.bin -o tests/plain.txt
    # Вывод в консоли: 
    [WARNING] Для режима CTR IV будет извлечен из файла
    [INFO] Файл успешно расшифрован в режиме CTR
    [INFO] Входной файл: tests\cipher.bin -> Выходной файл: tests\plain.txt
```

# Тестирование

## Запуск автотестов
```shell
# Windows
python -m unittest discover -s tests/ -p 'test_*.py' -v
```
```bash
# bash
python -m unittest discover -s tests/ -p 'test_*.py' -v
```

## Тесты на интероперабильность с OPENSSL производятся в ручном порядке

### Тестирование совместимости с OpenSSL

```bash
# 1. Шифруем своим инструментом
crypto -alg aes -m cbc -enc -k 000102030405060708090a0b0c0d0e0f -i tests/plain.txt -o tests/cipher.bin

# 2. Извлекаем IV и ciphertext
dd if=tests/cipher.bin of=tests/iv.bin bs=16 count=1
dd if=tests/cipher.bin of=tests/ciphertext_only.bin bs=16 skip=1
tests/
# 3. Дешифруем с OpenSSL
openssl enc -aes-128-cbc -d -K 000102030405060708090A0B0C0D0E0F -iv $(xxd -p tests/iv.bin | tr -d '\n') -in tests/ciphertext_only.bin -out tests/decrypted.txt

# 4. Проверяем
diff -s tests/plain.txt tests/decrypted.txt

# В выводе увидим: Files tests/plain.txt and tests/decrypted.txt are identical
```

```bash
# 1. Шифруем с OpenSSL
openssl enc -aes-128-cbc -K 000102030405060708090A0B0C0D0E0F -iv AABBCCDDEEFF00112233445566778899 -in tests/plain.txt -out tests/openssl_cipher.bin

# 2. Дешифруем своим инструментом
crypto -alg aes -m cbc -dec -k 000102030405060708090a0b0c0d0e0f --iv AABBCCDDEEFF00112233445566778899 -i tests/openssl_cipher.bin -o tests/decrypted.txt

# 3. Проверяем
diff -s tests/plain.txt tests/decrypted.txt

# В выводе увидим: Files tests/plain.txt and tests/decrypted.txt are identical
```

### Команды OpenSSL для разных режимов
* #### CBC: openssl enc -aes-128-ecb

* #### CBC: openssl enc -aes-128-cbc

* #### CFB: openssl enc -aes-128-cfb

* #### OFB: openssl enc -aes-128-ofb

* #### CTR: openssl enc -aes-128-ctr


### Тестирование CSPRNG на уникальность
    
```shell
    # 1. Переходим в корень проекта (для Windows)
    cd C:/Users/user/PycharmProjects/CryptoCoreEdu/
    # 2. Запускаем тест на проверку уникальности генерации ключей и векторов инициализации
    python -m tests.test_csprng.python
    # Ожидаемый вывод: Успешно сгенерировано 1000 уникальных ключей.
``` 

```bash
    # 1. Переходим в корень проекта (для Linux/Mac/WSL)
    cd /mnt/c/Users/user/PycharmProjects/CryptoCoreEdu
    # 2. Запускаем тест на проверку уникальности генерации ключей и векторов инициализации
    python -m tests.test_csprng.python
    # Ожидаемый вывод: Успешно сгенерировано 1000 уникальных ключей.
```

### Тестирование CSPRNG с помощью NIST Statistical Test Suite

#### Пошаговая инструкция запуска тестов:

1. **Переходим в корневую папку проекта:**
    ```bash
    cd /mnt/c/Users/user/PycharmProjects/CryptoCoreEdu
    ```
2. **Переходим в папку NIST STS:**
    ```bash
    cd sts-2.1.2/sts-2.1.2/
    ```
   
3. **Собираем тесты:**

    ```bash
    make
    ```
4. **Создаем тестовые данные (10 МБ):**
    ```bash
    python3 -c "
    from cryptocoreedu.csprng import generate_random_bytes
    data = generate_random_bytes(10000000)
    open('random_test_data.bin', 'wb').write(data)
    print('Сгенерирован файл random_test_data.bin размером 10 МБ')
    "
    ```
5. **Запускаем тесты:**
    ```bash
    ./assess 10000000
    ```

6. **Вводим параметры тестирования:**

* #### Enter Choice: 0 (Input File)

* #### User Prescribed Input File: ../../random_test_data.bin

* #### Enter Choice: 1 (All statistical tests)

* #### Select Test (0 to continue): 0 (Default parameters)

* #### How many bitstreams? 10 (Для точной оценки)

* #### Select input mode: 1 (Binary mode)

7. **Ждем выполнения тестов (5-7 минут)**


8. **Просматриваем результаты:**
    ```bash
    # (Linux/Mac/WSL)
    cat experiments/AlgorithmTesting/finalAnalysisReport.txt
    ```
9. **Ожимаемый вывод:**
    ```
    Все 15 статистических тестов NIST должны быть пройдены с показателем 10/10 и p-value ≥ 0.01
    
    ------------------------------------------------------------------------------
    RESULTS FOR THE UNIFORMITY OF P-VALUES AND THE PROPORTION OF PASSING SEQUENCES
    ------------------------------------------------------------------------------
    generator is <../../random_test_data.bin>
    ------------------------------------------------------------------------------
     C1  C2  C3  C4  C5  C6  C7  C8  C9 C10  P-VALUE  PROPORTION  STATISTICAL TEST
    ------------------------------------------------------------------------------
      0   1   1   3   3   0   1   1   0   0  0.213309     10/10      Frequency
      1   0   2   2   0   1   0   0   4   0  0.066882     10/10      BlockFrequency
      0   0   3   1   1   3   1   0   1   0  0.213309     10/10      CumulativeSums
      0   2   0   0   3   3   1   0   1   0  0.122325     10/10      CumulativeSums
      0   0   1   3   1   1   0   2   0   2  0.350485     10/10      Runs
      0   0   2   2   0   2   0   4   0   0  0.035174     10/10      LongestRun
      0   0   2   1   1   1   4   0   0   1  0.122325     10/10      Rank
      1   1   0   3   0   1   1   0   3   0  0.213309     10/10      FFT
      0   0   0   0   1   1   0   1   2   5  0.008879     10/10      NonOverlappingTemplate
      0   0   2   1   0   0   1   3   0   3  0.122325     10/10      NonOverlappingTemplate
      0   1   2   0   2   1   1   0   0   3  0.350485     10/10      NonOverlappingTemplate
      .....
    ```

### Тестирование хэш-функций

#### Тестирование хэш-функций sha256 и sha3-256 на тестовых векторах

```bash
   # Тестирование sha256 (Linux/MacOS/WSL)
   ## Хэшируем пустой файл
   crypto dgst -alg sha256 -i tests/empty.txt.txt
   # Ожидаемый вывод: e3b0c44298fc1c149afbf4c899cfb92427ae41e4649b934ca495991b7852b855 tests/empty.txt.txt
   
   ## Хэшируем файл со строкой "abc"
   crypto dgst -alg sha256 -i tests/test_one.txt
   # Ожидаемый вывод: ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad  tests/test_one.txt
   
   ## Хэшируем файл со строкой "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"
   crypto dgst -alg sha256 -i tests/test_two.txt
   # Ожидаемый вывод: 248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1  tests/test_two.txt

```

```bash
   # Тестирование sha3-256 (Linux/MacOS/WSL)
   ## Хэшируем пустой файл
   crypto dgst -alg sha3-256 -i tests/empty.txt.txt
   # Ожидаемый вывод: a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a tests/empty.txt.txt
   
   ## Хэшируем файл со строкой "abc"
   crypto dgst -alg sha3-256 -i tests/test_one.txt
   # Ожидаемый вывод: 3a985da74fe225b2045c172d6bd390bd855f086e3e9d525b46bfe24511431532  tests/test_one.txt
   
   ## Хэшируем файл со строкой "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"
   crypto dgst -alg sha3-256 -i tests/test_two.txt
   # Ожидаемый вывод: 41c0dba2a9d6240849100376a8235e2c82e1b9998a999e21db32dd97496d3376  tests/test_two.txt

```

#### Тестирование хэш-функций sha256 и sha3-256 на интероперабельность

```bash
   # Тестирование sha256 (Linux/MacOS/WSL)
   # хэшируем пустой файл нашей реализацией
   crypto dgst -alg sha256 -i tests/empty.txt.txt -o tests/output_hash.txt
   # хэшируем пустой файл с помощью sha256sum
   sha256sum tests/empty.txt.txt > tests/system_hash.txt
   # проверяем идентичность
   diff -s tests/output_hash.txt tests/system_hash.txt
   #Ожидаемый вывод: Files tests/output_hash.txt and tests/system_hash.txt are identical
```

```bash
   # Тестирование sha3-256 (Linux/MacOS/WSL)
   # хэшируем пустой файл нашей реализацией
   crypto dgst -alg sha3-256 -i tests/empty.txt.txt -o tests/output_hash.txt
   # хэшируем пустой файл с помощью sha3sum
   sha3sum -a 256 tests/empty.txt.txt > tests/system_hash.txt
   # проверяем идентичность
   diff -s tests/output_hash.txt tests/system_hash.txt
   #Ожидаемый вывод: Files tests/output_hash.txt and tests/system_hash.txt are identical
```

#### Тестирование хэш-функций на файле ~1gb

```bash
   crypto dgst -alg sha256 -i tests/test1gb.txt
   # Ожидаемый вывод: d5739a8da2a57adb3b9a38495a389894227f5e083efb541b0b4473faccd55225  tests/test1gb.txt
   # Примерное время выполнение около 50-55 секунд
```

### Тестирование HMAC

#### Тесты с известными векторами RFC-4231

```bash
  # Ключ - 20 байт
  echo "Hi There" > tests/message.txt 
  crypto dgst -alg sha256 --hmac -k 0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b -i tests/message.txt
  # b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7  tests/message.txt
  
  # Ключ - 8 байт
  echo "what do ya want for nothing?" > tests/message.txt 
  crypto dgst -alg sha256 --hmac -k 4a656665 -i tests/message.txt
  # 5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843  tests/message.txt
  
  # Ключ - 20 байт
  echo -n "ddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd" | xxd -r -p > tests/message.bin
  crypto dgst -alg sha256 --hmac -k aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa -i tests/message.bin
  # 773ea91e36800e46854db8ebd09181a72959098b3ef8c122d9635514ced565fe  tests/message.bin
  
  # Ключ - 25 байт
  echo -n "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd" | xxd -r -p > tests/message.bin
  crypto dgst -alg sha256 --hmac -k 0102030405060708090a0b0c0d0e0f10111213141516171819 -i tests/message.bin
  # 82558a389a443c0ea4cc819899f2083a85f0faa3e578f8077a2e3ff46729665b  tests/message.bin
  
  # Ключ - 20 байт
  echo -n "Test With Truncation" > tests/message.txt
  crypto dgst -alg sha256 --hmac -k 0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c -i tests/message.txt
  # a3b6167473100ee06e0c796c2955552b  tests/message.txt
  
  # Ключ - 131 байт
  echo -n "Test Using Larger Than Block-Size Key - Hash Key First" > tests/message.txt
  crypto dgst -alg sha256 --hmac -k aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa -i tests/message.txt
  # 60e431591ee0b67f0d8a26aacbf5b77f8e0bc6213728c5140546040f0ee37f54  tests/message.txt
  
  # Ключ - 131 байт
  echo -n "This is a test using a larger than block-size key and a larger than block-size data. The key needs to be hashed before being used by the HMAC algorithm." > tests/message.txt
  crypto dgst -alg sha256 --hmac -k aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa -i tests/message.txt
  # 9b09ffa71b942fcb27635fbcd5b0e944bfdc63644f0713938a7f51535c3a35e2  tests/message.txt
```
#### Тест верификации 

```bash
   crypto dgst -alg sha256 --hmac -k 00112233445566778899aabbccddeeff -i tests/message.txt -o tests/hmac.txt
    
   crypto dgst -alg sha256 --hmac -k 00112233445566778899aabbccddeeff -i tests/message.txt -v tests/hmac.txt
   #Вывод [OK] Проверка HMAC успешна
```

#### Тест на обнаружение искажения
```bash
   # Изменение файла
   echo "original_content" > tests/message.txt
   crypto dgst -alg sha256 --hmac -k 00112233445566778899