Citadel

Server di crittografia ibrida post-quantum e gestione delle chiavi.

Citadel combina X25519 + ML-KEM-768 per l'incapsulamento delle chiavi e AES-256-GCM per la crittografia dei dati, seguendo l'approccio ibrido del NIST per la transizione post-quantum. Le applicazioni crittografano e decrittografano i dati tramite un'API REST. Citadel gestisce le chiavi — generazione, rotazione, revoca, controllo degli accessi e registrazione audit.

Stato: Implementazione funzionante. Non sottoposta ad audit. Nessun dispiegamento in produzione. Vedi Sicurezza più sotto.

---

Cosa fa

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

La tua applicazione non tocca mai il materiale chiave grezzo. Il blob crittografato è auto-contenuto — include la chiave avvolta, gli identificatori dell'algoritmo e il ciphertext. Puoi conservarlo in qualsiasi database. Per decrittografare, invialo indietro a Citadel con lo stesso AAD e contesto.

Architettura

citadel-envelope    Nucleo di crittografia ibrida (X25519 + ML-KEM-768 + AES-256-GCM)
citadel-keystore    Gestione del ciclo di vita delle chiavi, gerarchia a 4 livelli, politiche adattive alle minacce
citadel-api         Server HTTP, autenticazione tramite chiave API con ambiti, limitazione di velocità, dashboard in tempo reale

Avvio rapido

Docker (consigliato)

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

# Imposta la tua chiave API admin
echo -n "your-secret-key" | sha256sum | cut -d' ' -f1
# Copia l'hash

# Avvia
CITADEL_API_KEY_HASH=<incolla-hash> docker compose up -d

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

Dashboard: http://localhost:3000

Da sorgente

Richiede Rust 1.75+.

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

Utilizzo

Python

import requests

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

# Crittografa
r = requests.post(f"{api}/api/keys/{dek_id}/encrypt", headers=headers, json={
    "plaintext": "sensitive data",
    "aad": "record-001",        # lega il ciphertext a questo record
    "context": "patient-records" # separazione di dominio
})
blob = r.json()

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

Vedi citadel_example.py per un esempio funzionante completo con binding AAD, rotazione delle chiavi e comportamento dell'applicazione sensibile alle minacce.

curl

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

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

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

Endpoint API

Endpoint	Metodo	Ambito	Descrizione
/health	GET	—	Controllo di integrità
/api/status	GET	read	Livello di minaccia, conteggio chiavi
/api/metrics	GET	read	Metriche di sicurezza
/api/keys	GET	read	Elenca tutte le chiavi
/api/keys	POST	manage	Genera nuova chiave
/api/keys/:id	GET	read	Ottieni dettagli chiave
/api/keys/:id/activate	POST	manage	Attiva una chiave in sospeso
/api/keys/:id/rotate	POST	manage	Ruota chiave (nuova versione)
/api/keys/:id/revoke	POST	manage	Revoca permanentemente chiave
/api/keys/:id/destroy	POST	manage	Distruggi materiale chiave
/api/keys/:id/encrypt	POST	encrypt	Crittografa dati
/api/decrypt	POST	encrypt	Decrittografa dati
/api/threat	GET	read	Dettagli intelligence sulle minacce
/api/policies	GET	read	Politiche chiave attive
/api/auth/whoami	GET	read	Info chiave API corrente
/api/auth/keys	GET	admin	Elenca chiavi API
/api/auth/keys	POST	admin	Crea chiave API
/api/auth/keys/:id	DELETE	admin	Revoca chiave API

Gerarchia delle chiavi

Root Key
  └── Domain Key (per ambiente / business unit)
        └── KEK — Key Encrypting Key (avvolge DEK)
              └── DEK — Data Encrypting Key (crittografa i dati dell'applicazione)

Segue NIST SP 800-57. Ogni livello contiene il raggio di esplosione di una compromissione — una DEK divulgata non espone altre DEK perché la KEK è separata.

Ambiti delle chiavi API

Ambito	Permessi
read	Visualizza chiavi, stato, metriche, livello di minaccia
encrypt	Crittografa e decrittografa dati
manage	Crea, ruota, revoca, distruggi chiavi
admin	Tutto quanto sopra + gestisci chiavi API

admin implica tutti gli altri ambiti. Principio del minimo privilegio: assegna dashboard di monitoraggio a read, servizi applicativi a read + encrypt, strumenti di amministrazione a admin.

Sistema di minaccia adattivo

Citadel monitora gli eventi di sicurezza e regola automaticamente le politiche chiave:

Livello	Attivazione	Risposta
BASSO	Operazioni normali	Periodi crittografici standard
GUARDATO	Anomalie minori	Rotazione leggermente più stretta
ELEVATO	Modelli sospetti	Programmi di rotazione compressi
ALTO	Indicatori di minaccia attivi	Rotazione forzata, limiti di utilizzo ridotti
CRITICO	Sotto attacco	Restrizioni massime

Eventi che aumentano il livello di minaccia: autenticazione fallita, fallimenti di decrittografia, modelli di accesso rapidi, escalation manuale. Il punteggio decade nel tempo.

Crittografia

Componente	Algoritmo	Standard
Incapsulamento chiave (classico)	X25519 ECDH	RFC 7748
Incapsulamento chiave (post-quantum)	ML-KEM-768	FIPS 203
Crittografia dati	AES-256-GCM	NIST SP 800-38D
Derivazione chiave	HKDF-SHA256	NIST SP 800-56C

Costruzione ibrida: entrambi i segreti condivisi vengono concatenati e alimentati tramite HKDF. La sicurezza è garantita se uno qualsiasi tra X25519 o ML-KEM-768 rimane sicuro.

Formato wire

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]

Auto-descrittivo, versionato, senza negoziazione (previene attacchi di downgrade). Vedi SPEC.md per la specifica completa.

Proprietà di sicurezza