Saltar al contenido principal

Cifrado de la base de datos

Libre WebUI incluye un servicio de cifrado en la aplicación para proteger los valores confidenciales antes de escribirlos en el almacenamiento.

Método de cifrado​

El backend utiliza AES-256-GCM mediante el módulo criptográfico de Node.js. La clave debe tener 32 bytes, representados por una cadena hexadecimal de 64 caracteres:

ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Genera una clave:

openssl rand -hex 32

Almacenamiento de la clave​

Libre WebUI carga la clave en este orden:

  1. ENCRYPTION_KEY desde el entorno.
  2. Un archivo persistente .encryption_key en el DATA_DIR seleccionado.
  3. Solo en un almacenamiento nuevo, una clave recién generada que se escribe de forma duradera en DATA_DIR/.encryption_key antes de iniciar la base de datos.

Si tanto el entorno como el archivo persistente proporcionan una clave, deben coincidir o el inicio falla. Un estado cifrado existente sin su clave original también produce un fallo seguro; Libre nunca genera una sustituta para un almacenamiento existente.

Reglas importantes de las claves​

  • Guarda una copia de ENCRYPTION_KEY con la base de datos.
  • No rotes la clave sin un plan para migrar los valores cifrados.
  • Si pierdes la clave, no podrás recuperar los valores cifrados.
  • Cambiarla sin volver a cifrar los datos hará ilegibles los valores existentes.

Qué protege​

El cifrado se aplica en las rutas de código que utilizan el servicio de cifrado o los auxiliares de almacenamiento cifrado. Está diseñado para valores confidenciales, como credenciales y datos privados gestionados por esos auxiliares.

No es cifrado de disco completo, de páginas SQLite ni de extremo a extremo entre usuarios y navegador. Utiliza cifrado de disco y HTTPS para esas capas.

Datos de Work​

El cifrado de la aplicación no cifra una tarea de Work completa. Los archivos fuente y las dependencias del proyecto son archivos normales en volúmenes Docker con nombre propios de cada tarea. Las conversaciones, resultados de herramientas, salidas de comandos y metadatos de Work se almacenan en SQLite y no se cifran automáticamente porque algunas rutas de credenciales utilicen el servicio.

Protege la raíz de datos de Docker y DATA_DIR con controles de acceso y cifrado de disco cuando sea necesario. Haz copias conjuntas de la base de datos, ENCRYPTION_KEY y los volúmenes de Work administrados. Enviar una tarea de Work a un modelo remoto también puede revelar al proveedor el contexto y las salidas solicitadas; el cifrado del almacenamiento no cambia ese límite de red.

Docker y Kubernetes​

Define expresamente una clave estable para producción:

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

Monta DATA_DIR en almacenamiento persistente. En Kubernetes, guarda la clave en un Secret y monta los datos en un PersistentVolume.

Solución de problemas​

Longitud de clave no válida

La clave debe tener exactamente 64 caracteres hexadecimales. Genera una nueva con:

openssl rand -hex 32

No se pueden descifrar los datos tras volver a desplegar

Confirma que se utilicen el mismo ENCRYPTION_KEY y el mismo volumen DATA_DIR.

El desarrollo generó una clave nueva

Conserva DATA_DIR/.encryption_key con la base de datos. También puedes definir el mismo valor mediante ENCRYPTION_KEY; si existen ambas fuentes, deben coincidir.

Documentación relacionada​