Citadel

Servidor de criptografia híbrida pós-quântica e gerenciamento de chaves.

A Citadel combina X25519 + ML-KEM-768 para encapsulamento de chave e AES-256-GCM para criptografia de dados, seguindo a abordagem híbrida do NIST para a transição pós-quântica. Aplicações criptografam e descriptografam dados por meio de uma API REST. A Citadel gerencia as chaves — geração, rotação, revogação, controle de acesso e registro de auditoria.

Status: Implementação funcional. Não auditado. Sem implantações em produção. Consulte Segurança abaixo.

---

O Que Ela Faz

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

Sua aplicação nunca toca no material bruto da chave. O bloco criptografado é autossuficiente — inclui a chave encapsulada, identificadores de algoritmo e o texto cifrado. Armazene-o em qualquer banco de dados. Descriptografe enviando-o de volta à Citadel com o mesmo AAD e contexto.

Arquitetura

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

Início 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"}

Painel: http://localhost:3000

A partir do Código-Fonte

Requer 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 um exemplo completo em funcionamento com vinculação de AAD, rotação de chaves e comportamento de aplicação ciente de ameaças.

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

Endpoint	Método	Escopo	Descrição
/health	GET	—	Verificação de saúde
/api/status	GET	read	Nível de ameaça, contagens de chaves
/api/metrics	GET	read	Métricas de segurança
/api/keys	GET	read	Listar todas as chaves
/api/keys	POST	manage	Gerar nova chave
/api/keys/:id	GET	read	Obter detalhes da chave
/api/keys/:id/activate	POST	manage	Ativar uma chave pendente
/api/keys/:id/rotate	POST	manage	Rotacionar chave (nova versão)
/api/keys/:id/revoke	POST	manage	Revogar chave permanentemente
/api/keys/:id/destroy	POST	manage	Destruir material de chave
/api/keys/:id/encrypt	POST	encrypt	Criptografar dados
/api/decrypt	POST	encrypt	Descriptografar dados
/api/threat	GET	read	Detalhes de inteligência de ameaças
/api/policies	GET	read	Políticas de chave ativas
/api/auth/whoami	GET	read	Informações da chave de API atual
/api/auth/keys	GET	admin	Listar chaves de API
/api/auth/keys	POST	admin	Criar chave de API
/api/auth/keys/:id	DELETE	admin	Revogar chave de API

Hierarquia de Chaves

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

Segue o NIST SP 800-57. Cada nível contém o raio de impacto de um comprometimento — uma DEK vazada não expõe outras DEKs porque a KEK é separada.

Escopos de Chave de API

Escopo	Permissões
read	Visualizar chaves, status, métricas, nível de ameaça
encrypt	Criptografar e descriptografar dados
manage	Criar, rotacionar, revogar, destruir chaves
admin	Tudo acima + gerenciar chaves de API

admin implica todos os outros escopos. Princípio do menor privilégio: conceda read a painéis de monitoramento, read + encrypt a serviços de aplicação e admin a ferramentas administrativas.

Sistema Adaptativo de Ameaças

A Citadel monitora eventos de segurança e ajusta automaticamente as políticas de chaves:

Nível	Gatilho	Resposta
LOW	Operações normais	Períodos criptográficos padrão
GUARDED	Anomalias menores	Rotação ligeiramente mais restrita
ELEVATED	Padrões suspeitos	Cronogramas de rotação compactados
HIGH	Indicadores de ameaça ativos	Rotação forçada, limites de uso reduzidos
CRITICAL	Sob ataque	Restrições máximas

Eventos que elevam o nível de ameaça: autenticação falha, falhas de descriptografia, padrões de acesso rápidos, escalonamento manual. A pontuação decai ao longo do tempo.

Criptografia

Componente	Algoritmo	Padrão
Encapsulamento de chave (clássico)	X25519 ECDH	RFC 7748
Encapsulamento de chave (pós-quântico)	ML-KEM-768	FIPS 203
Criptografia de dados	AES-256-GCM	NIST SP 800-38D
Derivação de chave	HKDF-SHA256	NIST SP 800-56C

Construção híbrida: ambos os segredos compartilhados são concatenados e alimentados por meio de HKDF. A segurança é mantida se qualquer um entre X25519 ou ML-KEM-768 permanecer seguro.

Formato de Transmissão

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]

Autodescritivo, versionado, sem negociação (previne ataques de downgrade). Consulte SPEC.md para a especificação completa.

Propriedades de Segurança

• Comparação em tempo constante — a verificação de chave de API via crate subtle previne ataques de temporização
• Zeroização — Todos os segredos compartilhados e chaves AES envolvidos em Zeroizing<T>, zerados ao serem descartados
• Erros uniformes — Falhas de descriptografia retornam mensagens de erro idênticas (sem oráculo de descriptografia)
• Log de auditoria com encadeamento de integridade — cadeia de hash SHA-256 detecta adulteração de log
• Limite de taxa — bucket de tokens por IP com escalonamento de ameaça em violações

Segurança

A Citadel é um software não auditado.