kybercffi-test-v2 1.0.2
Python CFFI обвязка для Kyber KEM - постквантовая криптография
License: MIT
Requires Python: >=3.7
Keywords: kyber, kem, post-quantum, cryptography, lattice-based, cffi

# kybercffi

**Python CFFI обвязка для Kyber KEM - постквантовая криптография**

[![PyPI version](https://badge.fury.io/py/kybercffi.svg)](https://badge.fury.io/py/kybercffi)
[![Python versions](https://img.shields.io/pypi/pyversions/kybercffi.svg)](https://pypi.org/project/kybercffi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Описание

`kybercffi` - это Python обвязка для алгоритма Kyber KEM (Key Encapsulation Mechanism), реализованная с использованием CFFI. Kyber является одним из алгоритмов постквантовой криптографии, стандартизированным NIST в 2022 году.

### Особенности

- ✅ **Все варианты безопасности**: Kyber512, Kyber768, Kyber1024
- ✅ **Кроссплатформенность**: Windows, Linux, macOS
- ✅ **Высокая производительность**: Использует эталонную реализацию на C
- ✅ **Простой API**: Интуитивно понятный интерфейс
- ✅ **Безопасность**: Устойчивость к квантовым атакам

### Поддерживаемые варианты

| Вариант | Уровень безопасности | Эквивалент | Размер открытого ключа | Размер секретного ключа |
|---------|---------------------|------------|----------------------|------------------------|
| Kyber512 | 1 | AES-128 | 800 байт | 1632 байта |
| Kyber768 | 3 | AES-192 | 1184 байта | 2400 байт |
| Kyber1024 | 5 | AES-256 | 1568 байт | 3168 байт |

## Установка

### Из PyPI (рекомендуется)

```bash
pip install kybercffi
```

### Из исходного кода

```bash
git clone https://github.com/denismagnitov/kybercffi.git
cd kybercffi
pip install .
```

### Требования

- Python 3.7+
- CFFI 1.15.0+
- Компилятор C (GCC, Clang, MSVC)

## Быстрый старт

```python
import kybercffi

# Создание экземпляра Kyber768 (рекомендуемый)
kyber = kybercffi.Kyber768()

# Генерация ключей
public_key, secret_key = kyber.generate_keypair()

# Инкапсуляция (отправитель)
ciphertext, shared_secret1 = kyber.encapsulate(public_key)

# Декапсуляция (получатель)
shared_secret2 = kyber.decapsulate(ciphertext, secret_key)

# Проверка
assert shared_secret1 == shared_secret2
print("Общий секрет успешно установлен!")
```

## Подробное использование

### Выбор варианта безопасности

```python
import kybercffi

# Способ 1: Прямое создание
kyber512 = kybercffi.Kyber512()    # Быстрый, меньше ключи
kyber768 = kybercffi.Kyber768()    # Рекомендуемый баланс
kyber1024 = kybercffi.Kyber1024()  # Максимальная безопасность

# Способ 2: Через фабрику
kyber = kybercffi.KyberKEM.create(security_level=3)  # Kyber768
```

### Удобные функции

```python
import kybercffi

# Генерация ключей
public_key, secret_key = kybercffi.generate_keypair(security_level=3)

# Инкапсуляция
ciphertext, shared_secret = kybercffi.encapsulate(public_key, security_level=3)

# Декапсуляция
shared_secret = kybercffi.decapsulate(ciphertext, secret_key, security_level=3)
```

### Обработка ошибок

```python
import kybercffi

try:
    kyber = kybercffi.Kyber768()
    public_key, secret_key = kyber.generate_keypair()
    
    # Неправильный размер ключа
    bad_key = b"wrong_key"
    ciphertext, shared_secret = kyber.encapsulate(bad_key)
    
except kybercffi.KyberEncryptionError as e:
    print(f"Ошибка шифрования: {e}")
except kybercffi.KyberError as e:
    print(f"Общая ошибка Kyber: {e}")
```

## Примеры использования

### Простой обмен ключами

```python
import kybercffi

# Алиса генерирует ключи
alice_kyber = kybercffi.Kyber768()
alice_public, alice_secret = alice_kyber.generate_keypair()

# Боб получает открытый ключ Алисы и создает общий секрет
bob_kyber = kybercffi.Kyber768()
ciphertext, bob_shared_secret = bob_kyber.encapsulate(alice_public)

# Алиса получает зашифрованный текст и восстанавливает общий секрет
alice_shared_secret = alice_kyber.decapsulate(ciphertext, alice_secret)

# Теперь у Алисы и Боба одинаковый общий секрет
assert alice_shared_secret == bob_shared_secret
```

### Интеграция с симметричным шифрованием

```python
import kybercffi
from cryptography.fernet import Fernet
import base64

# Установка общего секрета через Kyber
kyber = kybercffi.Kyber768()
public_key, secret_key = kyber.generate_keypair()
ciphertext, shared_secret = kyber.encapsulate(public_key)

# Использование общего секрета для симметричного шифрования
key = base64.urlsafe_b64encode(shared_secret)
fernet = Fernet(key)

# Шифрование данных
message = b"Секретное сообщение"
encrypted_message = fernet.encrypt(message)

# Расшифрование данных
decrypted_message = fernet.decrypt(encrypted_message)
assert message == decrypted_message
```

## API Reference

### Классы

#### `Kyber512`, `Kyber768`, `Kyber1024`

Основные классы для работы с соответствующими вариантами Kyber.

**Методы:**
- `generate_keypair() -> Tuple[bytes, bytes]` - Генерирует пару ключей
- `encapsulate(public_key: bytes) -> Tuple[bytes, bytes]` - Инкапсулирует общий секрет
- `decapsulate(ciphertext: bytes, secret_key: bytes) -> bytes` - Декапсулирует общий секрет

#### `KyberKEM`

Фабричный класс для создания экземпляров Kyber.

**Методы:**
- `create(security_level: int) -> KyberBase` - Создает экземпляр по уровню безопасности
- `get_variant_info() -> dict` - Возвращает информацию о всех вариантах

### Исключения

- `KyberError` - Базовое исключение
- `KyberKeyError` - Ошибки ключей
- `KyberEncryptionError` - Ошибки инкапсуляции
- `KyberDecryptionError` - Ошибки декапсуляции

## Производительность

Примерные показатели производительности на современном процессоре:

| Операция | Kyber512 | Kyber768 | Kyber1024 |
|----------|----------|----------|-----------|
| Генерация ключей | ~0.1 мс | ~0.2 мс | ~0.3 мс |
| Инкапсуляция | ~0.1 мс | ~0.2 мс | ~0.3 мс |
| Декапсуляция | ~0.1 мс | ~0.2 мс | ~0.3 мс |

## Безопасность

- Использует эталонную реализацию Kyber от команды разработчиков
- Все операции выполняются в постоянном времени
- Защита от атак по побочным каналам
- Криптографически стойкие генераторы случайных чисел

## Лицензия

MIT License. См. файл [LICENSE](LICENSE) для подробностей.

## Автор

**Denis Magnitov**

## Вклад в проект

Приветствуются вклады в проект! Пожалуйста:

1. Форкните репозиторий
2. Создайте ветку для новой функции
3. Внесите изменения
4. Добавьте тесты
5. Отправьте Pull Request

## Поддержка

- [GitHub Issues](https://github.com/denismagnitov/kybercffi/issues)
- [Документация](https://github.com/denismagnitov/kybercffi#readme)

## Связанные проекты

- [Kyber](https://pq-crystals.org/kyber/) - Официальная реализация
- [NIST PQC](https://csrc.nist.gov/projects/post-quantum-cryptography) - Стандартизация постквантовой криптографии