Passa al contenuto principale

Cifratura del database

Libre WebUI include un servizio di cifratura a livello applicativo per i valori sensibili, prima che vengano scritti nell'archivio.

Metodo di cifratura​

Il backend usa AES-256-GCM tramite il modulo crypto di Node.js. La chiave deve essere di 32 byte, rappresentati da una stringa esadecimale di 64 caratteri:

ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Genera una chiave:

openssl rand -hex 32

Archiviazione della chiave​

Libre WebUI carica la chiave in questo ordine:

  1. ENCRYPTION_KEY dall'ambiente.
  2. Un file .encryption_key persistente sotto il DATA_DIR selezionato.
  3. Solo per un archivio nuovo, una chiave appena generata e scritta in modo durevole in DATA_DIR/.encryption_key prima dell'avvio del database.

Se sia l'ambiente sia il file persistente forniscono una chiave, devono coincidere; altrimenti l'avvio fallisce. Anche uno stato cifrato esistente senza la chiave originale fallisce in modo chiuso: Libre non genera mai una sostituzione per un archivio esistente.

Regole importanti per la chiave​

  • Esegui il backup di ENCRYPTION_KEY insieme al database.
  • Non ruotare la chiave senza un piano di migrazione dei valori cifrati.
  • Se perdi la chiave, i valori cifrati non possono essere recuperati.
  • Cambiare chiave senza ricifrare i dati rende illeggibili i valori cifrati esistenti.

Cosa viene protetto​

La cifratura viene applicata dai percorsi di codice che usano il servizio di cifratura o gli helper di archiviazione cifrata. È destinata ai valori sensibili dell'applicazione, come credenziali e dati privati degli utenti gestiti da tali helper.

Non è una cifratura dell'intero disco, delle pagine SQLite o end-to-end tra utenti e browser. Usa cifratura del disco e HTTPS per questi livelli.

Dati di Work​

La cifratura applicativa non cifra un'intera attività Work. File sorgente e dipendenze sono file normali in volumi Docker con nome e limitati all'attività. Conversazioni Work, risultati degli strumenti, output dei comandi e metadati delle attività vengono salvati in SQLite e non sono cifrati automaticamente solo perché alcuni percorsi di credenziali usano il servizio di cifratura.

Quando necessario, proteggi la directory dei dati Docker e DATA_DIR con controlli di accesso e cifratura del disco. Esegui insieme il backup di database, ENCRYPTION_KEY e volumi Work gestiti. Inviare un'attività Work a un modello remoto può anche comunicare al provider il contesto della conversazione e i file o l'output dei comandi richiesti; la cifratura dell'archivio non modifica questo confine di rete.

Docker e Kubernetes​

Imposta esplicitamente una chiave stabile in produzione:

ENCRYPTION_KEY=replace-with-64-hex-characters
DATA_DIR=/data

Monta DATA_DIR su un archivio persistente. In Kubernetes, conserva la chiave in un Secret e monta i dati su un PersistentVolume.

Risoluzione dei problemi​

Lunghezza della chiave non valida

La chiave deve contenere esattamente 64 caratteri esadecimali. Generane una nuova con:

openssl rand -hex 32

Impossibile decifrare i dati dopo una nuova distribuzione

Verifica di usare la stessa ENCRYPTION_KEY e di aver montato lo stesso volume DATA_DIR.

Lo sviluppo ha generato una nuova chiave

Conserva DATA_DIR/.encryption_key insieme al database. In alternativa puoi impostare lo stesso valore tramite ENCRYPTION_KEY; se entrambe le fonti esistono, devono coincidere.

Documentazione correlata​