Настройка экземпляра сервиса Ключ Lite

Сервис Ключ Lite позволяет настроить его в двух режимах:

  • веб-интерфейс Lite. В данном режиме необходимы сервисы КриптоПро Ключ (Сервис Подписи, настроенный специальным образом, Сервис Аудита, Центр Идентификации и Веб-интерфейс Пользователя). Для работы с Веб-интерфейсом Lite требуется аутентификация пользователя. Возможна настройка отображения документов перед подписью и аудит событий. Поддерживаются все форматы подписи, поддерживаемые КриптоПро Ключ. Доступно расшифрование документов только формата CMS типа «конверт данных» (см. Р 1323565.1.025–2019). На стороне пользователя требуется наличие КриптоПро CSP. Для работы в браузере требуется наличие на стороне пользователя КриптоПро ЭЦП Browser plug-in.
  • REST-сервис Lite. В данном режиме сервис Ключ Lite предоставляет программный интерфейс, позволяющий выполнять вычисление хэш-значения для подписанного документа и формировать структуру подписи необходимого формата (в т.ч. усовершенствовать подпись в рамках поддерживаемых форматов). Вычисление значения подписи происходит непосредственно на устройстве пользователя. На стороне Пользователя требуется наличие КриптоПро CSP. Описание API Сервиса представлено в Руководстве Разработчика из комплекта документации.

Настройка Сервиса Lite должна производиться следующим образом.

Настройка Сервиса Lite производится при помощи утилиты конфигурирования CPShell (sudo cpsh) либо при помощи PowerShell (sudo pwsh). Список командлетов, входящих в состав модуля Lite, можно получить, выполнив команду:

Get-Command -Module CryptoPro.SignatureServiceLite.PowerShell -CommandType Cmdlet

Для получения справки по каждому из командлетов выполните следующую команду: 

Get-help <имя_командлета>
# Например:
Get-Help Set-LiteProperties -Full

Основные объекты администрирования Ключ Lite:

Настройки экземпляра сервиса

Основные настройки экземпляра Сервиса Lite могут быть изменены при помощи командлета Set-LiteProperties:

  • -CertValidationMode – режим проверки сертификата при формировании подписи. Может иметь следующие значения: NoCheck, ChainOnline, ChainOffline.
  • -CertRevocationValidationFlag – режим проверки на отзыв сертификатов в цепочке. Может иметь следующие значения: EndCertificateOnly, EntireChain, ExcludeRoot.
  • -PdfSignatureSize – размер блока, выделяемого для подписи в PDF-файле (в кБайт).
  • -AllowedCorsOrigins - допустимые источники запросов для контроля CORS.
  • -AdditionalCertStoreName – имя дополнительного хранилища сертификатов для сбора доказательств действительности сертификата подписи.
  • -IsAdditionalCertStoreEnabled – ($true/$false) значение, показывающее, следует ли использовать дополнительное хранилище сертификатов.
  • -SignatureTypeList - поддерживаемые форматы подписи через запятую. Допустимые значения: XMLDSig, GOST3410, PDF, CADES, CMS
  • -OcspServiceList - список служб OCSP через запятую.
  • -CadesUseOcspAuthorizedPolicy - разрешает использование групповой политики КриптоПро OCSP Client "Службы OCSP: сертификаты уполномоченных служб OCSP" при проверке полномочий службы актуальных статусов. Подробнее см. документацию на КриптоПро OCSP Client.
  • -CadesUseProxy - параметр зарезервирован для использования в ОС Windows. Использовать прокси при создании CAdES-подписи. Если TRUE — пропустить запрос настроек прокси-сервера у IE.

После выполнения настроек необходимо перезапустить сервис:

Restart-LiteInstance

Специальные настройки для работы Lite в режиме веб-интерфейса

Для настройки работы Lite в режиме веб-интерфейса необходимы сервисы КриптоПро Ключ (Сервис Подписи, настроенный специальным образом, Сервис Аудита, Центр Идентификации и Веб-интерфейс Пользователя). Настройки сервисов КриптоПро Ключ описаны в соответствующем Руководстве Администратора из комплекта документации.

В данном разделе описаны специальные настройки, требуемые для добавления возможности использования функций Lite в веб-интерфейсе.

1. Интеграция Сервиса Lite с Веб-интерфейсом КриптоПро Ключ:

