Citadel

Пост-квантовый гибридный сервер шифрования и управления ключами.

Citadel объединяет X25519 + ML-KEM-768 для инкапсуляции ключей и AES-256-GCM для шифрования данных, следуя гибридному подходу NIST для пост-квантового перехода. Приложения шифруют и расшифровывают данные через REST API. Citadel управляет ключами — генерацией, ротацией, отзывом, контролем доступа и журналированием аудита.

Статус: Рабочая реализация. Аудит не проводился. Продакшен-развёртываний нет. См. Безопасность ниже.

---

Что он делает

Your Application              Citadel                         Database
       |                         |                               |
       |-- POST /encrypt ------->|                               |
       |                         |-- hybrid KEM (X25519+ML-KEM)  |
       |                         |-- derive AES-256 key (HKDF)   |
       |                         |-- encrypt with AES-256-GCM    |
       |<-- encrypted blob ------|                               |
       |                                                         |
       |-- store blob ------------------------------------------>|

Ваше приложение никогда не работает напрямую с исходным ключевым материалом. Зашифрованный blob самодостаточен — он включает обёрнутый ключ, идентификаторы алгоритмов и шифротекст. Храните его в любой базе данных. Для расшифровки отправьте его обратно в Citadel с тем же AAD и контекстом.

Архитектура

citadel-envelope    Hybrid encryption core (X25519 + ML-KEM-768 + AES-256-GCM)
citadel-keystore    Key lifecycle management, 4-level hierarchy, threat-adaptive policies
citadel-api         HTTP server, scoped API key auth, rate limiting, real-time dashboard

Быстрый старт

Docker (рекомендуется)

# Clone
git clone https://github.com/mrcord77/rust_citadel.git
cd rust_citadel

# Set your admin API key
echo -n "your-secret-key" | sha256sum | cut -d' ' -f1
# Copy the hash

# Start
CITADEL_API_KEY_HASH=<paste-hash> docker compose up -d

# Verify
curl http://localhost:3000/health
# {"status":"ok","version":"0.2.0"}

Панель управления: http://localhost:3000

Из исходного кода

Требуется Rust 1.75+.

cargo build --release -p citadel-api
CITADEL_API_KEY="your-secret-key" CITADEL_SEED_DEMO=true ./target/release/citadel-api

Использование

Python

import requests

api = "http://localhost:3000"
headers = {"Authorization": "Bearer your-secret-key"}

# Encrypt
r = requests.post(f"{api}/api/keys/{dek_id}/encrypt", headers=headers, json={
    "plaintext": "sensitive data",
    "aad": "record-001",        # binds ciphertext to this record
    "context": "patient-records" # domain separation
})
blob = r.json()

# Decrypt
r = requests.post(f"{api}/api/decrypt", headers=headers, json={
    "blob": blob,
    "aad": "record-001",
    "context": "patient-records"
})
plaintext = r.json()["plaintext"]

Полный рабочий пример с привязкой AAD, ротацией ключей и поведением приложения с учётом уровня угрозы см. в citadel_example.py.

curl

# Status
curl http://localhost:3000/api/status -H "Authorization: Bearer $KEY"

# List keys
curl http://localhost:3000/api/keys -H "Authorization: Bearer $KEY"

# Encrypt
curl -X POST http://localhost:3000/api/keys/$DEK_ID/encrypt \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"plaintext":"hello","aad":"test","context":"demo"}'

Эндпоинты API

Эндпоинт	Метод	Область действия	Описание
/health	GET	—	Проверка работоспособности
/api/status	GET	read	Уровень угрозы, количество ключей
/api/metrics	GET	read	Показатели безопасности
/api/keys	GET	read	Список всех ключей
/api/keys	POST	manage	Создать новый ключ
/api/keys/:id	GET	read	Сведения о ключе
/api/keys/:id/activate	POST	manage	Активировать ожидающий ключ
/api/keys/:id/rotate	POST	manage	Ротация ключа (новая версия)
/api/keys/:id/revoke	POST	manage	Окончательно отозвать ключ
/api/keys/:id/destroy	POST	manage	Уничтожить ключевой материал
/api/keys/:id/encrypt	POST	encrypt	Зашифровать данные
/api/decrypt	POST	encrypt	Расшифровать данные
/api/threat	GET	read	Данные аналитики угроз
/api/policies	GET	read	Активные политики ключей
/api/auth/whoami	GET	read	Информация о текущем ключе API
/api/auth/keys	GET	admin	Список ключей API
/api/auth/keys	POST	admin	Создать ключ API
/api/auth/keys/:id	DELETE	admin	Отозвать ключ API

Иерархия ключей

Root Key
  └── Domain Key (per environment / business unit)
        └── KEK — Key Encrypting Key (wraps DEKs)
              └── DEK — Data Encrypting Key (encrypts application data)

Соответствует NIST SP 800-57. Каждый уровень ограничивает радиус поражения при компрометации — утёкший DEK не раскрывает другие DEK, поскольку KEK хранится отдельно.

Области действия ключей API

Область действия	Разрешения
read	Просмотр ключей, статуса, метрик, уровня угрозы
encrypt	Шифрование и расшифрование данных
manage	Создание, ротация, отзыв и уничтожение ключей
admin	Всё вышеперечисленное + управление ключами API

Область admin подразумевает все остальные. Принцип минимальных привилегий: панелям мониторинга — read, сервисам приложений — read + encrypt, административным инструментам — admin.

Адаптивная система реагирования на угрозы

Citadel отслеживает события безопасности и автоматически корректирует политики управления ключами:

Уровень	Триггер	Реакция
LOW	Обычная работа	Стандартные криптопериоды
GUARDED	Незначительные аномалии	Чуть более частая ротация
ELEVATED	Подозрительные паттерны	Сокращённые графики ротации
HIGH	Активные индикаторы угроз	Принудительная ротация, сниженные лимиты использования
CRITICAL	Под атакой	Максимальные ограничения

События, повышающие уровень угрозы: неудачная аутентификация, сбои расшифрования, интенсивные обращения, ручная эскалация. Показатель со временем снижается.

Криптография

Компонент	Алгоритм	Стандарт
Инкапсуляция ключа (классическая)	X25519 ECDH	RFC 7748
Инкапсуляция ключа (пост-квантовая)	ML-KEM-768	FIPS 203
Шифрование данных	AES-256-GCM	NIST SP 800-38D
Выработка ключа	HKDF-SHA256	NIST SP 800-56C

Гибридная конструкция: оба общих секрета конкатенируются и пропускаются через HKDF. Безопасность сохраняется, если хотя бы один из алгоритмов — X25519 или ML-KEM-768 — остаётся стойким.

Формат сообщений

version[1] || suite_kem[1] || suite_aead[1] || flags[1] || kem_ct_len[2] ||
x25519_ephemeral_pk[32] || mlkem768_ct[1088] || nonce[12] || aead_ct[variable]

Самодокументируемый, версионируемый, без согласования параметров (предотвращает атаки понижения версии). Полную спецификацию см. в SPEC.md.

Свойства безопасности

• Сравнение за константное время — проверка ключа API через крейт subtle предотвращает атаки по времени
• Зануление — все общие секреты и ключи AES обёрнуты в Zeroizing<T> и зануляются при освобождении
• Единообразные ошибки — при сбоях расшифрования возвращаются идентичные сообщения об ошибке (нет оракула расшифрования)
• Журнал аудита с контролем целостности — хеш-цепочка SHA-256 выявляет подмену журнала
• Ограничение частоты запросов — токен-бакет на каждый IP с эскалацией уровня угрозы при нарушениях

Безопасность

Citadel не проходила независимый аудит.