Citadel

Servidor de cifrado híbrido post-cuántico y gestión de claves.

Citadel combina X25519 + ML-KEM-768 para encapsulación de claves y AES-256-GCM para cifrado de datos, siguiendo el enfoque híbrido del NIST para la transición post-cuántica. Las aplicaciones cifran y descifran datos a través de una API REST. Citadel gestiona las claves — generación, rotación, revocación, control de acceso y registro de auditoría.

Estado: Implementación funcional. Sin auditoría. Sin despliegues en producción. Consulte Seguridad a continuación.

---

Qué Hace

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

Su aplicación nunca toca material clave en bruto. El blob cifrado es autocontenido — incluye la clave envuelta, identificadores de algoritmo y texto cifrado. Almacénelo en cualquier base de datos. Descífrelo enviándolo de vuelta a Citadel con el mismo AAD y contexto.

Arquitectura

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

Inicio rápido

Docker (recomendado)

# 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"}

Panel: http://localhost:3000

Desde el código fuente

Requiere Rust 1.75+.

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

Uso

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"]

Consulte citadel_example.py para un ejemplo completo funcional con vinculación AAD, rotación de claves y comportamiento de aplicación consciente de amenazas.

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"}'

Endpoints de la API

Endpoint	Método	Ámbito	Descripción
/health	GET	—	Comprobación de salud
/api/status	GET	read	Nivel de amenaza, conteos de claves
/api/metrics	GET	read	Métricas de seguridad
/api/keys	GET	read	Listar todas las claves
/api/keys	POST	manage	Generar nueva clave
/api/keys/:id	GET	read	Obtener detalles de la clave
/api/keys/:id/activate	POST	manage	Activar una clave pendiente
/api/keys/:id/rotate	POST	manage	Rotar clave (nueva versión)
/api/keys/:id/revoke	POST	manage	Revocar clave permanentemente
/api/keys/:id/destroy	POST	manage	Destruir material de clave
/api/keys/:id/encrypt	POST	encrypt	Cifrar datos
/api/decrypt	POST	encrypt	Descifrar datos
/api/threat	GET	read	Detalles de inteligencia de amenazas
/api/policies	GET	read	Políticas de clave activas
/api/auth/whoami	GET	read	Información de la clave API actual
/api/auth/keys	GET	admin	Listar claves API
/api/auth/keys	POST	admin	Crear clave API
/api/auth/keys/:id	DELETE	admin	Revocar clave API

Jerarquía de Claves

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

Sigue NIST SP 800-57. Cada nivel contiene el radio de explosión de un compromiso — una DEK filtrada no expone otras DEK porque la KEK es independiente.

Ámbitos de Clave de API

Ámbito	Permisos
read	Ver claves, estado, métricas, nivel de amenaza
encrypt	Cifrar y descifrar datos
manage	Crear, rotar, revocar, destruir claves
admin	Todo lo anterior + gestionar claves de API

admin implica todos los demás ámbitos. Principio de mínimo privilegio: asigne a los paneles de monitoreo read, servicios de aplicación read + encrypt, herramientas de administración admin.

Sistema de Amenazas Adaptativo

Citadel monitorea eventos de seguridad y ajusta automáticamente las políticas de clave:

Nivel	Desencadenante	Respuesta
LOW	Operaciones normales	Períodos criptográficos estándar
GUARDED	Anomalías menores	Rotación ligeramente más ajustada
ELEVATED	Patrones sospechosos	Horarios de rotación comprimidos
HIGH	Indicadores de amenaza activos	Rotación forzada, límites de uso reducidos
CRITICAL	Bajo ataque	Restricciones máximas

Eventos que elevan el nivel de amenaza: autenticación fallida, fallos de descifrado, patrones de acceso rápidos, escalada manual. La puntuación decae con el tiempo.

Criptografía

Componente	Algoritmo	Estándar
Encapsulación de clave (clásica)	X25519 ECDH	RFC 7748
Encapsulación de clave (post-cuántica)	ML-KEM-768	FIPS 203
Cifrado de datos	AES-256-GCM	NIST SP 800-38D
Derivación de clave	HKDF-SHA256	NIST SP 800-56C

Construcción híbrida: ambos secretos compartidos se concatenan y se alimentan a través de HKDF. La seguridad se mantiene si cualquiera de X25519 o ML-KEM-768 permanece seguro.

Formato de Cable

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]

Autodescriptivo, versionado, sin negociación (evita ataques de degradación). Consulte SPEC.md para la especificación completa.

Propiedades de Seguridad

• Comparación en tiempo constante — Verificación de clave API mediante el crate subtle previene ataques de temporización
• Zeroización — Todos los secretos compartidos y claves AES envueltos en Zeroizing<T>, puestos a cero al soltarlos
• Errores uniformes — Los fallos de descifrado devuelven mensajes de error idénticos (sin oráculo de descifrado)
• Registro de auditoría encadenado por integridad — Cadena hash SHA-256 detecta manipulación del registro
• Limitación de velocidad — Cubo de tokens por IP con escalada de amenazas en caso de violaciones

Seguridad

Citadel es software no auditado.