Утилита переноса (миграции) данных между КриптоПро DSS и КриптоПро Ключ DSStoKey

Утилита переноса (миграции) данных между КриптоПро DSS и КриптоПро Ключ `DSStoKey`

Утилита DSStoKey позволяет перенести пользовательские данные, конфигурацию сервисов и сервисные сертификаты КриптоПро DSS в соответствующие сервисы КриптоПро Ключ. Доступен перенос данных для компонентов, имеющих базу данных:

Центр Идентификации,
Сервис Подписи,
БД Сервиса Операций,
Сервис Аудита,
Сервис Обработки Документов.

Подготовительные мероприятия

См. также:

Планирование перехода с КриптоПро DSS на КриптоПро Ключ;
Учетной записи, из под которой будет произведен запуск утилиты, требуются права на запись в папку утилиты, права на доступ к реестру и к закрытым ключам сервисных сертификатов;
Требуется создание экземпляров всех перечисленных сервисов на сервере с КриптоПро Ключ до того, как будет начат перенос данных;
На исходном сервере (КриптоПро DSS) требуется доверие к TLS-сертификатам баз данных (и MSSQL исходного сервера, и Postgres целевого);
Для доступа к БД целевого и исходного серверов требуется наличие учетных записей доступа к БД (логин/пароль): для MSSQL с правами на чтение всех таблиц БД КриптоПро DSS, а в Postgres на запись во все таблицы БД КриптоПро Ключ.

Внимание!

Требуется сверить форматы даты и времени на исходном и целевом серверах. В случае если они не совпадают, необходимо воспользоваться параметром datetimeformat.

Описание процедуры переноса данных

Для каждого набора данных (таблицы) переносятся данные из БД КриптоПро DSS в соответствующие БД КриптоПро Ключ в соответствии с выбранным режимом переноса.
Валидация данных не производится.
При переносе любых параметров, связанных с URL-адресами, выполняется подмена адресов в соответствии с параметрами запуска утилиты.

Порядок работы с утилитой

Утилита DSStoKey принимает на вход путь к файлу с параметрами миграции migration_options.json. Для удобства использования можно создать несколько файлов, чтобы переносить данные каждого экземпляра по отдельности.

Примечание

Если в КриптоПро DSS существуют пользователи, созданные до конца 2020 года И до обновления на версию 2.0.3222, то миграцию Центра Идентификации и Сервиса Подписи необходимо выполнять ОДНОВРЕМЕННО (в рамках одного запуска утилиты: в файле конфигурации утилиты должны быть заполнены обе структуры IdSrv и SignSrv). В противном случае пользователи, созданные ранее описанных выше событий, потеряют доступ к своим сертификатам и ключам.

Порядок действий на целевом сервере (КриптоПро Ключ):

Установить КриптоПро Ключ,
Развернуть экземпляры переносимых компонентов,
Скопировать адреса созданных приложений и строки подключения к созданным БД (например, в текстовый файл).

Порядок действий на исходном сервере (КриптоПро DSS):

Обновить КриптоПро DSS (необходимо согласовать версию, обратившись по адресу dsssupport@cryptopro.ru),
Извлечь утилиту миграции в папку, откуда будет произведен запуск. Требуются права на запись внутри данной папки,
Заполнить полученными с целевой машины данными файл конфигурации утилиты migration_options.json (см. параметры утилиты),
Остановить переносимые сервисы КриптоПро DSS (или обеспечить отсутствие операций создания/удаления пользователей и/или сертификатов),
Запустить утилиту с правами администратора: .\dm.exe --options ".\migration_options.json" и дождаться окончания выполнения переноса данных.

Порядок действий на целевом сервере (КриптоПро Ключ):

Проверить перенесенные настройки (адреса приложений, сервисные сертификаты и т.д.),
Проверить перенесенные Мастер-ключи криптопровайдеров в подпапке _ExportedKeys папки с утилитой. В случае их успешного переноса переместить содержимое подпапки в /var/opt/cprocsp/keys/ и назначить права на владение учетной записи, из-под которой работают сервисы КриптоПро Ключ, использующие данные ключи,
Перезагрузить экземпляры сервисов (Restart-*Instance).

Конфигурационный файл утилиты

Примечание

