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

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

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

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

См. также:

  • Планирование перехода с КриптоПро DSS на КриптоПро Ключ

  • Учетной записи, из под которой будет произведен запуск утилиты, требуются права на запись в папку утилиты, права на доступ к реестру и к закрытым ключам сервисных сертификатов;

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

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

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

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

    "CleanupConfiguration": true, /* Требуется ли очистка таблиц с настройками в целевой БД перед миграцией */
    "MigrateConfiguration": true, /* Требуется ли миграция таблиц с настройками *
Примечание

Рекомендуется указывать эквивалентные значения обоих перечисленных параметров.

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

Утилита 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

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

Ключ Значение
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-запроса к БД
CleanupConfiguration Значение true/false, указывающее, требуется ли очистка таблиц с настройками в целевой БД перед миграцией
MigrateConfiguration Значение true/false, указывающее, требуется ли миграция таблиц с настройками
CleanupData Значение true/false, указывающее, требуется ли очистка таблиц с пользовательскими данными в целевой БД перед миграцией
MigrateData Значение true/false, указывающее, требуется ли миграция таблиц с пользовательскими данными
TopUpData Значение true/false, указывающее, требуется ли добавление пользовательских данных к уже имеющимся. В случае значения true значения других параметров CleanupConfiguration и MigrateConfiguration должны быть false
TopUpDataInfoFile Путь к файлу с информацией о переносе пользовательских данных, который будет служить точкой отсчета при добавлении новых пользовательских данных к существующим
DataBatchSize Количество строк таблиц, переписываемое за одну пакетную вставку в целевую БД
SessionIdHostMap Отображение ("маппинг") имени узла в конфигурации генератора сессий SessionIdHostConfiguration (текущее значение можно посмотреть в выводе командлета Get-IdsSessionIdhostConfiguration/Get-DssSessionIdHostConfiguration)
Примечание

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

Внимание!

Параметр CleanupData является противоположным с параметром TopUpData, отвечающим за добавление пользовательских данных к имеющимся без удаления. Недопустимо указывать их эквивалентными.

Пример:

  "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,

    "CleanupConfiguration": true, /* Требуется ли очистка таблиц с настройками в целевой БД перед миграцией */
    "MigrateConfiguration": true, /* Требуется ли миграция таблиц с настройками */

    "CleanupData": true, /* Требуется ли очистка таблиц с пользовательскими данными в целевой БД перед миграцией */
    "MigrateData": true, /* Требуется ли миграция таблиц с пользовательскими данными */

    "TopUpData": false,
    "TopUpDataInfoFile": "_migration_report_IdSrv_last.txt",

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

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

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

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

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

Внимание!

Параметр CleanupData является противоположным с параметром TopUpData, отвечающим за добавление пользовательских данных к имеющимся без удаления. Недопустимо указывать их эквивалентными.

Пример:

  "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,

    "CleanupConfiguration": true, /* Требуется ли очистка таблиц с настройками в целевой БД перед миграцией */
    "MigrateConfiguration": true, /* Требуется ли миграция таблиц с настройками */

    "CleanupData": true, /* Требуется ли очистка таблиц с пользовательскими данными в целевой БД перед миграцией */
    "MigrateData": true, /* Требуется ли миграция таблиц с пользовательскими данными */

    "TopUpData": false,
    "TopUpDataInfoFile": "_migration_report_SignSrv_last.txt",

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

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

Ключ Значение
SourceDatabase Строка подключения к исходной БД
TargetDatabase Строка подключения к целевой БД
CommandTimeoutSeconds Максимальное время выполнения одного SQL-запроса к БД
CleanupConfiguration Значение true/false, указывающее, требуется ли очистка таблиц с настройками в целевой БД перед миграцией
MigrateConfiguration Значение true/false, указывающее, требуется ли миграция таблиц с настройками

Пример:

  "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,

    "CleanupConfiguration": true, /* Требуется ли очистка таблиц с настройками в целевой БД перед миграцией */
    "MigrateConfiguration": true /* Требуется ли миграция таблиц с настройками */
  },

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

Ключ Значение
SourceDatabase Строка подключения к исходной БД
TargetDatabase Строка подключения к целевой БД
CommandTimeoutSeconds Максимальное время выполнения одного SQL-запроса к БД
CleanupConfiguration Значение true/false, указывающее, требуется ли очистка таблиц с настройками в целевой БД перед миграцией
MigrateConfiguration Значение true/false, указывающее, требуется ли миграция таблиц с настройками

Пример:

  "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,

    "CleanupConfiguration": true, /* Требуется ли очистка таблиц с настройками в целевой БД перед миграцией */
    "MigrateConfiguration": true /* Требуется ли миграция таблиц с настройками */
  },

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

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

**Пример: **

  "UriMap": {
    "https://hostname1": "https://hostname2", 
    "http://hostname1": "http://hostname2" 
  },

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

При наличии данного параметра будет произведена попытка экспорта Мастер-ключей криптопровайдеров 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*

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

Внимание!

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

Утилита позволяет добавить пользователей без очистки уже ранее перенесенных. Это может быть полезно в случаях, когда миграция выполняется в несколько этапов или продолжалось параллельное использование КриптоПро 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 объектов Центра Идентификации и Сервиса Подписи.

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