Перейти к содержанию

dss

Сервис работы с электронными подписями#

Сервис dss-service реализует работу с электронными подписями в облаке. Имеется собственная реализация (ОЭП от Лексемы) с использованием КриптоПро CSP для НЭП и интеграция с СКБ Контур.

Note

Опциональный элемент системы. API доступно только внутри инфраструктуры серверной части lexema8.

Подключение сервиса#

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

Настройки для интеграции с СКБ Контур#

При работе с боевыми площадками необходимо получить у СКБ Контур tls-сертификат (для доступа к API), купить лицензию КриптоПро, настроить приложение stunnel-msspi. Пример настройки:

{
  applications: {
    dss: {
      protocol: 'http',
      host: 'dss-service',
      port: 3076,
      script: 'ecosoft-lexema8-dss-service',
      kontur: {
        cryptoApiUrl: 'http://localhost:8200/v3',
        cryptoApiHost: 'cloud.kontur-ca.ru:443'
        certificateReleasingUrl: 'http://localhost:8201/CC',
        certificateReleasingHost: 'reg.kontur-ca.ru:443',
        callbackUrl: 'http://dss.lexema.ru/api/v2.0/dss/kontur/response'
      }
    }
  }
}

Примечания - host зависит от названия контейнера в файле docker-compose.yml. - в свойстве cryptoApiUrl хост и порт берется из настроек stunnel-msspi (свойство accept из раздела [Crypto API]). - в свойстве certificateReleasingUrl хост и порт берется из настроек stunnel-msspi (свойство accept из раздела [Certificate Releasing]). - к свойству callbackUrl такие же требования, как при подключении сервиса в режиме разработки. Дополнительно нужно настроить список разрешенных адресов, которые могут обращаться по адресу callbackUrl. Для этого можно использовать Web Application Firewall. В качестве разрешенного адреса указывается cloud.kontur-ca.ru. - свойство key указывать не нужно.

stunnel-msspi Настройки stunnel-msspi должны находится в проекте с конфигурационными файлами в папке ./dss. Пример stunnel-msspi: 

output = /var/log/stunnel.log
socket = l:TCP_NODELAY=1
socket = r:TCP_NODELAY=1
debug = 7

[Crypto API]
connect = cloudtest.kontur-ca.ru:443
client = yes
accept = localhost:8200
cert = 384d821774cb0e826d390ba34ddb7ae790415fe8
verify = 2

[Certificate Releasing]
connect = reg.kontur-ca.ru:443
client = yes
accept = localhost:8201
cert = 384d821774cb0e826d390ba34ddb7ae790415fe8
verify = 2

Примечания: - cert - отпечаток tls-сертификата. - для работы stunnel-msspi нужна лицензия КриптоПро. Для правильной установки лицензии обратитесь к системному администратору.

Настройки для подключения ОЭП от Лексемы#

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

{
  applications: {
    dss: {
      protocol: 'http',
      host: 'dss-service',
      port: 3076,
      script: 'ecosoft-lexema8-dss-service',
      lexema: {}
    }
  }
}
Дополнительно для работы в производственном окружении необходимо: - Cгенерировать внешнюю гамму. Можно использовать биологический генератор, как в примере подключения сервиса в режиме разработки, либо использовать другие программные средства. Для подключения гаммы обратитесь к системному администратору. - Установить лицензию КриптоПро. Для правильной установки лицензии обратитесь к системному администратору.

Примечания: - Сгенерированной гаммы хватает на ограниченное количество ключей. Необходимо генерировать заново, если вся гамма была использована. - Генерацией гаммы должен заниматься ответственный за безопасность хранения приватных ключей ЭП. - Сертификаты и приватные ключи ЭП хранятся на сервере, где разворачивается dss-service. - Если используется корневой сертификат, то файл (сертификата) должен иметь формат pfx.

Установка сертификатов и лицензии Криптопро#