Set-FeProperties -LiteSignServerAddress " http://$hostname/$lite_name/" – по умолчанию http, т.к. это межсервисное взаимодействие

2. Переключение Сервиса Подписи в режим поддержки Lite (Client или ServerAndClient):

Set-SignProperties -DisplayName <Имя экземпляра Сервиса Подписи> -ServiceType Client

3. Добавление криптопровайдера типа "Lite" с именем, соответствующим используемому алгоритму подписи.

Add-SignCryptoProvider -TypeId Lite -ProviderName " Crypto-Pro GOST R 34.10-2012 Cryptographic Service Provider" -ProviderType 80

4. Перезапуск настраиваемых сервисов: 

Restart-SignInstance
Restart-FeInstance
Restart-LiteInstance

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

Настройки конечных точек

В настройках конечных точек Lite можно указать следующий параметр:

  • -MaxRequestBodySizeInBytes - максимальный размер сообщения в байтах. По умолчанию равен 30000000 (~30 Мбайт). Рекомендуется выполнять данную настройку согласованно с настройкой ограничения размера передаваемых данных в cpnginx.

Пример настройки:

Set-LiteEndpointGlobalSettings -DisplayName lite -MaxRequestBodySizeInBytes 30000000

После выполнения настроек необходимо перезапустить сервис:

Restart-LiteInstance

Журналирование

Сообщения о работе службы Сервиса Lite записываются в автоматически создаваемые при установке журналы событий:

/var/log/cprokey/litesrv/lite/cprokey-litesrv-lite*.log (/var/log/cprokey/litesrv/lite/cprokey-litesrv-lite*.clef в случае использования структурированного журналирования).

Поддерживаемые типы и форматы журналов событий

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

Настройка журналирования и ротации журналов

Настройка журналов производится при помощи командлета Set-LiteLoggingProperties.

