Ротация ключа шифрования

В процессе ротации ключа шифрования необходимо перешифровать базу данных. На время выполнения этой операции, Пассворк переводится в сервисный режим: веб-интерфейс и автоматизации становятся недоступны.

осторожно

Перед ротацией обязательно должна быть создана резервная копия базы данных Пассворка (MongoDB или PostgreSQL) и ключа шифрования encryption_key.

Примеры создания и восстановления резервных копий

Общие сведения

При ротации Пассворк получает текущий ключ из encryption_key или из переменной окружения ENCRYPTION_KEY, проверяет его соответствие внутренним настройкам и читает новый ключ из файла new_encryption_key.

После успешного завершения ротации, new_encryption_key заменяет текущий encryption_key. Старый ключ сохраняется в этой же директории с временной меткой.

Порядок выполнения

Включение сервисного режима

При включении сервисного режима, закрывается доступ к веб-интерфейсу и автоматизациям использущим API. Его включение является обязательным условием:

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

Генерация нового ключа шифрования

Для создания нового ключа шифрования и его последующего сохранения в файл 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

к сведению

Если файл new_encryption_key уже существует, команда завершится с ошибкой.

Проверочный запуск

Команда encryption-key:update без параметра --apply работает в режиме 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

Разбор вывода

Колонка	Описание
Found	Количество найденных записей или значений, которые подходят для проверки на этом этапе. Значение 0 означает, что таких данных в базе нет.
Processed	Количество значений, которые команда смогла успешно проверить: расшифровать старым ключом и подготовить к шифрованию новым ключом.
Skipped	Количество найденных записей, которые не требуют обработки или не содержат значения для перешифровки. Например, SMTP-настройки могут быть найдены, но пароль может отсутствовать.
Restored	Количество значений, которые были пропущены при повторном запуске после прерывания, потому что их состояние уже отличается от сохранённого промежуточного состояния. В обычном dry-run равно 0.
Conflicts	Количество конфликтов при продолжении прерванной операции. Например, если ранее сохранённая для продолжения запись больше не найдена. В обычном dry-run равно 0.
Seconds	Время выполнения конкретного этапа в секундах.

осторожно

Если dry-run завершился с ошибкой, то перешифрование невозможно до устранения причин ошибок.

Применение перешифровки

Параметр --apply запускает изменение данных. Перед началом применения команда выводит предупреждение и запрашивает подтверждение:

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

После успешного завершения:

• Зашифрованные значения в базе данных будут перешифрованы новым ключом;
• Файл new_encryption_key будет переименован в encryption_key;
• Старый encryption_key будет переименован в backup-файл encryption_key.<дата_и_время>.bak.

Отключение сервисного режима

После успешного завершения перешифровки сервисный режим необходимо отключить, чтобы вернуть доступ к веб-интерфейсу и автоматизациям Пассворка:

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

осторожно

Сервисный режим не следует отключать до успешного завершения — encryption-key:update --apply.

Если выполнение было прервано

Если выполнение команды было прервано, перешифрование можно запустить повторно. Пассворк сохраняет состояние операции и продолжает обработку с места, на котором остановилась предыдущая попытка.

Для продолжения необходимо использовать тот же файл 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

к сведению

Если ошибка произошла после замены файла encryption_key, будет выполнена попытка восстановить старый файл ключа из backup-файла.

Проверки и ограничения

Команда encryption-key:update не начнёт выполнение, если:

• Сервисный режим выключен;
• Текущий ключ шифрования не соответствует хэшу в базе данных;
• Файл new_encryption_key отсутствует или повреждён.

После успешной ротации необходимо проверить работу Пассворка и убедиться, что пользователи могут открыть данные. Удалять backup старого ключа рекомендуется только после проверки работоспособности и подтверждения корректности резервной копии.

Версия для LLM