Примеры запросов на создание подписи средствами REST API | КриптоПро DSS

Oauth 2.0

При создании операции через конечную точку authorize желаемый срок
действия передаётся через параметр запроса dss_transaction_lifetime.
Срок действия транзакции указывается в секундах.

Пример

Внимание!

В заголовке Authorization необходимо передать access_token, полученный на предыдущем шаге.

Время жизни операций

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

Для поддержки данного сценария Администратор должен задать максимально допустимое
время жизни операций в параметра MaxTransactionLifetime командлетов Get-DssStsProperties, Set-DssStsProperties.

• Если MaxTransactionLifetime равен 0, то переданное прикладной системой время жизни операции Ttl игнорируется.
• Если MaxTransactionLifetime отличен от 0, то переданное прикладной системой время жизни операции должно быть меньше указанного значения.
• Если прикладная система укажет время жизни операции больше чем MaxTransactionLifetime, то операция будет создана со временем жизни MaxTransactionLifetime.
• Если прикладная система не укажет время жизни операции, то операция будет создана со временем жизни по умолчанию OtpConfirmationTimeOut.

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

Настройками КриптоПро DSS должно быть обеспечено условие TokenTimeout > MaxTransactionLifetime. TokenTimeout — время выполнения операции
задаваемое на сервисе подписи командлетами Get-DssProperties, Set-DssProperties.

Выбор метода вторичной аутентификации

Если пользователю назначено несколько методов вторичной аутентификации, то в ответ на первый запрос к
конечной точке /v2.0/confirmation Сервис Подтверждения Операций
вернёт список доступных пользователю методов вторичной аутентификации.

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

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

Пример ответа:

Выполнение операции

Данный шаг является опциональным и относится только к сценариям подтверждения операций на Сервисе Подписи.

Выполнение операции на Сервисе Подписи* находится за рамками данного раздела.
Для аутентификации запроса необходимо указать маркер доступа полученный на предыдущем шаге.

Дополнительные отображаемые данные

Прикладная система может передать дополнительные сведения об операции, которые она хочет отобразить
пользователю. Дополнительные сведения передаются в поле ConfirmationParams первого запроса
RequestSecurityToken к
конечной точке /v2.0/confirmation.

Поле ConfirmationParams представляет собой словарь, где ключом является имя параметра. Имя параметра должно
быть задано в шаблоне сообщения, передаваемого пользователю.

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

Завершение подтверждения операции

Если ответ Сервиса Подтверждения операция содержит флаги IsFinal — true,
IsError — false,
то сервис вернул новый маркер доступа AccessToken. Данный маркер доступа содержит факт
подтверждения операции пользователем. Если

Загрузка документа

Описание API Сервиса Преобразования документов — Сервис Преобразования документов

Подписываемый документ (-ы) необходимо загрузить в Сервис Обработки Документов.
Сервис подготовит необходимые данные для подтверждения операции подписи:

• хэш от документа (ГОСТ Р 34.11-2022)
• Выжимка из документа
• Печатное представление документа (опционально)
• PDF-представление документа

Документ загружается на сервер в поточном режиме. После загрузки сервис вернёт ID загруженного документа.
Идентификатор загруженного документа необходимо будет передать в Сервис Подписи при создании операции подписи.

Выжимка из документа и PDF-представление документа являются обязательными атрибутами документа при подтвержении операции подписи через DSS SDK.
PDF-представление документа всегда формируется сервисом обработки документов.
Выжимка из документа может быть сформирована как сервисом так и передана из вызывающей системы PostDocumentInput
в параметре AdditionalInfo в ключе SnippetTemplate.

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

Запроса подтверждения операции

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

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

После выполнения данного шага операция перейдёт в статус Challenged.

Для запроса подтверждения операции необходимо отправить запрос RequestSecurityToken
на конечную точку /<sts_app_name>/v2.0/confirmation.

Интеграция посредством soap

1. Пользователь отправляет сформированный платежный документ в систему ДБО.
2. Система ДБО, используя штатные документированные механизмы КриптоПро DSS (SOAP), передает подписываемый документ и подписанный маркер доступа (SAML-токен), содержащий информацию о пользователе (имя пользователя, номер мобильного телефона и т.п.).
3. Для подтверждения подписания документа КриптоПро DSS направляет пользователю SMS-сообщение, содержащее код подтверждения подписания и значимые поля документа (например, получатель, сумма и т.п.), на номер мобильного телефона полученный в маркере доступа.
4. Пользователь вводит полученный код подтверждения в поле формы веб-интерфейса системы ДБО.
5. Система ДБО передает полученный код подтверждения КриптоПро DSS.
6. КриптоПро DSS, используя документированные функции ПАКМ «КриптоПро HSM», отправляет запрос на подписание документа с использованием закрытого ключа пользователя и получает подписанный документ.
7. КриптоПро DSS передает подписанный документ в систему ДБО.

Масштабируемость и отказоустойчивость

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

Настройки

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