Для незаполненных параметров будет установлено значение по умолчанию: NULL для объектов и строковых; false - для булевых. При работе утилиты такие параметры могут вызывать ошибки. Рекомендуется удалять или комментировать неиспользуемые объекты и параметры. Для удобства использования можно создать несколько файлов, чтобы переносить данные каждого экземпляра по отдельности.

Пример конфигурации утилиты DSStoKey migration_options.json

Журналирование работы утилиты

Ключ	Значение
LogLevel	Минимальный уровень логирования: "Information" или "Warning"
LogFile	Путь к файлу журнала

Пример:

  "LogLevel": "Warning", /* Минимальный уровень логирования: "Information" или "Warning" */
  "LogFile": "_log.txt",

Дополнительно утилита после выполнения переноса создает в собственной папке файлы, содержащие информацию о перенесенных данных Центра Идентификации (IdSrv) и Сервиса Подписи (SignSrv) следующего вида:

_migration_report_SignSrv_%DateTime%.txt
_migration_report_IdSrv_%DateTime%.txt
_migration_report_SignSrv_last.txt
_migration_report_IdSrv_last.txt

Файлы, имеющие в имени дату и время, содержат информацию о перенесенных данных на указанный момент времени, а файлы, содержащие last в имени, - соответствуют последнему выполненному переносу при помощи утилиты. Данные файлы могут быть использованы как "точки сохранения", от которых начнется работа утилиты при добавлении пользовательских данных к уже существующим.

Центр Идентификации (объект `IdSrv`)

Ключ	Значение
SourceDatabase	Строка подключения к исходной БД
TargetDatabase	Строка подключения к целевой БД
TargetOperationsDatabase	Строка подключения к целевой БД Сервиса Операций
CommandTimeoutSeconds	Максимальное время выполнения одного SQL-запроса к БД
MigrationMode	Режим переноса данных
TopUpDataInfoFile	Путь к файлу с информацией о переносе пользовательских данных, который будет служить точкой отсчета при добавлении новых пользовательских данных к существующим
DataBatchSize	Количество строк таблиц, переписываемое за одну пакетную вставку в целевую БД
SessionIdHostMap	Отображение ("маппинг") имени узла в конфигурации генератора сессий SessionIdHostConfiguration (текущее значение можно посмотреть в выводе командлета Get-IdsSessionIdhostConfiguration/Get-DssSessionIdHostConfiguration)

Примечание

В настройках переноса для Центра Идентификации и Сервиса Подписи должна быть указана одна и та же целевая БД Сервиса Операций (TargetOperationsDatabase).

После выполнения миграции Центра Идентификации необходима донастройка OAuth-клиента Веб-интерфейса. Для этого необходимо выполнить следующие команды:

# Получение списка зарегистрированных клиентов с целью установления идентификатора клиента для Веб-интерфейса
Get-IdsClient

# Настройка клиента Веб-интерфейса
Set-IdsClient -ClientId <Id OAuth-клиента Веб-интерфейса> -ElevateLoa $true

Пример:

  "IdSrv": {
    "SourceDatabase": "Data Source=.\\SQLEXPRESS;Initial Catalog=IdentityServiceDB;Integrated Security=True;Persist Security Info=False;TrustServerCertificate=True",
    "TargetDatabase": "Username=username;Password=password;Host=192.168.0.1;Port=5050;Database=IdentityServiceMigrUtilTestDb;Include Error Detail=true",
    "TargetOperationsDatabase": "Username=username;Password=password;Host=192.168.0.1;Port=5050;Database=OperationsDb;Include Error Detail=true",

    "CommandTimeoutSeconds": 60,

    "MigrationMode": "CleanupData, CleanupConfig, MigrateConfig, MigrateData",

    "TopUpDataInfoFile": "_migration_report_IdSrv_last.txt",

    "DataBatchSize": 1000, /* Количество строк таблиц, переписываемое за одну пакетную вставку в целевую БД */

    /* Маппинг хостов в конфигурации генератора сессий SessionIdHostConfiguration */
    "SessionIdHostMap": { "host1": "host2" }
  },

Сервис Подписи (объект `SignSrv`)