Все сертификаты необходимо паместить в tar архив с именем certificates.tar и положить в папку dss в вашем deploy-проекте. в эту же папку добавьте файл import-cert.sh. Внутри файла пропишите команду для установки лицензии для криптпро, а также установку необходимых сертификатов. Сертификаты из архива будут автоматически распакованы в папку /root/certificates/. пример файла import-cert.sh

# Установка лицензии криптопро
/opt/cprocsp/sbin/amd64/cpconfig -license -set <ENTRY_LICENSE>
/opt/cprocsp/sbin/amd64/cpconfig -license -view

# Пример установки сертификата для интеграции с Контур
/opt/cprocsp/bin/amd64/certmgr -install -pfx -file /root/certificates/tls.pfx  -pin <ENTRY_YOU_PIN> -silent

# Пример установки установки корневого сертификата, который используется при использовании ОЭЦП от лексемы
/opt/cprocsp/bin/amd64/certmgr -install -pfx -store mRoot -file /root/certificates/root.pfx  -pin <ENTRY_YOU_PIN> -silent

Особенности работы сервиса при интеграции с СКБ Контур#

Выпуск тестового пользовательского сертификата#

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

Обновление статуса при запуске сервиса#

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

Обработка подписей на сервере#

Если необходимо обрабатывать результат операции на сервере после того, как придет ответ от СКБ Контур на маршрут, указанный конфигурационном файле в свойстве callbackUrl, то необходимо в проект подключить сервис scheduler и создать для него задачу Для задачи необходимо написать прикладную функцию, в которой будет обрабатываться результат операции. В составе типового решения КЭДО Lexema-ECM интеграция с СКБ Контур по умолчанию выключена.

Настройка конфигурационного файла#

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

{
  applications: {
    "dss": {
      "kontur"{
        taskId: 1
      }     
    }
  }
}

Особенности работы ОЭП от Лексемы#

Поддерживается: - Создание сертификатов НЭП с сроком действия 18 месяцев. Можно подключать корневой сертификат для выпуска пользовательских. - Удаление сертификата. - Подписание файла. - Проверка подписи.

Создание сертификатов#

По умолчанию пользователь может создать сертификат только самому себе. Если нужна возможность, чтобы пользователь мог создавать сертификаты другим пользователям, то необходимо создать в системе роль DssAdmin (если ее нет) и назначить ему эту роль. После этого в методе создания сертификата можно передавать идентификатор пользователя, для которого необходимо создать сертификат.

Использование корневого сертификата#

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

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

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

Заполнение поля Subject (информация о владельце) сертификата#

При создании сертификата в Subject сертификата автоматически добавляются следующие поля: - SN - Фамилия пользователя - G - Имя и отчество - CN - Фамилия, имя и отчество - E - email пользователя Эти данные о пользователе загружаются из системной таблицы.

Добавление дополнительных полей в сертификат#

Если необходимо в поле Subject сертификата добавить дополнительные поля, то следует написать прикладной запрос, который должен вернуть требуемые атрибуты. Список поддерживаемых атрибутов, который должен вернуть запрос: - FirstName - Имя пользователя. Добавляется в поле G сертификата. - LastName - Фамилия пользователя. Добавляется в поле SN сертификата. - MiddleName - Отчество пользователя. Добавляется в поле G сертификата. - Email - Почта пользователя. Добавляется в поле E сертификата. - Organization - Организация. Добавляется в поле O сертификата. - Position - Должность пользователя. Добавляется в поле T сертификата. - OrganizationINN - ИНН организации. Добавляется в поле "Неструктурированное имя" сертификата. - OrganizationKPP - КПП организации. Добавляется в поле "Неструктурированное имя" сертификата. - OrganizationOGRN - ОГРН организации. Добавляется в поле "Неструктурированное имя" сертификата. Пример заполнения поля "Неструктурированное имя" в сертификате: INN=12345678/KPP=948931/OGRN=524535.

Для созданного запроса необходимо добавить роль DssService (эту роль необходимо создать, если ее нет). Пример описания запроса:

