Отображаемая подпись PDF-документов | КриптоПро DSS

Включение режима асинхронной подписи

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

Enable-DssAsyncOperationSettings

Внимание!

Имена параметров, которые передаются в поле Parameters регистрозависимы.

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

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

• Инициированный на сервере КриптоПро DSS
• Инициированный в мобильном приложении

Выпуск сертификата, инициированный на сервере КриптоПро DSS

1. Оператор или пользователь через API DSS (или Веб-интерфейс DSS) создаёт неподписанный запрос на сертификат.
2. Пользователь в мобильном приложении создаёт ключ подписи и подписывает запрос на сертификат. Подписанный запрос на сертификат передаётся на сервер DSS.
3. В зависимости от настроек КриптоПро DSS подписанный запрос на сертификат передаётся в Удостоверяющий Центр для обработки.
4. Выпущенный сертификат устанавливается в DSS и мобильное приложение.

Создание неподписанного запроса на сертификат осуществляется через конечную точку /request.
Как и в случае ключей, хранимых в DSS, оператор выбирает зарегистрированный в DSS Удостоверяющий Центр (УЦ),
шаблон сертификата и заполняет имя субъекта.

Для задания способа хранения ключа на мобильном устройстве в объекте CertificateRequest
в поле Parameters необходимо будет указать флаг (IsClient: true).

У объекта DssCertRequest, представляющего собой созданный запрос на сертификат, появится
дополнительный статус Status – SIGN_WAIT.
Данный статус говорит Прикладной системе о том, что запрос на сертификат ожидает подписания в мобильном
приложении.