Ключ	Значение
SourceDatabase	Строка подключения к исходной БД
TargetDatabase	Строка подключения к целевой БД
TargetOperationsDatabase	Строка подключения к целевой БД Сервиса Операций
SignServiceCommonSourceDatabase	Строка подключения к исходной БД Common Сервиса Подписи
SignServiceCommonTargetDatabase	Строка подключения к целевой БД Common Сервиса Подписи
CommandTimeoutSeconds	Максимальное время выполнения одного SQL-запроса к БД
MigrationMode	Режим переноса данных
TopUpDataInfoFile	Путь к файлу с информацией о переносе пользовательских данных, который будет служить точкой отсчета при добавлении новых пользовательских данных к существующим
DataBatchSize	Количество строк таблиц, переписываемое за одну пакетную вставку в целевую БД

Примечание

Пример:

  "SignSrv": {
    "SourceDatabase": "Data Source=.\\SQLEXPRESS;Initial Catalog=SignatureServerDB;Integrated Security=True;Persist Security Info=False;TrustServerCertificate=True",
    "TargetDatabase": "Username=username;Password=password;Host=192.168.0.2;Port=5051;Database=SignServerMigrUtilTestDb;Include Error Detail=true",
    "TargetOperationsDatabase": "Username=username;Password=password;Host=192.168.0.1;Port=5050;Database=OperationsDb;Include Error Detail=true",
    "SignServiceCommonSourceDatabase": "Data Source=.\\SQLEXPRESS;Initial Catalog=SignatureServerCommonDB;Integrated Security=True;Persist Security Info=False;TrustServerCertificate=True",
    "SignServiceCommonTargetDatabase": "Username=username;Password=password;Host=192.168.0.3;Port=5050;Database=SignatureServerCommonDb;Include Error Detail=true",

    "CommandTimeoutSeconds": 60,

    "MigrationMode": "CleanupData, CleanupConfig, MigrateConfig, MigrateData",

    "TopUpDataInfoFile": "_migration_report_SignSrv_last.txt",

    "DataBatchSize": 1000 /* Количество строк таблиц, переписываемое за одну пакетную вставку в целевую БД */
  },

Сервис Обработки Документов (объект `DocSrv`)

Ключ	Значение
SourceDatabase	Строка подключения к исходной БД
TargetDatabase	Строка подключения к целевой БД
CommandTimeoutSeconds	Максимальное время выполнения одного SQL-запроса к БД
MigrationMode	Режим переноса данных

Пример:

  "DocSrv": {
    "SourceDatabase": "Data Source=.\\SQLEXPRESS;Initial Catalog=DocumentStoreDB;Integrated Security=True;Persist Security Info=False;TrustServerCertificate=True",
    "TargetDatabase": "Username=username;Password=password;Host=192.168.0.4;Port=5050;Database=DocumentStoreMigrUtilTestDb;Include Error Detail=true",

    "CommandTimeoutSeconds": 60,

    "MigrationMode": "CleanupData, CleanupConfig, MigrateConfig"
  },

Сервис Аудита (объект `AuditSrv`)

Ключ	Значение
SourceDatabase	Строка подключения к исходной БД
TargetDatabase	Строка подключения к целевой БД
CommandTimeoutSeconds	Максимальное время выполнения одного SQL-запроса к БД
MigrationMode	Режим переноса данных

Пример:

  "AuditSrv": {
    "SourceDatabase": "Data Source=.\\SQLEXPRESS;Initial Catalog=AnalyticsServiceDB;Integrated Security=True;Persist Security Info=False;TrustServerCertificate=True",
    "TargetDatabase": "Username=username;Password=password;Host=192.168.0.5;Port=5050;Database=AnalyticsMigrUtilTestDb;Include Error Detail=true",

    "CommandTimeoutSeconds": 60,

    "MigrationMode": "CleanupData, CleanupConfig, MigrateConfig"
  },

Отображение (маппинг) URL (объект `UriMapping`)