{
  "rights": {
    "read": ["DssAdmin"]
  },
  "select": {
    "text": "./loadAttributes.sql",
    "parameters": ["userId", "bigint"]
  },
  "parameters": {
    "userId": "bigint",
    "orgId": "bigint"
  }
}

Запрос принимает идентификатор пользователя из системной таблицы lex.User, а также идентификатор организации из таблицы lex.Organization Созданный запрос необходимо добавить в файл внешних зависимостей exteranl-manual.json (если это необходимо) и в конфигурационный файл (раздел applications.dss.lexema.loadUserAttributesQuery). Пример конфигурационного файла:

dss: {
  ...
  lexema: {
    loadUserAttributesQuery: './digitalSignature/loadAttributes.query.json'
  }
  ...

Описание системных моделей#

Модель для хранения подписей от СКБ Контур#

Описание свойств модели: - Id - идентификатор подписи. - FileId - идентификатор файла из системной таблицы lex.File, который подписывается. - OperationId - идентификатор операции, который создается на стороне СКБ Контур. - Status - статус операции. Значение статуса соответствует значениям из документации от СКБ Контур (берется текстовое значение, а не числовое). - Signature - подпись файла в формате base64. - KonturFileId - идентификатор файла, который создается на стороне СКБ Контур. - CUser - логин пользователя, который создал операцию подписи. - WUser - логин пользователя, который обновил подпись. - CHost - хост пользователя, который создал операцию подписи. - WHost - хост пользователя, который обновил подпись.

Модель для хранения сертификатов пользователей#

Описание свойств модели: - Id - идентификатор сертификата пользователя. - User - идентификатор пользователя. - Value - сертификат в формате base64. - DisableConfirmOperation - флаг, отвечающий за отключение подтверждения операции подписания сертификатом. - ValidFrom - дата начала действия сертификата. - ValidTo - дата окончания действия сертификата. - Provider - провайдер (lexema или kontur). - Qualified - определяет является ли сертификат квалифицированным. - CertificateThumbprint - отпечаток сертификата. - CUser - логин пользователя, который создал запись в таблице. - WUser - логин пользователя, который обновил запись в таблице. - CHost - хост пользователя, который создал запись в таблице. - WHost - хост пользователя, который обновил запись в таблице.

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

Подключение сервиса#

В проекте с конфигурационными файлами создайте папку dss и в ней создайте следующие файлы:

  • import-cert.sh — скрипт для загрузки сертификата;
  • stunnel.conf — файл конфигурации stunnel-msspi;

Если имеется файл сертификата для создания TLS-канала в формате PFX, поместите его в папку dss и переименуйте в tls.pfx.

Если необходимо использовать корневой сертификат: добавьте файл сертификата в формате PFX, поместите его в папку dss и переименуйте в root.pfx.

import-cert.sh#

Добавьте следующую строку:

/opt/cprocsp/sbin/amd64/cpconfig -license -set <лицензия>

В ней замените следующие строки значениями:

  • <лицензия> — серийный номер лицензии.

Если в папке dss содержится файл сертификата tls.pfx, добавьте следующую строку:

/opt/cprocsp/bin/amd64/certmgr -install -pfx -file /root/tls.pfx -pin '<pin>' -silent

В ней замените следующие строки значениями:

  • <pin> — PIN от файла сертификата tls.pfx.

Если в папке dss содержится файл сертификата root.pfx, добавьте следующую строку:

/opt/cprocsp/bin/amd64/certmgr -install -pfx -store mRoot -file /root/root.pfx  -pin '<pin>' -silent

В ней замените следующие строки значениями:

  • <pin> — PIN от файла сертификата root.pfx.

stunnel.conf#

Вставьте следующий код:

output = /var/log/stunnel.log
socket = l:TCP_NODELAY=1
socket = r:TCP_NODELAY=1
debug = 7

[https]
connect =
client = yes
accept = localhost:8200
cert =
verify = 2

В нём заполните следующие поля:

  • connect — имя сервера для подключения;
  • cert — отпечаток сертификата для подключения.