Утилита миграции DSStoKey
Внимание!
Поддерживается миграция только на КриптоПро Ключ версии R19 (v1281). После миграции можно обновить КриптоПро Ключ до более новой версии.
Утилита DSStoKey позволяет перенести (мигрировать) пользовательские данные, конфигурацию сервисов и сервисные сертификаты КриптоПро DSS в соответствующие
сервисы КриптоПро Ключ. Доступен перенос данных для компонентов, имеющих базу данных:
- Центр Идентификации,
- Сервис Подписи,
- БД Сервиса Операций,
- Сервис Аудита,
- Сервис Обработки Документов.
Конфигурации следующих сервисов не переносятся и потребуют последующей настройки согласно Руководству Администратора:
- Сервис Взаимодействия с SDK,
- Веб-интерфейс Пользователя,
- Сервис PUSH-уведомлений.
Подготовительные мероприятия
См. также:
- Учетной записи, из под которой будет произведен запуск утилиты, требуются права на запись в папку утилиты, права на доступ к реестру и к закрытым ключам сервисных сертификатов;
- Требуется создание экземпляров всех перечисленных сервисов на сервере с КриптоПро Ключ до того, как будет начат перенос данных;
- На исходном сервере (КриптоПро DSS) требуется доверие к TLS-сертификатам баз данных (и MSSQL исходного сервера, и Postgres целевого);
- Для доступа к БД целевого и исходного серверов требуется наличие учетных записей доступа к БД (логин/пароль): для MSSQL с правами на чтение всех таблиц БД КриптоПро DSS, а в Postgres на запись во все таблицы БД КриптоПро Ключ;
- Для работы утилиты необходимо установить ASP.NET Core Runtime 10.0.7 - Hosting Bundle со страницы загрузки.
Внимание!
Требуется сверить форматы даты и времени на исходном и целевом серверах.
В случае если они не совпадают, необходимо воспользоваться параметром
datetimeformat.
Описание процедуры переноса данных
- Для каждого набора данных (таблицы) переносятся данные из БД КриптоПро DSS в соответствующие БД КриптоПро Ключ в соответствии с выбранным режимом переноса.
- Валидация данных не производится.
- При переносе любых параметров, связанных с URL-адресами, выполняется подмена адресов в соответствии с параметрами запуска утилиты.
Порядок работы с утилитой
Утилита DSStoKey принимает на вход путь к файлу с параметрами миграции migration_options.json.
Для удобства использования можно создать несколько файлов, чтобы переносить данные каждого экземпляра по отдельности.
Примечание
Если в КриптоПро DSS существуют пользователи, созданные до конца 2020 года И до обновления на версию 2.0.3222,
то миграцию Центра Идентификации и Сервиса Подписи необходимо выполнять ОДНОВРЕМЕННО
(в рамках одного запуска утилиты: в файле конфигурации утилиты должны быть заполнены обе структуры
IdSrv и SignSrv). В противном случае пользователи, созданные ранее описанных выше событий, потеряют доступ
к своим сертификатам и ключам.
Порядок действий на целевом сервере (КриптоПро Ключ):
- Установить КриптоПро Ключ,
- Развернуть экземпляры переносимых компонентов,
- Скопировать адреса созданных приложений и строки подключения к созданным БД (например, в текстовый файл).
Порядок действий на исходном сервере (КриптоПро DSS):
- Обновить КриптоПро DSS (необходимо согласовать версию, обратившись по адресу dsssupport@cryptopro.ru),
- Запустить установщик утилиты миграции. Данные утилиты будут скопированы в
C:\Program Files\Crypto Pro\TOOLS\DSStoKEY\. Требуются права администратора, - Заполнить полученными с целевой машины данными файл конфигурации утилиты
migration_options.json(см. параметры утилиты), - Остановить переносимые сервисы КриптоПро DSS (или обеспечить отсутствие операций создания/удаления пользователей и/или сертификатов),
- Запустить утилиту с правами администратора:
"C:\Program Files\Crypto Pro\TOOLS\DSStoKEY\bin\dm.exe" --options "C:\Program Files\Crypto Pro\TOOLS\DSStoKEY\bin\migration_options.json"и дождаться окончания выполнения переноса данных.
Порядок действий на целевом сервере (КриптоПро Ключ):
- Проверить перенесенные настройки (адреса приложений, сервисные сертификаты и т.д.),
- Проверить перенесенные Мастер-ключи криптопровайдеров в подпапке
_ExportedKeysпапки с утилитой. В случае их успешного переноса переместить содержимое подпапки в/var/opt/cprocsp/keys/и назначить права на владение учетной записи, из-под которой работают сервисы КриптоПро Ключ, использующие данные ключи, - Перезагрузить экземпляры сервисов (Restart-*Instance).
Дополнительно на целевом сервере (КриптоПро Ключ):
1. Выполнить настройку следующих сервисов согласно Руководству Администратора:
- Сервис Взаимодействия с SDK,
- Веб-интерфейс Пользователя,
- Сервис PUSH-уведомлений.
2. Проверить (и при необходимости ввести) лицензии:
Get-IdsLicense
Get-IdsLicenseGroup
Get-SignLicense
3. Перенастроить сервисы ADFS, если они использовались.
Конфигурационный файл утилиты
Примечание
Для незаполненных параметров будет установлено значение по умолчанию: 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 -RedirectUri https://$hostname/$fe_name/signin-oidc
Пример:
"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 | Количество строк таблиц, переписываемое за одну пакетную вставку в целевую БД |
Примечание
В настройках переноса для Центра Идентификации и Сервиса Подписи должна быть указана одна и та же целевая БД Сервиса Операций (TargetOperationsDatabase).
Пример:
"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'ах и только тех URL-адресах, которые были заменены во время замены адресов узлов из поля Hosts. Чтобы изменить имя приложения в URL-адресе без замены адреса узла, в набор Hosts необходимо добавить строку "OldHost": "OldHost", т.е. заменить адрес узла точно таким же |
Пример:
"UriMapping": {
"Hosts": {
"OldHost1": "NewHost1",
"OldHost2": "NewHost2",
"OldHost3": "OldHost3" /*Замена адреса узла на старое значение с целью выполнения замены 3 для имени приложения*/
},
"ServicesDisplayNames": {
"OldApplicationName1": "NewApplicationName1",
"OldApplicationName2": "NewApplicationName2",
"OldApplicationName3": "NewApplicationName3"
}
},
Настройки переноса ключей (только для тестового использования)
При наличии данного параметра будет произведена попытка экспорта Мастер-ключей криптопровайдеров 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",
Донастройка ADFS на целевом сервере
В случае если в качестве стороннего центра идентификации (СЦИ) использовался ADFS,
после выполнения переноса требуется убедиться, что в конфигурации СЦИ, зарегистрированного
в КриптоПро Ключ для ADFS, в параметре
IssuerAlternativeNames присутствуют следующие значения:
https://<Адрес сервера СЦИ>/adfs- если взаимодействие с СЦИ осуществляется через OpenId Connect 1.0 или через обмен маркеров JWT,http://<Адрес сервера СЦИ>/adfs/services/trust- если взаимодействие с СЦИ осуществляется через обмен маркеров SAML.
Для этого возможно использовать следующий командлет:
Get-IdsIdentityProvider -IssuerName <Имя СЦИ>
В случае если в выводе командлета отсутствуют перечисленные значения, их требуется зарегистрировать при помощи следующей команды:
Set-IdsIdentityProvider -IssuerName <Имя СЦИ> -IssuerAltNames @("http://<Адрес сервера СЦИ>/adfs/services/trust", "https://<Адрес сервера СЦИ>/adfs")
См. также: