Rotación de la clave de cifrado

Durante la rotación de la clave de cifrado, la base de datos debe recifrarse. Mientras esta operación se ejecuta, Passwork cambia al modo de servicio: la interfaz web y las automatizaciones dejan de estar disponibles.

peligro

Antes de la rotación, debe crear una copia de seguridad de la base de datos de Passwork y de encryption_key.

Ejemplos de creación y restauración de copias de seguridad

Información general

Durante la rotación, Passwork lee la clave actual desde encryption_key o desde la variable de entorno ENCRYPTION_KEY, comprueba que coincida con la configuración interna y lee la nueva clave desde el archivo new_encryption_key.

Una vez completada correctamente la rotación, new_encryption_key reemplaza a la encryption_key actual. La clave antigua se guarda en el mismo directorio con una marca de tiempo.

Procedimiento

Activación del modo de servicio

Cuando el modo de servicio está activado, se cierra el acceso a la interfaz web y a las automatizaciones que usan el API. Es necesario activar el modo de servicio:

DEB

sudo -u www-data bash -c 'cd /var/www && php bin/console app:service-mode enable'

RPM

sudo -u apache bash -c 'cd /var/www && php bin/console app:service-mode enable'

Docker

docker compose exec -T php-fpm sh -c 'cd /server/www && php bin/console app:service-mode enable'

PowerShell

cd "C:\inetpub\wwwroot\passwork"
php .\bin\console app:service-mode enable

Generación de una nueva clave de cifrado

Para crear una nueva clave de cifrado y guardarla en el archivo new_encryption_key:

DEB

sudo -u www-data bash -c 'cd /var/www && php bin/console encryption-key:generate'

RPM

sudo -u apache bash -c 'cd /var/www && php bin/console encryption-key:generate'

Docker

docker compose exec -T php-fpm sh -c 'cd /server/www && php bin/console encryption-key:generate'

PowerShell

php .\bin\console encryption-key:generate

info

Si el archivo new_encryption_key ya existe, el comando fallará.

Ejecución de prueba (dry run)

El comando encryption-key:update sin el parámetro --apply se ejecuta en modo dry-run:

DEB

sudo -u www-data bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --ansi'

RPM

sudo -u apache bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --ansi'

Docker

docker compose exec -T php-fpm sh -c 'cd /server/www && php -d memory_limit=-1 bin/console encryption-key:update --ansi'

PowerShell

php -d "memory_limit=-1" .\bin\console encryption-key:update --ansi

Explicación de la salida

Columna	Descripción
Found	Número de registros o valores encontrados que son adecuados para la verificación en esta etapa. Un valor de 0 significa que no existen dichos datos en la base de datos.
Processed	Número de valores que el comando verificó correctamente: descifrados con la clave antigua y preparados para el cifrado con la nueva clave.
Skipped	Número de registros encontrados que no requieren procesamiento o que no contienen valores para recifrar. Por ejemplo, se pueden encontrar configuraciones SMTP, pero la contraseña puede estar ausente.
Restored	Número de valores omitidos durante una nueva ejecución tras una interrupción, porque su estado ya difiere del estado intermedio guardado. En una ejecución de prueba normal, este valor es 0.
Conflicts	Número de conflictos al continuar una operación interrumpida. Por ejemplo, si un registro guardado anteriormente para continuar ya no se puede encontrar. En una ejecución de prueba normal, este valor es 0.
Seconds	Tiempo de ejecución de una etapa específica en segundos.

peligro

Si el dry-run finaliza con un error, el recifrado no será posible hasta que se resuelvan las causas de los errores.

Aplicación del recifrado

El parámetro --apply inicia la modificación de datos. Antes de aplicar los cambios, el comando muestra una advertencia y solicita confirmación:

DEB

sudo -u www-data bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'

RPM

sudo -u apache bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'

Docker

docker compose exec -T php-fpm sh -c 'cd /server/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'

PowerShell

php -d "memory_limit=-1" .\bin\console encryption-key:update --apply

Después de una finalización correcta:

• Los valores cifrados en la base de datos se recifrarán con la nueva clave;
• El archivo new_encryption_key se renombrará a encryption_key;
• El archivo encryption_key antiguo se renombrará al archivo de copia de seguridad encryption_key.<date_and_time>.bak.

Desactivación del modo de servicio

Una vez completado correctamente el recifrado, se debe desactivar el modo de servicio para restaurar el acceso a la interfaz web de Passwork y a las automatizaciones:

DEB

sudo -u www-data bash -c 'cd /var/www && php bin/console app:service-mode disable'

RPM

sudo -u apache bash -c 'cd /var/www && php bin/console app:service-mode disable'

Docker

docker compose exec -T php-fpm sh -c 'cd /server/www && php bin/console app:service-mode disable'

PowerShell

php .\bin\console app:service-mode disable

peligro

El modo de servicio no debe desactivarse antes de que encryption-key:update --apply finalice correctamente.

Si la ejecución se interrumpió

Si la ejecución del comando se interrumpió, el recifrado se puede reiniciar. Passwork guarda el estado de la operación y continúa el procesamiento desde el punto en que se detuvo el intento anterior.

Para continuar, use el mismo archivo new_encryption_key:

DEB

sudo -u www-data bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'

RPM

sudo -u apache bash -c 'cd /var/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'

Docker

docker compose exec -T php-fpm sh -c 'cd /server/www && php -d memory_limit=-1 bin/console encryption-key:update --apply'

PowerShell

php -d "memory_limit=-1" .\bin\console encryption-key:update --apply

info

Si se produce un error después de que se haya reemplazado el archivo encryption_key, Passwork intentará restaurar el archivo de la clave antigua desde el archivo de copia de seguridad.

Comprobaciones y limitaciones

El comando encryption-key:update no se iniciará si:

• El modo de servicio está desactivado;
• La clave de cifrado actual no coincide con el hash de la base de datos;
• El archivo new_encryption_key falta o está dañado.

Después de una rotación correcta, compruebe que Passwork funciona correctamente y asegúrese de que los usuarios puedan abrir los datos. Elimine la copia de seguridad de la clave antigua solo después de verificar el funcionamiento y confirmar que la copia de seguridad es correcta.