Данный объект позволяет выполнить отображение (маппинг) всех URL в конфигурациях сервисов и пользовательских данных. Необходимо перечислить через запятую все пары ключ-значение, для которых требуется выполнить перенос, за исключением имени узла в конфигурации генератора сессий SessionIdHostConfiguration (параметр SessionIdHostMap в объекте Центр Идентификации (IdSrv) - его требуется указать отдельно.

Ключ Значение

Hosts Адрес узла. Может состоять из схемы, адреса сервера и порта (например https://host.ru:443). Схема и порт являются опциональными. Если схема и/или порт указаны, то поиск соответствия для замены будет производиться с учетом этих параметров

ServicesDisplayNames Имена приложений сервисов. Замена будет производиться во всех адресах и URN'ах

Ключ	Значение
Hosts	Адрес узла. Может состоять из схемы, адреса сервера и порта (например `https://host.ru:443`). Схема и порт являются опциональными. Если схема и/или порт указаны, то поиск соответствия для замены будет производиться с учетом этих параметров
ServicesDisplayNames	Имена приложений сервисов. Замена будет производиться во всех адресах и URN'ах

Пример:

  "UriMapping": {

    "Hosts": {

      "OldHost1": "NewHost1",
      "OldHost2": "NewHost2"
    },

    "ServicesDisplayNames": {

      "OldApplicationName1": "NewApplicationName1",
      "OldApplicationName2": "NewApplicationName2"
    }

  },

Настройки переноса ключей (только для тестового использования)

При наличии данного параметра будет произведена попытка экспорта Мастер-ключей криптопровайдеров DSS из реестра (HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Crypto Pro\Settings\Keys\). После завершения работы утилиты в случае миграции настроек криптопровайдеров в подпапке CryptoProviderKeysFolder (указанной в параметре утилиты CryptoProviderKeysFolder появятся папки с бинарными данными экспортированных из реестра ключей.

Ключ	Значение
CryptoProviderKeysFolder	Общая папка сохраненных ключей
CryptoProviderKeysPrefix_8Chars	Префикс отдельной папки с сохраненным ключом. Параметр имеет строгий формат – 8 символов, латинские буквы в верхнем регистре и разрешенные для именования папок символы

Пример:

  "CryptoProviderKeysFolder": ".\\_ExportedKeys",
  "CryptoProviderKeysPrefix_8Chars": "NEW-MIGR"

После завершения работы утилиты в папке, указанной в параметре CryptoProviderKeysFolder, появятся папки с бинарными данными экспортированных из реестра ключей. Для импорта данных ключей необходимо перенести все полученные папки с бинарными данными в папку /var/opt/cprocsp/keys/ на целевом узле. Для папок с ключами необходимо также назначить владельцем учетную запись, из-под которой работают соответствующие сервисы КриптоПро Ключ.

Пример:

sudo chown dss-srv -R /var/opt/cprocsp/keys/NEW-MIGR*

Формат даты и времени

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

В значении параметра MigratedDateTimeFormat необходимо указать текстовый формат даты и времени на целевом сервере (КриптоПро Ключ).

Пример:

"MigratedDateTimeFormat": "dd.MM.yyyy HH:mm:ss"

Если параметр отсутствует, то утилита применит по умолчанию следующий формат: "dd.MM.yyyy HH:mm:ss".

Проверка формата даты и времени

Проверить соответствие форматов даты и времени на исходном и целевом сервере возможно, выполнив на каждом из серверов следующую команду:

[System.Convert]::ToString([System.DateTime]::Now)

В случае если результаты отличаются, необходимо подобрать такое значение строки форматирования $fmt, чтобы формат даты, полученный в результате выполнения команды ниже на целевом сервере, совпал с форматом, полученным ранее на исходном сервере.

Пример подбора строки форматирования даты и времени на целевом сервере:

$fmt = "dd.MM.yyyy HH:mm:ss"
[System.DateTime]::Now.ToString($fmt, [System.Globalization.CultureInfo]::InvariantCulture)

Справочник по построению строк форматирования $fmt

Режимы переноса пользовательских данных и настроек сервисов (объект `MigrationMode`)

Данный объект является обязательным для каждого из сервисов и позволяет настроить режим переноса пользовательских данных и настроек сервисов из КриптоПро DSS в КриптоПро Ключ. Для каждого сервиса настраивается предварительная очистка таблиц в целевой БД, а также необходимость переноса данных.

Объект MigrationMode заполняется в каждом объекте сервиса один раз и содержит набор флагов, отвечающих за перенос и предварительную очистку данных в целевой БД. Существуют следующие флаги, доступные в ограниченном количестве сочетаний:

CleanupData - очистка таблиц с пользовательскими данными в целевой БД перед миграцией
CleanupConfig - очистка таблиц с настройками в целевой БД перед миграцией
MigrateConfig - миграция таблиц с настройками
MigrateData - миграция таблиц с пользовательскими данными
TopUpNewData - миграция только новых (появившихся после предыдущей миграции) данных из таблиц с пользовательскими данными

Допустимые сочетания флагов для Центра Идентификации и Сервиса Подписи (объекты `IdSrv` и `SignSrv`)

"CleanupData" - Только очистка таблиц с пользовательскими данными в целевой БД перед миграцией
"CleanupData, CleanupConfig, MigrateConfig" - Перенос настроек с предварительной очисткой имеющихся настроек в целевой БД. Дополнительно требуется очистить пользовательские данные, так как они могут быть неразрывно связаны со старыми настройками (например, группы пользователей).
"CleanupData, CleanupConfig, MigrateConfig, MigrateData" - Перенос всех данных и настроек с предварительным удалением данных и настроек из целевой БД.
"CleanupData, MigrateData" - Перенос только пользовательских данных.
"TopUpNewData" - Всегда используется отдельно от других флагов. Перенос только новых (появившихся после предыдущей миграции) данных из таблиц с пользовательскими данными.

Примечание

Может быть целесообразно выполнять перенос данных и настроек в следующей последовательности. "CleanupData, CleanupConfig, MigrateConfig" -> "CleanupData, MigrateData". При выполнении первого шага производится перенос настроек, что не занимает большого количества времени. После этого возможно протестировать работоспособность сервисов КриптоПро Ключ, выполнить при необходимости донастройку и после этого запустить перенос всех пользовательских данных.

Пример:

"MigrationMode": "CleanupData, CleanupConfig, MigrateConfig, MigrateData",

Допустимые сочетания флагов для Сервиса Обработки Документов и Сервиса Аудита (объекты `DocSrv` и `AuditSrv`)

"CleanupData, CleanupConfig, MigrateConfig" - Перенос настроек с предварительной очисткой имеющихся настроек и данных в целевой БД. Записи аудита и документы будут удалены.

Пример:

"MigrationMode": "CleanupData, CleanupConfig, MigrateConfig",

Добавление пользовательских данных к уже существующим (только для тестового использования)

Внимание!

Функциональность находится в разработке и может быть использована только для тестирования.

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

Утилита после выполнения переноса создает в собственной папке файлы, содержащие информацию о перенесенных данных Центра Идентификации (IdSrv) и Сервиса Подписи (SignSrv) следующего вида:

_migration_report_SignSrv_%DateTime%.txt
_migration_report_IdSrv_%DateTime%.txt
_migration_report_SignSrv_last.txt
_migration_report_IdSrv_last.txt

Файлы, имеющие в имени дату и время, содержат информацию о перенесенных данных на указанный момент времени, а файлы, содержащие last в имени, - соответствуют последнему выполненному переносу при помощи утилиты. При первом переносе создается два файла с идентичным содержимым, далее обновляется только содержимое файла _migration_report_*_last.txt и создаются новые файлы _migration_report_*_%DateTime%.txt.

Данные файлы могут быть использованы как "точки сохранения" при добавлении пользовательских данных к уже существующим.

Внимание!

Редактирование файлов вручную не рекомендуется.

Доступна информация о переносе следующих данных:

дата создания/регистрации пользователя;
идентификатор созданного ключа;
идентификатор токена аутентификации.

Пример содержимого:

{
  "LastUserCreatedAt": "2025-01-22T14:11:27.94",
  "LastTokenProfileId": -1,
  "LastTokenId": 113454
}

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

пользователи должны быть созданы после момента времена, указанного в файле миграции _migration_report... (в процессе дополнительно выполняется проверка уникальности);
ключи, запросы и сертификаты пользователей должны иметь идентификаторы, бОльшие, чем указано в файле миграции _migration_report...;
токены аутентификации должны иметь идентификаторы, бОльшие, чем указано в файле миграции _migration_report....

Примечание

В случае возникновения коллизии (совпадении идентификатора при переносе) утилита обрабатывает коллизии следующим образом:

для пользователей и токенов аутентификации перенос не производится;
для ключей, запросов и сертификатов перенос производится с присвоением им в КриптоПро Ключ новых незанятых идентификаторов.

Задание файла миграции, от которого утилита начнет отсчет при добавлении данных к существующим, производится при помощи параметра TopUpDataInfoFile объектов Центра Идентификации и Сервиса Подписи.

Для включения режима добавления данных к существующим необходимо использовать флаг TopUpNewData объекта Центра Идентификации и/или Сервиса Подписи.

Пример:

"MigrationMode": "TopUpNewData",