Название свойства Описание
LogLevel Уровень логирования по умолчанию.
OutputTemplate Шаблон сообщения. Параметры и вид шаблона по умолчанию описаны ниже.
RollingInterval Задает частоты создания нового файла журнала. Доступны значения:
Minute,Hour,Day,Month,Year, Infinite. По умолчанию имеет значение Day.
FileSizeLimitBytes Максимальный размер файла журнала в байтах, при достижении заданного размера будет создан новый файл. Для неограниченного роста необходимо указать 0. По умолчанию имеет значение 1MB.
RetainedFileCountLimit Максимальное количество файлов журналов, при достижении этого значения старые файлы будут удаляться. Для отключения удаления необходимо указать 0.
IsAsync Используется ли асинхронная запись в файл. Данный режим ускоряет производительность, но снижает надежность. По умолчанию false.
AsyncBufferSize Размер очереди для асинхронной записи. Определяется опытным путем, по умолчанию имеет значение 10000. Слишком большие значения увеличат объем занятой памяти и снизят надежность из-за риска потерять все содержимое очереди в результате сбоя, слишком маленькие значения нивелируют преимущество асинхронной записи.
AsyncBlockWhenFull Определяет режим работы асинхронной записи при превышении размера очереди, блокирование записи новых событий или игнорирование (отбрасывание не помещающихся сообщений с их потерей. По умолчанию false.
FlushToDiskIntervalSeconds Интервал записи в файл на диск. По умолчанию 2 секунды.
UseRenderedClef Построение текстовок записей журнала в удобно читаемом формате с учетом подстановочных параметров. По умолчанию false. Рекомендуется использовать при включении структурированного журналирования (параметр UseStructuredLogging).
UseStructuredLogging Включение структурированного журналирования. По умолчанию false.
EnableDebugLogging Параметр зарезервирован для дальнейшего использования.

После выполнения настроек необходимо перезапустить сервис:

Restart-LiteInstance

Поддерживаются следующие виды журналирования:

Текстовое журналирование

Режим журналирования используется по умолчанию. Журналы событий имеют расширение *.log. Шаблон форматирования по умолчанию имеет следующий вид.

[{Level:u3}] {EventId}: {Timestamp:o } | {RequestId,22} | {Message:lj} | {Properties:j} |{NewLine}{Exception}<|

Компоненты шаблона (в случае если компонент отсутствует, он будет представлять собой пустое значение | |:

  • {Level:u3} - уровень логирования в виде трехбуквенного сокращения в верхнем регистре: DBG, INF, WRN, ERR, CRT.
  • {EventId} - идентификатор события .
  • {Timestamp:o} - метка времени в формате YYYY-MM-DDThh:mm:ss.fffffffzzz (ISO 8601).
  • {RequestId,22} - уникальный идентификатор запроса. Представляет из себя 22 символа в формате ConnectionId:RequestNumber, где ConnectionId - это идентификатор HTTP соединения, а RequestNumber - номер HTTP запроса, полученного по данному соединению.
  • {Message:lj} - текст сообщения.
  • {Propertie:j} - дополнительные свойства сообщения, не вошедшие в текстовку {Message}, в виде сериализованного в строку объекта JSON.
  • {NewLine} - специальное свойство, отображающее новую строку.
  • {Exception} - сообщение об ошибке вместе со стектрейсом (при наличии).

Символы {, }, :u3, :o, :lj, :j являются специальными элементами самого шаблона, они не попадают в результирующий вывод. Специальные символы | и <| облегчают его автоматизированный разбор.

Пример записи:

[INF] { Id: 1 }: 2024-11-15T13:54:45.4041441+03:00 | 0HN82BCC94RU0:00000001 | Request starting HTTP/1.0 POST http://localhost:60000/api/signatures/presign - application/json 1167 | {"SourceContext":"Microsoft.AspNetCore.Hosting.Diagnostics","RequestPath":"/api/signatures/presign","ConnectionId":"0HN82BCC94RU0","ProcessId":81153,"ThreadId":11} |
Структурированное журналирование

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

Set-LiteLoggingProperties -UseStructuredLogging $true -UseRenderedClef $true

После выполнения настроек необходимо перезапустить сервис:

Restart-LiteInstance

Журналы событий имеют расширение *.clef. Шаблон форматирования по умолчанию имеет следующий вид.

Компонент Имя Описание Обязательность
@t Timestamp Метка времени в формате YYYY-MM-DDThh:mm:ss.fffffffzzz (ISO 8601). Обязательный
@m Message Текст сообщения
@mt Message Template Шаблон сообщения. Будет отображен вместо поля Message, если при настройке структурированного журналирования не был взведен флаг -UseRenderedClef $true
@l Level Уровень логирования Отсутствие означает, чтобы событие является информационным
@x Exception Сообщение об ошибке вместе со стектрейсом (при наличии).
@i Event id Идентификатор события

Пример записи:

{"@t":"2024-11-15T10:55:43.7311260Z","@m":"Content root path: \"/var/opt/cprokey/litesrv/lite\"","@i":"cc26f24e","ContentRoot":"/var/opt/cprokey/litesrv/lite","SourceContext":"Microsoft.Hosting.Lifetime","ProcessId":84635,"ThreadId":1}

XML-преобразования

Ключ Lite обеспечивает поддержку пользовательских XML-преобразований при формировании подписи формата XMLDSig (XAdES). Данная возможность обеспечивается путем регистрации плагина XML-преобразования.

Регистрация плагина осуществляется при помощи командлета Add-LiteTransformPlugin, позволяющего настроить следующие параметры:

  • –Assembly - Путь к сборке, содержащей реализацию преобразования. По умолчанию поиск будет осуществляться в папке /opt/cprokey/plugins/transforms/.
  • –ClassName - Имя класса в указанной сборке, непосредственно реализующего XML-преобразование.
  • –Identifiers - Список идентификаторов, соответствующих регистрируемому преобразованию.

В Ключ Lite доступны следующие XML-преобразования:

  • XML-Signature XPath Filter 2.0. Идентификатор: http://www.w3.org/2002/06/xmldsig-filter2
  • Преобразование, разработанное для Федеральной таможенной службы (ФТС). Идентификатор: urn:xml-dsig:transformation:v1.1.
Add-LiteTransformPlugin -DisplayName lite –Assembly "/opt/cprokey/plugins/transforms/CryptoPro.Plugins.Xml.Transforms.dll" –ClassName CryptoPro.Plugins.Xml.Transforms.Filter2SubstractTransform –Identifiers "http://www.w3.org/2002/06/xmldsig-filter2"
Add-LiteTransformPlugin -DisplayName lite –Assembly "/opt/cprokey/plugins/transforms/CryptoPro.Plugins.Xml.Transforms.dll" –ClassName CryptoPro.Plugins.Xml.Transforms.XmlFssTransform –Identifiers "urn:xml-dsig:transformation:v1.1"

После выполнения настроек необходимо перезапустить сервис:

Restart-LiteInstance