Отображаемая подпись 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
или пользователем в мобильном приложении и передан в УЦ для обработки.

Примечание

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

Выпущенный сертификат может быть установлен в 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
Примечание

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

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

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

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

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

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

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

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

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

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

ColorDescription

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

ПолеТипОписание
RedintЗначение красной компоненты цвета
GreenintЗначение зелёной компоненты цвета
BlueintЗначение синей компоненты цвета

SignatureRect

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

ПолеТипОписание
LowerLeftXintX координата левого нижнего угла прямоугольника
LowerLeftYintY координата левого нижнего угла прямоугольника
UpperRightXintX координата правого верхнего угла прямоугольника
UpperRightYintY координата правого верхнего угла прямоугольника
BorderRadiusintРадиус скругления углов прямоугольника
BorderWeightintТолщина линии границы прямоугольника. 0 – отсутствие границы (значение по умолчанию)
BorderColorColorDescriptionЦвет границы прямоугольника. По умолчанию (0, 0, 0)
BackgroundColorColorDescriptionЦвет фона прямоугольника. По умолчанию (255, 255, 255)
ContentMarginintОтступ от границы прямоугольника до содержимого представления подписи

FontDescription

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

ПолеТипОписание
FontSizeintРазмер шрифта
FontFamilyintНазвание шрифта. Допустимые значения: times, arial. По умолчанию – times
FontColorColorDescriptionЦвет шрифта

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

Типы подписи

ИмяКодЗначение
XMLDSigПодпись документа в формате XMLDSig
GOST34101Электронная подпись по ГОСТ Р 34.10 – 2001 или ГОСТ Р 34.10 – 2022
CAdES2Подпись формата CAdES-BES, CAdES-T, CAdES-X Long Type 1
PDF3Подпись PDF документов
MSOffice4Подпись документов MS Word и Excel
CMS5Подпись формата CAdES-BES

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

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

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

Внимание!

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

ИмяЗначениеОписание
CADESTypeBES (0)Подпись в формате CAdES-BES
T (2)Подпись в формате CAdES-T
XLT1 (1)Подпись в формате CAdES-X Long Type 1
IsDetached (o)true/falseОтделённая/присоединённая подпись.
По умолчанию false
TSPAddress (r)Адрес TSP службы (используется только для формата T, XLT1)
Hash (o)true/falseПодпись значения хэш-функции ГОСТ Р 34.11 – 94
В поле Content должно быть передано значение хэш-функции от документа.
CmsSignatureType (o)signПодпись документа
cosignСоподпись документа
counterSignЗаверяющая подпись документа
ContentEncoding (o)base64Содержимое документа закодировано в Base64
binaryСодержимое документа в двоичном представлении
OriginalDocument (o) Содержимое исходного документа (используется при соподписи подписи).

При создании пакетной отделённой соподписи (как самого документа, так и его
хэш-значения) содержимое исходного документа (или его хэш-значение) передаётся
через структуру DocumentContent (в поле OriginalContent), параметр
OriginalDocument не используется.
SignatureIndex (o)Индекс подписи, для которой создается заверяющая подпись
AuthenticatedAttributes (o)Аутентифицированные атрибуты CMS подписи.

Значение закодированный в Base64 JSON-словарь строка-строка.
Ключ словаря – OID атрибута
Значение ключа – закодированное в Base64 значение атрибута.
IncludeCertChain (o)true/falseЗначение, показывающее, необходимо ли прикладывать цепочку сертификатов для сертификата подписи к подписанному документу
IncludeDocumentName (o)true/falseЗначение, показывающее, необходимо ли включить атрибут с именем файла
Читайте также:  Электронные подписи (ЭЦП) - купить в Первом БИТе - Георгиевск

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

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

ИмяЗначениеОписание
PDFFormatCMS (2)Подпись PDF документов с использованием формата PKCS7
CAdEST (0)Подпись PDF документов с использованием формата CAdES-T
CAdES (1)Подпись PDF документов с использованием формата CAdES-X Long Type 1
PDFReason (r)Цель подписания документа
PDFLocation (r)Место подписания документа
PdfSignatureAppearance (o)Строковое представление шаблона видимой (отображаемой) PDF-подписи
PdfSignatureTemplateId (o)1Идентификатор шаблона видимой (отображаемой) PDF-подписи
Простой текстовый шаблон
2Идентификатор шаблона видимой (отображаемой) PDF-подписи
Шаблон с логотипом и текстом
3Идентификатор шаблона видимой (отображаемой) PDF-подписи
Шаблон в виде изображения
PDFCertificationLevel(o)Уровень сертификации подписи. Описывает, в зависимости от уровня, тип изменений, которые можно вносить в документ. Возможные значение описаны ниже

PDFCertificationLevel

Примечание

При создании видимой (отображаемой) подписи необходимо указание параметров
PdfSignatureTemplateId и PdfSignatureAppearance

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

ИмяЗначениеОписание
XMLDSigTypeXMLEnveloped (0)Вложенная XMLDSig подпись
XMLEnveloping (1)Присоединённая XMLDSig подпись
XMLTemplate (2)XMLDSig подпись по шаблону
XAdESTypeNone (0)XAdES не используется, будет создана подпись с указанным значением параметра XMLDSigType
BES (1)Подпись формата XAdES
ИмяЗначениеОписание
Hashtrue/falseПодпись значения хэш-функции ГОСТ Р 34.11 – 94
В поле документ должно быть передано значение хэш-функции от документа

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

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

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

Примечание

В данном примере для первого подписываемого PDF-документа будет использован формат
отображаемой подписи с идентификатором шаблона = 1, а для второго документа
будет использован формат отображаемой подписи с идентификатором шаблона = 3.

[
    {
        "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
должны быть отображены следующие поля запроса на сертификат:

CertificateRequestПараметры транзакции
AuthorityIdCAId
PinCodeНе используется
TemplateCertTemplateOid
DistinguishedNameНе используется
RawDistinguishedNameCertSubjectName
Parameters ->EkuStringEkuString
Parameters ->GroupIdGroupId
Примечание

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

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

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

  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.

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

Оцените статью
ЭЦП Эксперт
Добавить комментарий

Adblock
detector