Если КриптоПро DSS подключен к КриптоПро УЦ 2.0, то DSS автоматически отправит запрос в УЦ и загрузит
выпущенный сертификат. Если запрос создавался для «Стороннего УЦ» (тип Out-of-Band), то подписанный запрос на
сертификат должен быть выгружен Прикладной системой из DSS (конечная точка /request
или пользователем в мобильном приложении и передан в УЦ для обработки.

Выпущенный сертификат может быть установлен в DSS Прикладной системой через API DSS и далее, используя API DSS SDK,
установлен в мобильном приложении пользователя.
Также выпущенный сертификат может быть передан непосредственно пользователю для установки его в мобильное
приложение и регистрации на сервере DSS.

Таким образом, сценарий похож на сценарий выпуска сертификата с ключом, хранимым на сервере DSS. Но
возникает дополнительный шаг, когда прикладная система ожидает подпись запроса на сертификат в мобильном
приложении.
Уведомление пользователя о необходимости подписать запрос на сертификат может быть выполнено через
PUSH-уведомление (средствами DSS), или любым другим образом доступным прикладной системе. Пользователь
может самостоятельно в мобильном приложении проверить наличие запросов, требующих подписи.

Выпуск сертификата, инициированный в мобильном приложении

1. Пользователь в мобильном приложении создаёт ключ подписи и запрос на сертификат.
2. Запрос на сертификат тем или иным образом передаётся в УЦ для обработки.
3. Выпущенный сертификат устанавливается в DSS и мобильное приложение.
   На шаге 2 подписанный запрос на сертификат, используя API SDK, может быть загружен в DSS. Таким образом сценарий сводится к предыдущему.

Дополнительные сценарии выпуска сертификата

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

Настройка модуля для отправки callback

Для регистрации модуля необходимо выполнить следующий скрипт:

Настройка сервиса подписи

Для поддержки сертификатов и ключей, хранимых в мобильном приложении, в Веб-интерфейсе DSS необходимо:

• Добавить криптопровайдер типа Lite

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

• Задать режим подписи Сервиса Подписи: подпись хэш-значения, подпись документа.

Set-DssProperties -ClientSignFullDocRequired $true

• Дополнительно можно настроить отправку Callback о событии подписи запроса на сертификат в МП.

Данная возможность может быть полезна для автоматизации процесса выпуска сертификата.
Прикладная система через callback может быть оповещена о том, что пользователь подписал запрос на сертификат,
и запрос на сертификат может быть передан в УЦ для обработки.

Регистрация callback приведена в статье Оповещения о событиях инициализации мобильного приложения.

Общие параметры шаблонов

Размеры всех элементов в представлении подписи и в шаблоне указываются в единицах измерения –
типографских пунктах Adobe (points). 1 пункт = 1/72 дюйма = 0,3528 мм.

Цвет элементов указывается в системе RGB (red, green, blue; красный, зелёный, синий).

Положение представления подписи на странице задается в системе координат PDF документа. Точка с
координатами (0, 0) соответствует левому нижнему углу страницы.

ColorDescription

Описание цвета элемента. Описание полей приведено в таблице ниже.

SignatureRect

Описание прямоугольника подписи. Описание полей приведено в таблице ниже.

FontDescription

Описание шрифта. Описание полей класса приведено ниже.

Параметры подписи документа

Типы подписи

Обычно в параметре DocumentType указывают расширение подписываемого файла. Допустим также любой другой строковый идентификатор.
С данным идентификатором должен быть связан плагин для отображения документов на сервере DSS.

В зависимости от выбранного формата подписи необходимо указать сопутствующие параметры.
При подписи без подтверждения вторым фактором аутентификации параметры передаются в поле Parameters структуры Document.

При подписи с подтверждением вторым фактором аутентификации параметры передаются в поле Parameters структуры Transaction.

В случае отсутствия параметра IncludeCertChain в запросе на подпись используется значение этого параметра по-умолчанию, которое может быть назначено при помощи командлета Set-DssProperties.

Параметр IncludeDocumentName со значением true добавляет в подписанные атрибуты CMS подписи атрибут с именем файла. Идентификатор атрибута – 1.3.6.1.4.1.311.88.2.1.
Значение атрибута берётся из данных указанных при загрузке документа (параметр filename).
Параметр поддерживается для КриптоПро DSS начиная с версии 2.0.3710.

PDFCertificationLevel

Дополнительный параметры подписи отсутствуют

Передача индивидуальных для каждого документа параметров шаблона в метод подписи пакета документов

Если при пакетной подписи PDF-документов необходимо поставить видимую подпись с индивидуальным
шаблонам для каждого из переданных PDF-документов, то в дополнительные параметры следует
положить параметр PdfSignatureAppearancesData. Значение этого параметра должно быть представлено
как массив json-объектов, сериализованный в UTF-8 строку и закодированный в Base64.

Структура массива объектов с информацией о формате отображаемой подписи:

[
    {
        "TemplateId": "1",
        "Appearance": "ewoJIkNv..."
    },
    {
        "TemplateId": "3",
        "Appearance": "ewogICAiQ..."
    }
]

Для того чтобы закодировать этот json-массив для передачи внутри параметра подписи,
необходимо сначала из json-строки, в которую сериализуется массив, извлечь байты
в кодировке UTF-8:

// Encoding.UTF8.GetBytes()
91,123,34,84,101,109,112,108,97,116,101,73,100,34,58,34,49,34,44,34,...

А затем закодировать получившийся массив байтов в Base64:

// Convert.ToBase64String()
W3siVGVtcGxhdGVJZCI6IjEiLCJBcHBlYXJhbmNlI...

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

Передача параметров шаблона в метод подписи документов

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

• идентификатор шаблона в качестве значения параметра PdfSignatureTemplateId,
• параметры шаблона в качестве значения параметра PdfSignatureAppearance.

Содержимое шаблона должно быть представлено как json-объект, сериализованный в UTF-8 строку и
закодированный в Base64.

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

Пример

Содержимое документа test.txt:

ATTRIBUTES:
GlobalID=fe16c231-804d-4681-ac1b-a7612bd55cf8
DocType=PayDocCur
DocTypeVersion=2.0
CreateDate=2022-05-16 14:28:08.58
CreateOrg=348409
FIELDS:
DocInfo.DocAccount=40702840838050000545
DocInfo.DocDate=2022-05-16
DocInfo.DocNumber=104
DocInfo.DocSum=7.00
DocInfo.DocSumCurrency=840
PayDocCur.AdditionalInfo=/FULLPAY/
PayDocCur.AmountTransfer=7.00
PayDocCur.BenefAccountCurISOCode=USD
PayDocCur.BenefBankBIC=CHASUS31HPQ
PayDocCur.BenefBankBICType=SWIFT
PayDocCur.BenefBankCountryCode=840
PayDocCur.BenefBankCountryISOCode=US
PayDocCur.BenefBankName=JPMORGAN CHASE BANK, N.A.
PayDocCur.BenefBankPlace=NEW YORK,NY
PayDocCur.BenefCountryCode=044
PayDocCur.BenefCountryISOCode=BS
PayDocCur.Beneficiar=ASKOT INVESTMENTS LTD
PayDocCur.BeneficiarAccount=40807840955130000002
PayDocCur.BeneficiarAddress=NASSAU, EST HILL STREET, 3944
PayDocCur.BeneficiarCountry=БАГАМЫ
PayDocCur.BeneficiarPlace=NASSAU
PayDocCur.BranchShortName=0038-7981-01835
PayDocCur.ChargeBEN=false
PayDocCur.ChargeOUR=true
PayDocCur.ChargeSHA=false
PayDocCur.ChargesType=OUR
PayDocCur.CurrCodeISO=USD
PayDocCur.CurrCodeISOTransfer=USD
PayDocCur.CurrCodeTransfer=840
PayDocCur.Flag_TargetAssignment=false
PayDocCur.IMediaBankAddress=2, KRASNOGO TEKSTILSHCHIKA STREET
PayDocCur.IMediaBankBIC=SABRRU2P
PayDocCur.IMediaBankBICType=SWIFT
PayDocCur.IMediaBankCountryCode=643
PayDocCur.IMediaBankCountryISOCode=RU
PayDocCur.IMediaBankName=SBERBANK (SEVERO-ZAPADNY HEAD OFFICE)
PayDocCur.IMediaBankPlace=ST. PETERSBURG
PayDocCur.IMediaClirCodeSymbol=RU
PayDocCur.IMediaClirCountryCode=RU
PayDocCur.IMediaClirShortName=Банковский идентификационный код (БИК)
PayDocCur.IsMultiCurr=false
PayDocCur.OfficialsPhone=76502587430
PayDocCur.Option50a=F
PayDocCur.Option56a=A
PayDocCur.Option57a=A
PayDocCur.Payer=JSC 'SRI PI.'
PayDocCur.PayerAddress=LENINA
PayDocCur.PayerBIC=044525225
PayDocCur.PayerBankBIC=SABRRUMM
PayDocCur.PayerBankName=SBERBANK (HEAD OFFICE - ALL BRANCHE
PayDocCur.PayerBankPlace=Москва
PayDocCur.PayerCountryCode=643
PayDocCur.PayerCountryISOCode=RU
PayDocCur.PayerCountryNameRu=РОССИЯ
PayDocCur.PayerFiscalCode=7715784155
PayDocCur.PayerName=АО "НИИ ТП"
PayDocCur.PayerPlace=PERM
PayDocCur.PaymentDirection=0
PayDocCur.PaymentsDetails=FLOWING EXPENSES
PayDocCur.SenderOfficials=niitp_rut niitp_rut niitp_rut
PayDocCur.Urgent=false

Объект PostDocumentInput в формате JSON:

Пример запроса на создание неподписанного запроса на сертификат

Запрос

Пример ошибки object_not_found

Файл 99d8aeca-68a0-4985-bfc6-4891da69d1f8 найден,
6c67c768-3848-454a-b443-b039cdf357a2q – не найден.

Пример получения списка запросов на сертификат

Запрос

Пример получения списка сертификатов

Запрос

Примеры запросов

Пример запроса с указанием различительного имени в строковом представлении:

Примечание

Параметр ClientSignFullDocRequired определяет тип данных, которые будут
передаваться в МП для подписи.

Если ClientSignFullDocRequired = $false, в МП передаётся только хэш-значение документа.
В данном режиме поддерживаются все форматы подписи.

Если ClientSignFullDocRequired = $true, в МП передаётся документ.
В данном режиме поддерживаются следующие форматы подписи: CMS (CAdES-BES, CAdES-T, CAdES-XLT1), XMLDSig, Необработанная подпись.

Создание запроса на сертификат с подтверждением при помощи вторичной аутентификации (v1 api)

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

При этом в массиве параметров транзакции метода /transactions
должны быть отображены следующие поля запроса на сертификат:

Создание подписи в асинхронном режиме

Последовательность шагов при подтверждение операции подписи в асинхронном режиме:

1. Аутентификация пользователя на Центре Идентификации
2. Загрузка документов для подписи
3. Создание операции подписи на Сервисе Подписи
4. Отправка запроса на подтверждение операции подписи
5. Ожидание подтверждения операции в DSS SDK и подписи документов
6. Выгрузка подписанного документа

На шаге 3 для создания подписи с подтверждением в асинхронном режиме необходимо в вызове Signature
передать дополнительные параметры:

• IsAsync – true
• Callback – URL-адрес для оповещения о заверщении операции подписи

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

Типовые ошибки

Предназначен для загрузки небольшого пакета документов в хранилище.
При загрузке считается хэш документа.
Содержимое документов передается в теле запроса через multipart/form-data.

При формировании запроса необходимо выставить Content-Type: multipart/form-data.

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

Для загрузки некоторого документа с именем {docName} необходимо передать пару элементов.

Управление сертификатами пользователя

С точки зрения API DSS управление сертификатами и запросами на сертификат не изменяется.
Получение списка сертификатов и запросов, удаление сертификатов и запросов, аннулирование сертификатов, загрузка содержимого сертификата
и запроса на сертификат осуществляется через действующие конечные точки – /certificates-v2, /request-v2.

Прикладная система может различить запросы на сертификат по типу хранения ключ (на сервере DSS или у пользователя) по значению поля CertificateType объекта
DSSCertRequest: ServerSide, ClientSide. Так же Прикладная система может может проверить значение поля Storage: Mobile, Server.

Прикладная система может различить сертификат по типу хранения ключ (на сервере DSS или у пользователя) по значению поля CertificateType объекта
DSSCertificateEx: ServerSide, ClientSide. Так же Прикладная система может может проверить значение поля Storage: Mobile, Server.

Если к Учетной записи пользователя привязано несколько различных мобильных приложений, то прикладной системе необходимо определить для какого приложения можно создать
операцию с данным сертификатом. Для этого прикладная система должна посмотреть на значение поля StorageInfo в объекте сертификата DSSCertificateEx.

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