• Для прикладной системы зарегистрирован OAuth-клиент
• Для учётной записи пользователя заданы методы первичной и вторичной аутентификации
• Для учётной записи пользователя заданы операции требующие подтверждения
• Зарегистрирован ресурс, для которого будет выполняться подтверждение операции
• Выполнены необходимые настройки методов вторичной аутентификации
• Настроены модули оповещения о статусе операции (опционально)

Необработанная подпись

Сервис Подписи DSS позволяет формировать необработанную подпись двумя способами:

Ожидание подтверждения

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

Если для подтверждения операции требуется предъявить одноразовый пароль (отправленный в SMS, Email или полученный с помощью
мобильного приложения или токена OATH), то прикладная система должна дождаться от пользователя ввода одноразового пароля
в её интерфейсе и передать его в DSS на следующем шаге.
См. раздел Аутентификация и подтверждение операций по одноразовым паролям.

Если для подтверждения операции используется мобильное приложение (myDSS 1.0, мобильные приложения со встроенным DSS SDK),
то прикладная система может:

• асинхронный режим: ожидать оповещение о подтверждении пользователем операции на адрес указанный в параметре CallbackUri.
• синхронный режим: периодически опрашивать Сервис Подтверждения операций о статусе операции.

В асинхронном режиме прикладная система получит сообщение о завершении операции
на адрес указанный в параметре CallbackUri:

Примеры ответа на CallbackUri

Оповещение о подтверждении операции:

{
    "Result":"success",
    "TransactionId":"aa1a4a5d-bb4d-456b-87da-31818604fcd8",
    "Error":"",
    "ErrorDescription":null}

Оповещение об отказе (пользователь в мобильном приложении Отказался от подтверждения операции):

{
    "Result":"failed",
    "TransactionId":"e19de724-0a4f-4d29-903a-0d3c93735dad",
    "Error":"all_actions_declined",
    "ErrorDescription":"Все действия входящие в состав операции 'e19de724-0a4f-4d29-903a-0d3c93735dad' были отклонены."
}

Оповещение об истечении строка действия транзакции.

{
"Result":"failed",
"TransactionId":"bc0ffdee-7143-439f-bf6b-d1400725d8f1",
"Error":"transaction_expired",
"ErrorDescription":"Срок действия транзакции истёк"
}

Если пользователь подтвердил операцию на мобильном устройстве, необходимо обратиться на Сервис Подтверждения Операций
для получения нового AccessToken. В запросе передаётся идентификатор RefId.

Если интегрируемая система не передала адрес CallbackUri в первом запросе к /<sts_app_name>/v2.0/confirmation,
то статус подтверждения операции она сможет узнать, периодически опрашивая Сервис Подтверждения Операций.

В поле ChallengeResponse передаётся:

В поле TextChallengeResponse передаётся:

Операции сервиса подписи

В таблице ниже перечислены операции Сервиса Подписи, которые могут быть выполнены с подтверждением.

Отмена вторичной аутентификации

Прикладная система может Отменить операцию, для которой было запрошено подтверждение.
Отменить можно только операцию в статусе Challenged.

Прикладная система передать идентификатор операции и тип управлящего действия в ответе
RequestSecurityToken в поле
ControlChallengeResponse

Отображаемые сведения об операциях

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

Первичная аутентификация

Первичная аутентификация производится по протоколу OAuth 2.0 в соответствии с выбранным
методом и сценарием аутентификации.
Результатом первичной аутентификации пользователя является маркер доступа (JWT-токен). Полученный маркер
должен быть использован при вызове методов API DSS в дальнейшем.

Маркер доступа имеет ограниченный срок действия. После истечения срока действия прикладная система
должна получить новый маркер доступа для возможности вызова методов API.
Срок действия маркера доступа задаётся Администратором DSS в настройках OAuth-клиента, назначенного
прикладной системой.

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

Подпись в формате cades-xlt1/cades-t

Сервис Подписи DSS позволяет создавать следующие виды подписи в формате CAdES-XLT1/CAdES-T:

Подпись в формате xmldsig

REST-интерфейс Сервиса Подписи позволяет формировать XML-подпись следующими способами:

Подтверждение операции на сервисе подписи

Предварительные условия

В подтверждении операции задействованы следующие сервисы DSS:

Пользовательский сертификат

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

• передача идентификатора сертификата в запросе на формирование подписи
• использование сертификата по умолчанию

Для получения идентификтора сертификата можно воспользоваться методом GetCertificates.

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

Пререквизиты

• Зарегистрированный OAuth-клиент для интегрируемой системы

• Пользователю создана учетная запись в Центре Идентификации
• Пользователю выпущен сертификат подписи

• На Сервисе Обработки Документов (СОД) зарегистрированы плагины для отображения документов.

Пример шаблона с дополнительными параметрами для операции подписи, подтверждаемоей в dss sdk.

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

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

Примечание

При создании заверяющей подписи в поле Content необходимо передавать подписанный документ, для которого требуется заверяющая подпись.

В поле OriginalDocument необходимо передавать исходный документ.

В запросе должен присутствовать параметр CmsSignatureType, имеющий значение countersign.

В запросе может присутствовать параметр SignatureIndex, указывающий индекс заверяемой подписи. В случае, если данный параметр отсутствует в запросе, Сервис Подписи будет заверять первую подпись в документе.

Процесс подтверждения операций

Подтверждение операций производится через конечные точки:

Конечная точка /v2.0/confirmation/cert используется в случае, если прикладная система используется OAuth-клиент
с аутентификацией по сертификату.

Процесс подтверждения операций состоит из следующих шагов:

Сведения об операции

Любая операция характеризуется:

Сведения об операции сохраняются в базе данных Сервиса Обработки Операций.
По умолчанию сведения хранятся бессрочно. Большое количество сохранённых операций сказывается на производительности DSS.
Для высоконагруженных систем рекомендуется хранить не более 5 млн. операций.
Администратор DSS должен настроить Очистку данных об операциях

Пользователь и/или прикладная система могут получить сведения об операциях через API Сервиса Обработки Операций.
Данная конечная точка может быть использована для контроля статуса операции. Например, если прикладная система не получила callback с результатами
подтвреждения операции, или необходимо получить информацию о ранее подтверждённых операциях.

КриптоПро DSS позволяет подтверждать следующие типы операций:

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

ScopeConfirmation относится к подтверждению операций, зарегистрированных Администратором DSS.
Администратор может зарегистрировать любое количество операций, выполнение которых требует подтверждения пользователем.
Но в аудите DSS все подтвержденные операции будут отображаться с одинаковым кодом события.

PrivateKeyAccess относится к подтверждению доступа к закрытому ключу пользователя при помощи Cloud CSP.

В v2 API операции типа SignDocuments не используются. В v2 API нет различий между подписью одного документа и
подписью пакета документов (в отличие от v1 API), поэтому операции подписи имеют тип SignDocument.

В процессе обработки каждая операция проходит через несколько статусов:

Ниже представлена схема переходов статусов операции.

Для операций Issue, ScopeConfirmation статус Created не поддерживается, начальное состояние
для данных операций Challenged.

Для операций Issue, ScopeConfirmation статус Completed не поддерживается, успешному завершению операций
соответствует статус Confirmed.

Штатным изменением статуса операции является: Created -> Challenged -> Confirmed -> Completed.

Время жизни операции настраивается Администратором DSS.
Время подтверждения операции задается на Центре Идентификации — параметр OtpConfirmationTimeOut командлетов Get-DssStsProperties, Set-DssStsProperties.

Так же прикладная система может явно указать срок жизни операции. Для поддержки данного сценария Администратор должен задать максимально допустимое
время жизни операций в параметра MaxTransactionLifetime командлетов Get-DssStsProperties, Set-DssStsProperties.

• Если MaxTransactionLifetime равен 0, то переданное прикладной системой время жизни операции игнорируется.
• Если MaxTransactionLifetime отличен от 0, то переданное прикладной системой время жизни операции должно быть меньше указанного значения.
• Если прикладная система укажет время жизни операции больше чем MaxTransactionLifetime, то операция будет создана со временем жизни MaxTransactionLifetime.
• Если прикладная система не укажет время жизни операции, то операция будет создана со временем жизни по умолчанию OtpConfirmationTimeOut.

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

Настройками КриптоПро DSS должно быть обеспечено условие TokenTimeout > OtpConfirmationTimeOut.
То есть время выполнения операции должно быть больше, чем время подтверждения операции.Если время выполнения будет меньше времени подтверждения, то возможны случаи когда DSS не успеет выполнить
операцию после получения подтверждения пользователя и операция будет помечена как истёкшая Expired.

Разница между TokenTimeout и OtpConfirmationTimeOut зависит от сценария подтверждения операции и нагрузки как на DSS так и на прикладную систему.
Если используется асинхронное подтверждение операций, то разница может составлять десятки секунд или минуты.
Если используется синхронное подтверждение, то разница зависит от пракладной системы, вызывающей API DSS.

Создание операции на сервисе подписи

Данный шаг является опциональным и относится только к сценариям подтверждения операций на Сервисе Подписи.

Создание операции на Сервисе Подписи находится за рамками данного раздела. Результатом создания операции на Сервисе Подписи
является идентификатор операции Operation->Id. Пример ответа Сервиса Подписи, содержащий идентификатор операции:

Пример ответа Сервиса Подписи

{
    "Operation": {
        "Id": "30110c89-231b-40ba-a03e-3cab41a1d35e",
        "Result": null,
        "Status": "Created",
        "Error": null,
        "ErrorDescription": null,
        "ExpirationDate": 1641558446
    }
}

Прикладная система должна проверить значение поля Operation->Status перед продолжением выполнения сценарий.
Если выполнение операции требует подтверждения пользователя, то поле Operation->Status будет иметь значение
Created.

Требование подтверждения операции настраивается в профиле пользователя на Центре Идентификации.

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

Форматы подписи

REST-интерфейс Сервиса Подписи DSS позволяет подписывать документы, используя следующие форматы электронной подписи:

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