Работа с ЭЦП в Sber API
Общие сведения
Электронная цифровая подпись или электронная подпись (далее - ЭП) — это цифровой аналог рукописной подписи на бумаге. Сокращенно ее обозначают как ЭЦП или ЭП. Это реквизит электронного документа, полученный в результате криптографического преобразования информации с использованием закрытого ключа подписи и позволяющий проверить отсутствие искажения информации в электронном документе с момента формирования подписи (целостность), принадлежность подписи владельцу сертификата ключа подписи (авторство), а в случае успешной проверки подтвердить факт подписания электронного документа (неотказуемость).
Использование ЭП
Электронная подпись (ЭП) состоит из сертификата (открытый ключ) и криптографической части (закрытый ключ, доступный только владельцу). С помощью закрытого ключа документ шифруется, а открытого — дешифруется. Сертификат ЭП содержит всю необходимую информацию: данные о владельце, срок действия подписи и т. д. Криптографическая часть включает только механизмы шифрования.
Вот для чего применяется электронная подпись:
- подтверждение авторства — позволяет установить, что документ или сообщение были созданы указанным в документе человеком;
- проверка целостности документа — с помощью ЭП можно проверить, не были ли внесены изменения в документ после его подписания;
- защита от подделки документа — ЭП нельзя изменить или удалить без нарушения целостности и подлинности документа или сообщения;
- доказательство юридической значимости документа, авторства и согласия сторон.
Виды ЭП
Существует несколько видов ЭП:
- Простая электронная подпись (ПЭП) — подпись, сформированная с помощью одноразового пароля, подтверждает факт формирования ЭП определенным лицом (авторство). Для подписи важных документов она не подходит — ее степени защиты для этого недостаточно.
- Усиленная неквалифицированная подпись (УНЭП) — подпись, сформированная с использованием сертифицированных средств криптозащиты информации (СКЗИ), содержащая сертификат подписанта. Обеспечивает проверку авторства и целостности. Применима для документов, исполняемых в рамках договора между Клиентом и Банком.
- Усиленная квалифицированная электронная подпись (УКЭП) — подпись, сформированная с использованием сертифицированных средств криптозащиты информации (СКЗИ), содержащая квалифицированный сертификат подписанта. Обеспечивает проверку авторства и целостности. Используется для документов, требующих УКЭП, и исполняемых вне Банка.
Подписание документов с помощью ЭП
Для формирования электронной подписи документа применяются сертифицированные средства криптозащиты информации.
Документ может быть подписан двумя способами:
- после подписания создается один файл, содержащий исходные данные документа и данные подписи (прикрепленная подпись);
- после подписания создаются два файла: файл с документом и файл с подписью (открепленная подпись).
Банк поддерживает работу с открепленными подписями.
Терминология
- КУЦ - код удостоверяющего центра. Является уникальным идентификатором организации в УЦ СберБанка.
- Электронный ключ (токен) - программно-аппаратное устройство на базе «VPN-key-TLS» или «Рутокен TLS», используемое в СберБизнес для генерации ключей ЭП, ключей шифрования, формирования и проверки УНЭП/УКЭП, шифрования и подключения к защищенной корпоративной VPN–сети Банка. Электронный ключ реализует алгоритмы шифрования и электронной подписи, соответствующие российскому ГОСТ.
- Bicrypt ID - идентификатор сертификата, который состоит из (КУЦ) + (номер сертификата) + (тип сертификата: s-сертификат пользователя; t-сертификат TLS) + (ФИО пользователя клиента).
- ЭП - электронная цифровая подпись, которая формируется закрытым ключом.
- Сертификат ЭП - сертификат электронной подписи, используется для идентификации ЭП в полученном документе.
Использование ЭП в API
В API можно использовать два вида документов: те, которые подписаны ЭП, и те, которые не подписаны.
- Если документ подписан ЭП, то он сразу же отправляется на обработку в автоматизированную банковскую систему (АБС банка), при условии, что под документом есть достаточное количество ЭП.
- Документ без ЭП создается в СберБизнес как черновик. Если клиент не подпишет этот черновик в СберБизнес, то документ не отправится на обработку. Использование ЭП в API помогает автоматизировать процесс подписания отправляемых документов.
Ресурсы API с возможностью передачи ЭП
| # | Описание | Endpoint |
|---|---|---|
| 1 | Создание платежных поручений | /fintech/api/v1/payments |
| 2 | Отправка зарплатной ведомости | /fintech/api/v1/payrolls |
| 3 | Отправка заявления на перевод между бизнес-картами | /fintech/api/v2/corporate-cards/sign-and-approve |
| 4 | Создание документа | /fintech/api/v1/generic-letters/to-bank |
| 5 | Создание СПД | /fintech/api/v1/confirmatory-documents-inquiries |
| 6 | Создание СВО | /fintech/api/v1/currency-operation-details |
| 7 | Создание Письмо для целей ВК | /fintech/api/v1/curr-control-messages/to-bank |
| 8 | Создание заявления на регистрацию ВК | /fintech/api/v1/bank-control-statements/reg-curr-contracts |
| 9 | Создание валютного платежного поручения | /fintech/api/v1/pay-doc-cur |
Авторизация
Все запросы в Sber API выполняются от имени конкретного пользователя СберБизнес, в том числе при интеграции для работы с информацией только по собственной компании. Запросы в Sber API в заголовке (Header) содержат параметр - Authorization. В нем требуется передавать токен доступа (access_token) пользователя. Получение токена доступа осуществляется с помощью сервиса СберБизнес ID. Подробно о подключении и работе сервиса авторизации рассказали в соответствующем разделе документации.
При интеграции по собственной компании потребуется выбрать одного пользователя СберБизнес и пройти им авторизацию через СберБизнес ID единоразово. В дальнейшем вам потребуется своевременно обновлять токен доступа при помощи токена обновления - обновить токен доступа.
Схема работы ЭП в API
- Графическое описание
- Текстовое описание
| № | Что делаем | Подробности |
|---|---|---|
| 1 | Создайте для подписанта профиль в СберБизнес | Чтобы автоматизировать процесс подписания документов, вам нужно создать профиль в СберБизнес для сотрудника (подписанта), чья подпись будет использоваться. Если у подписанта уже есть профиль в СберБизнес, создайте дублирующий профиль СберБизнес. Дублирующий профиль будет использоваться только при работе с банком через Sber API. Если компания использует систему двойного подписания документов (Первая и Вторая подписи), создайте дублирующий профиль СберБизнес для каждого подписанта. |
| 2 | Выпустите на подписанта сертификат ЭП | Выпуск сертификата ЭП происходит в УЦ СберБанка. Процесс выпуска сертификата необходимо реализовать с помощью ресурсов Sber API в рамках вашей Платформы. Подробнее о процессе оформления сертификата ЭП расскажем в соответствующем разделе. |
| 3 | Подпишите документ и отправьте в Банк | Для создания ЭП к документу потребуется инструмент для подписания - средство криптографической защиты информации (СКЗИ). СКЗИ вы выбираете самостоятельно исходя из ваших задач и потребностей. Ниже по странице в соответствующем разделе мы расскажем о следующих способах подписания: 1. Токен (Инфокрипт, Рутокен) с использованием программных средств (API токена); 2. Токен + СКЗИ Крипто Про 3. OpenSSL + ГОСТ алгоритмы Созданную открепленную подпись (detached) необходимо закодировать с помощью Base64 и полученный результат отправить в теле запроса. |
Создайте для подписанта профиль в СберБизнес
Создайте для сотрудника профиль в СберБизнес. Это поможет автоматизировать процесс подписания документов.
Если у сотрудника уже есть профиль в СберБизнес, создайте дублирующий профиль. Он будет использоваться только при работе с банком через Sber API.
Если компания использует систему двойного подписания документов (Первая и Вторая подписи), создайте дублирующий профиль СберБизнес для каждого подписанта.
Создать профиль с правом подписи можно в отделении Сбербанка, подав корректирующее заявление.
Дублирующий профиль нужен для сохранения возможности входа в СберБизнес для сотрудника и одновременного использования его подписи в Sber API.
Закрытая часть ключа и сертификат ЭП будут храниться на токене или в другом защищенном пространстве. Вашей Платформе потребуется постоянный доступ к токену для автоматизированной работы с ключом и сертификатом. При условии, что у сотрудника один профиль в СберБизнес с типом защиты «электронный ключ» (токен) и его токен будет установлен в сервер (или другое устройство, которое хранит данные Платформы), он лишится возможности входа в СберБизнес.
Если возможность входа в СберБизнес не нужна, дублирующий профиль можно не создавать.
У подписанта может быть один одновременно активный сертификат ЭП. При наличии двух профилей в СберБизнес (основной и дублирующий) с типом защиты «электронный ключ» (токен), активным будет только один сертификат ЭП. При выпуске еще одного сертификата ЭП предыдущий деактивируется.
Профиль подписанта должен иметь следующие характеристики:
- Право на подписание
- Вариант защиты Системы и подписания — «электронный ключ» (токен)
Вариант защиты Системы и подписания определяет метод подписания документов. При выборе «одноразовые SMS-пароли» используются одноразовые коды из сообщений для подписания документов, что соответствует подписи ПЭП. Для обеспечения безопасности обмена подписанными документами с банком через API требуется использование НЭП, поэтому нужен профиль СберБизнес с типом защиты «электронный ключ» (токен).
Обратите внимание, что даже при типе защиты «электронный ключ» (токен) сертификат ЭП может храниться на носителе, отличном от токена (например, на внутреннем хранилище вашего сервера). Приобретение токена является необязательным, но рекомендуется.
Прежде чем решить вопрос о необходимости приобретения токена, изучите разделы Выпустите на подписанта сертификат ЭП и Подпишите документ и отправьте в Банк.
Выпустите на подписанта сертификат ЭП
Выпуск неквалифицированного сертификата клиентской подписи выполняет аккредитованный УЦ Банка.
Для работы в Sber API подойдет сертификат ЭП, выпущенный при помощи процедуры, описанной ниже.
Срок действия выпущенного сертификата ЭП составляет 36 месяцев, поэтому необходимо реализовать полноценный процесс получения сертификатов.
Эти сертификаты ЭП не подойдут для работы со Sber API:
- ЭП, созданные сертификатами ЭП других УЦ;
- Сертификат ЭП, выпущенный через СберБизнес.
Для реализации процесса оформления сертификата ЭП на вашей Платформе потребуется:
- Дублирующий профиль пользователя-подписанта в СберБизнес (из пункта 1)
- Инструмент для создания закрытого ключа и запроса на открытый ключ - сертифицированное средство криптографической защиты информации (СКЗИ);
- Хранилище закрытого и открытого ключей (сертификата ЭП) - токен или другое ваше устройство;
- Разработка механизма взаимодействия с Банком с использованием Sber API.
Выбор СКЗИ
Выбор СКЗИ может влиять на способ хранения сертификата и закрытого ключа ЭП. Например, если выбрано СКЗИ, которое поддерживает работу с HSM, то сертификат и ключ могут храниться на этом устройстве для обеспечения дополнительного уровня безопасности. Кроме того, выбор СКЗИ может определить возможности по интеграции с другими системами и платформами для хранения ключей ЭП.
Сертификат и закрытый ключ ЭП могут храниться не только на токене, но и на специальных устройствах для хранения ключей (HSM), в защищенном хранилище на сервере или других средствах, предоставляемых СКЗИ.
СКЗИ отличаются друг от друга по различным параметрам, таким как поддерживаемые алгоритмы шифрования, уровень безопасности, возможности интеграции с различными платформами, удобство использования и т.д.
Для российских компаний доступны различные СКЗИ, такие как КриптоПро CSP, Рутокен ЭЦП, ИнфоКрипт, ИнфоПульс ГОСТ, КриптоАРМ и др.
Выбор СКЗИ - рекомендации
| № | Название | Описание | Стоимость | Где взять |
|---|---|---|---|---|
| 1 | КриптоПро CSP | Разработанная одноименной компанией линейка криптографических утилит. Они используются в других программах для генерации электронной подписи (ЭП), работы с сертификатами, организации структуры PKI и т.д. Плюсы: - подходит для всех, кто использует усиленную квалифицированную электронную подпись; - облегчает работу с государственными порталами и информационными системами; - поддерживает электронный документооборот с контрагентами; - помогает участвовать в электронных торгах, например, на Госуслугах; - упрощает удаленное трудоустройство и подписание машиночитаемых доверенностей. | CSP CryptoPro — платный продукт. Лицензию можно заказать на сайте разработчика или приобрести у официальных дилеров. | На сайте вендора |
| 2 | OpenSSL + ГОСТ алгоритмы | Криптографическая библиотека, которая реализует протоколы Secure Sockets Layer (SSL) и Transport Layer Security (TLS). Она предоставляет инструменты для генерации приватных ключей RSA, создания запросов на подписание сертификатов (CSR) и выполнения кодирования/декодирования. OpenSSL написан на языке C, но существуют оболочки для многих других языков программирования. Плюсы: - имеет открытый исходный код, что делает его доступным для изучения и модификации сообществом разработчиков; - совместимость с операционными системами Windows, Linux и Mac. | Бесплатно | Скачать с официального сайта Для использования ГОСТ-алгоритмов в OpenSSL потребуется библиотека gost.dll. |
| 3 | СКЗИ от Рутокен | Встроено в носитель Рутокен ЭЦП 3.0. Носитель выпускается компанией АО «Активсофт» и предназначен для хранения сертификатов ЭП, генерации ЭП, шифрования документов и защиты информации от доступа посторонних лиц. Плюсы: - дополнительный уровень безопасности благодаря двухфакторной аутентификации с использованием PIN-кода; - встроенная лицензия на криптопровайдер, что позволяет избежать установки СКЗИ на компьютер; - поддержка российских и международных стандартов информационной безопасности; - совместимость с операционными системами Windows, Linux и Mac. | С тарифами вы можете ознакомиться на сайте банка. | Как получить электронный ключ (токен) |
| 4 | СКЗИ от Инфокрипт | Встроено в носитель Инфокрипт-токен. Носитель выпускается компанией ООО Фирма «ИнфоКрипт» и предназначен для хранения сертификатов ЭП, генерации ЭП, шифрования документов и защиты информации от доступа посторонних лиц. Плюсы: - дополнительный уровень безопасности благодаря двухфакторной аутентификации с использованием PIN-кода; - встроенная лицензия на криптопровайдер, что позволяет избежать установки СКЗИ на компьютер; - поддержка российских и международных стандартов информационной безопасности; - совместимость с операционными системами Windows, Linux и Mac. | С тарифами вы можете ознакомиться на сайте банка. | Как получить электронный ключ (токен) |
Инструкции для СКЗИ
Процесс выпуска сертификата ЭП через Sber API
Ниже в формате usecase будет описан процесс выпуска сертификата ЭП на пользователя СберБизнес.
Мы предусмотрели 2 варианта реализации сценария выпуска сертификата ЭП:
- Процесс выпуска инициирует Подписант сам на себя
- Процесс выпуска на Подписанта инициирует ЕИО
Для реализации интеграции со Sber API группы компаний (холдинга) используется следующий механизм:
- Банк для головной компании формирует ссылку авторизации СберБизнес ID
- Ссылка авторизации используется Пользователями головной и дочерних компаний для получения токенов доступа (access_token) и обновления (refresh_token)
- Для каждой компании в группе требуется получить собственную пару токенов доступа и обновления.
Для получения информации о всех сертификатах ЭЦП по компании требуется использовать ресурс /fintech/api/v1/crypto/eio и токен доступа (access_token) Пользователя с признаком ЕИО (обычно это признак имеет генеральный директор компании). Для получения информации о всех сертификатах ЭЦП дочерней компании в запросе должен использоваться токен доступа ЕИО дочерней компании.
Для использования механизма выпуска сертификата ЭП в холдингах рекомендуем использовать сценарий "Инициатор - ЕИО".
- Инициатор - Подписант
- Инициатор - ЕИО
Для реализации сценария используются ресурсы /fintech/api/v1/crypto...:
- Работают только с access_token пользователей-сотрудников вашей компании
- Позволяют получать информацию только по криптопрофилю владельца access_token
- Позволяют создавать запросы на выпуск сертификатов только на владельца access_token
Usecase
Шаги
- Получить access_token
- Создать закрытый ключ + запрос на выпуск открытого ключа
- Отправить запрос на выпуск сертификата
- Получить готовое заявление на выпуск сертификата
- Передать заявление в Банк
- Получить статус заявления
- Скачать и активировать сертификат
Участники usecase
- Подписант - пользователь СберБизнес, сотрудник вашей организации, имеющий право на подписание документов от лица компании
- Платформа - любой web-ресурс или АС, которую вы используете для организации процесса оформления сертификата ЭП
- СКЗИ - используемое вашей компанией средство криптографической защиты информации
- Sber API - представляет из себя ресурсы Sber API, к которым обращается Платформа
- Банк - офис Сбербанка, через который в offline взаимодействует ваша организация
Предусловия
- Подписан имеет профиль в СберБизнес
- Профиль подписанта имеет право подписи
- В профиле СберБизнес Подписанта установлен тип защиты «электронный ключ» (токен)
- Подписан находится на Платформе
Постусловия
- На подписанта выпущен сертификат ЭП
- Сертификат ЭП готов к созданию ЭП
- При возникновении ошибок
CHECKERRORилиREQUISITEERRORдля консультации можно отправить письмо в техническую поддержку [supportdbo2@sberbank.ru] (mailto:supportdbo2@sberbank.ru)
В письмо вложите файл запроса на выпуск сертификата и его данные, которые отправляли в Банк на шаге 11. - При тестировании сценария на тестовом стенде (ИФТ) на шаге 18 вместо похода в отделение Сбербанка необходимо отправить письмо в техническую поддержку [supportdbo2@sberbank.ru] (mailto:supportdbo2@sberbank.ru)
В письмо вложите файл запроса на выпуск сертификата и его данные, которые отправляли в Банк на шаге 11. После ответа технической поддержки можно перейти к шагу 19.
Используемые ресурсы
| № | Метод | Точка вызова | Описание | Операция в scope | Шаг в схеме |
|---|---|---|---|---|---|
| 1 |  | /ic/sso/api/v2/oauth/authorize | Получение кода авторизации | openid | 1. Получить access_token |
| 2 |  | /ic/sso/api/v2/oauth/token | Получение токена доступа | openid | 1. Получить access_token |
| 3 | | /ic/sso/api/v2/oauth/user-info | Получение информации | openid | 1. Получить access_token |
| 4 | | /fintech/api/v1/crypto | Получение информации по сертификатам | GET_CRYPTO_INFO | 2. Создать закрытый ключ + запрос на выпуск открытого ключа и 7. Скачать и активировать сертификат |
| 5 | | /fintech/api/v1/crypto/cert-requests | Создание запроса на выпуск сертификата | CERTIFICATE_REQUEST | 3. Отправить запрос на выпуск сертификата |
| 6 | | /fintech/api/v1/crypto/cert-requests/{externalId}/state | Получение статуса заявления | CERTIFICATE_REQUEST | 4. Получить готовое заявление на выпуск сертификата и 6. Получить статус заявления |
| 7 | | /fintech/api/v1/crypto/cert-requests/{externalId}/print | Получение печатной формы заявления | CERTIFICATE_REQUEST | 4. Получить готовое заявление на выпуск сертификата |
| 8 | | /fintech/api/v1/crypto/cert-requests/{externalId}/activate | Активация выпущенного сертификата | CERTIFICATE_REQUEST | 7. Скачать и активировать сертификат |
Для реализации сценария используются ресурсы /fintech/api/v1/crypto.../eio:
- Работают с access_token пользователей, которые имеют признак единоличного исполнительного органа (ЕИО)
- Позволяют получать информацию по криптопрофилю всех сотрудников компании
- Позволяют создавать запросы на выпуск сертификатов на любых сотрудников компании, к которой относится ЕИО
Usecase
Шаги
- Получить access_token
- Создать закрытый ключ + запрос на выпуск открытого ключа
- Отправить запрос на выпуск сертификата
- Получить готовое заявление на выпуск сертификата
- Передать заявление в Банк
- Получить статус заявления
- Скачать и активировать сертификат
Участники usecase
- ЕИО - единоличный исполнительный орган вашей организации
- Подписант - пользователь СберБизнес, сотрудник вашей организации, имеющий право на подписание документов от лица компании
- Платформа - любой web-ресурс или АС, которую вы используете для организации процесса оформления сертификата ЭП
- СКЗИ - используемое вашей компанией средство криптографической защиты информации
- Sber API - представляет из себя ресурсы Sber API, к которым обращается Платформа
- Банк - офис Сбербанка, через который в offline взаимодействует ваша организация
Предусловия
- Подписан имеет профиль в СберБизнес
- Профиль подписанта имеет право подписи
- В профиле СберБизнес Подписанта установлен тип защиты «электронный ключ» (токен)
- ЕИО находится на Платформе
Постусловия
- На подписанта выпущен сертификат ЭП
- Сертификат ЭП готов к созданию ЭП
- При возникновении ошибок
CHECKERRORилиREQUISITEERRORдля консультации можно отправить письмо в техническую поддержку [supportdbo2@sberbank.ru] (mailto:supportdbo2@sberbank.ru)
В письмо вложите файл запроса на выпуск сертификата и его данные, которые отправляли в Банк на шаге 11. - При тестировании сценария на тестовом стенде (ИФТ) на шаге 18 вместо похода в отделение Сбербанка необходимо отправить письмо в техническую поддержку [supportdbo2@sberbank.ru] (mailto:supportdbo2@sberbank.ru)
В письмо вложите файл запроса на выпуск сертификата и его данные, которые отправляли в Банк на шаге 11. После ответа технической поддержки можно перейти к шагу 19.
| № | Метод | Точка вызова | Описание | Операция в scope | Шаг в схеме |
|---|---|---|---|---|---|
| 1 | | /ic/sso/api/v2/oauth/authorize | Получение кода авторизации | openid | 1. Получить access_token |
| 2 | | /ic/sso/api/v2/oauth/token | Получение токена доступа | openid | 1. Получить access_token |
| 3 | | /ic/sso/api/v2/oauth/user-info | Получение информации | openid | 1. Получить access_token |
| 4 | | /fintech/api/v1/crypto/eio | Получение информации по сертификатам ЕИО | GET_CRYPTO_INFO | 2. Создать закрытый ключ + запрос на выпуск открытого ключа и 7. Скачать и активировать сертификат |
| 5 | | /fintech/api/v1/crypto/cert-requests/eio | Создание запроса на выпуск сертификата ЕИО | CERTIFICATE_REQUEST | 3. Отправить запрос на выпуск сертификата |
| 6 | | /fintech/api/v1/crypto/cert-requests/eio/{externalId}/state | Получение статуса заявления ЕИО | CERTIFICATE_REQUEST | 4. Получить готовое заявление на выпуск сертификата и 6. Получить статус заявления |
| 7 | | /fintech/api/v1/crypto/cert-requests/eio/{externalId}/print | Получение печатной формы заявления ЕИО | CERTIFICATE_REQUEST | 4. Получить готовое заявление на выпуск сертификата |
| 8 | | /fintech/api/v1/crypto/cert-requests/eio/{externalId}/activate | Активация выпущенного сертификата ЕИО | CERTIFICATE_REQUEST | 7. Скачать и активировать сертификат |
Реквизиты запроса на сертификат
1. Cведения о владельце сертификата
| OID | Наименование | Формат |
|---|---|---|
| 2.5.4.3 | ФИО Обозначение: CN | UTF-8 STRING ОБЯЗАТЕЛЬНОЕ ПОЛЕ Макс. длина - 128 Общее имя. Каждое слово в тексте должно быть отделено 1 пробелом. Если в фамилии, имени или отчестве в написании присутствует «дефис», то в запрос так и вносится с дефисом, без пробелов (например: Салтыков-Щедрин). Если фамилия, имя или отчество состоит из нескольких слов разделенных пробелом, то в запрос вносится одним словом, части которого соединены «подчеркиванием» без пробелов (например: фамилия «Ван чо» будет записана Ван_чо). Необходимо удалять пробелы (в случае их наличия) в начале и в конце текста, а также все символы, которые не указаны в файле Набор разрешенных символов в сертификате ЭП.xlsx Например: «Иванов Иван Иванович» |
| 2.5.4.6 | Страна Обозначение: C | PRINTABLE STRING Макс. длина - 2 ОБЯЗАТЕЛЬНОЕ ПОЛЕ Необходимо удалять пробелы (в случае их наличия) в начале и в конце текста, а также все символы, которые не указаны в файле Набор разрешенных символов в сертификате ЭП.xlsx Должен записываться только двухбуквенный код выбранной страны из справочника стран. Например, для «Российской федерации» - “RU” |
| 2.5.4.10 | Организация Обозначение: O | UTF-8 STRING Макс. длина - 64 ОБЯЗАТЕЛЬНОЕ ПОЛЕ Полное или сокращенное название организации, наименование юридического лица. Необходимо удалять пробелы (в случае их наличия) в начале и в конце текста, а также все символы, которые не указаны в файле Набор разрешенных символов в сертификате ЭП.xlsx Например: «ООО «Клиент»» |
| 2.5.4.11 | Подразделение Обозначение: OU | UTF-8 STRING Макс. длина - 64 ОБЯЗАТЕЛЬНОЕ ПОЛЕ Наименование подразделения.Указываются данные подразделения уполномоченного представителя юридического лица. Необходимо удалять пробелы (в случае их наличия) в начале и в конце текста, а также все символы, которые не указаны в файле Набор разрешенных символов в сертификате ЭП.xlsx Если длина ИНН = 12 знакам ИЛИ поле «Подразделение» не заполнено, то oid не добавляется в запрос. Например: «Бухгалтерия» |
| 2.5.4.12 | Должность Обозначение: T | UTF-8 STRING Макс. длина - 64 Должность. Указываются данные уполномоченного представителя юридического лица. Необходимо удалять пробелы (в случае их наличия) в начале и в конце текста, а также все символы, которые не указаны в файле Набор разрешенных символов в сертификате ЭП.xlsx Если длина ИНН = 12 знакам, то oid не добавляется в запрос. Например: «Главный бухгалтер» |
| 1.2.840.113549.1.9.1 | Адрес электронной почты Обозначение: E | IA5STRING Макс. длина - 64 Необязательное поле. Адрес электронной почты. Необходимо удалять пробелы (в случае их наличия) в начале и в конце текста, а также все символы, которые не указаны в файле Набор разрешенных символов в сертификате ЭП.xlsx Значение, которое записывается в атрибут “E” должно загружаться из поля «Адрес электронной почты» экранной формы. |
2. Параметры по ГОСТ Р 34.10-2012
| OID | Наименование | Формат |
|---|---|---|
| 1.2.643.7.1.1.1.1 | Алгоритм подписи | Алгоритм подписи по ГОСТ Р 34.10-2012 с ключом 256 id-tc26-gost3410-12-256 |
| 1.2.643.2.2.35.2 | Параметры эллиптической кривой для алгоритма | Параметры ГОСТ Р 34.10-2001 256 бит, вариант B id-GostR3410-2001-CryptoPro-B-ParamSet |
| 1.2.643.7.1.1.2.2 | Параметры алгоритма хэширования | Алгоритм хэширования по ГОСТ Р 34.11-12 с длиной хэш-кода 256 id-tc26-gost3411-12-256 |
| 1.2.643.2.2.31.1 | Параметры алгоритма шифрования | Алгоритм шифрования по ГОСТ 28147-89 ГОСТ 28147-89 |
| 1.2.643.7.1.1.3.2 | Алгоритм подписи и хэширования (Это подпись запроса) | Алгоритм подписи ГОСТ Р 34.10-2012 с 256 с хэшированием по ГОСТ Р 34.11-2012 id-tc26-signwithdigest-gost3410-12-256 |
3. Расширения (Extension)
| OID | Наименование | Формат |
|---|---|---|
| 1.2.643.3.123.3.1 | Идентификатор Бикрипт | OCTET STRING внутри него UTF-8 STRING с ID Бикрипт ОБЯЗАТЕЛЬНОЕ ПОЛЕ Макс. длина - 32 Необходимо удалять пробелы (в случае их наличия) в начале и в конце текста, а также все символы, которые не указаны в файле Набор разрешенных символов в сертификате ЭП.xlsx Подробнее о формировании идентификатора рассказали ниже |
| 2.5.29.15 | Использование ключа | OCTET STRING содержащий BITSTRING ОБЯЗАТЕЛЬНОЕ ПОЛЕ Должно содержать следующие компоненты: Цифровая подпись, неотрекаемость, шифрование ключей, шифрование данных. |
| 2.5.29.19 | Базовые ограничения | OCTET STRING содержащий базовые ограничения ОБЯЗАТЕЛЬНОЕ ПОЛЕ Битовое поле «CA» ложно, ограничения длинны цепочки сертификатов – 0. |
| 1.2.643.3.123.3.4 | Parent AS | OCTET STRING содержащий OID бизнес-системы ОБЯЗАТЕЛЬНОЕ ПОЛЕ Заполнять значением 1.2.643.3.123.5.24 |
Формирование BicryptId
Для составления запроса на выпуск нового сертификата ЭП необходимо сгенерировать уникальный идентификатор сертификата ЭП - Bicrypt ID.
Bicrypt ID состоит из:
| 1 | 2 | 3 | 4 |
|---|---|---|---|
| КУЦ | Порядковый номер для генерации сертификата | Тип ключа | Фамилия и инициалы владельца сертификата |
значение атрибута certCenterCode из ответа методов /v1/crypto или /v1/crypto/eio | значение атрибута certCenterNum +1 из ответа методов /v1/crypto или /v1/crypto/eio | Всегда используем значение "s" | ФамилияИО (кириллицей без пробелов) |
- Длина КУЦ может быть 4 или 6 символов
- При каждом формировании идентификатора требуется выполнять инкрементацию значения атрибута certCenterNum (добавлять +1 к текущему полученному значению)
- Порядковый номер для генерации сертификата должен соответствовать ряду: «01,02,..09,10,11..99,0A,0B..0Z,1A..1Z…9Z,A0,A1…A9,AA,AB..AZ…Z0,Z1..Z9,ZA..ZZ»
- Если длина КУЦ 6 символов, то Порядковый номер необходим длиной 2 символа. Берем его без изменений из ответа методов
/v1/cryptoили/v1/crypto/eio - Если длина КУЦ 4 символа, то Порядковый номер необходим длиной 4 символа. Берем из ответа методов
/v1/cryptoили/v1/crypto/eioи добавляем 00 в его начало, чтобы сделать 4 символьным
Общая длина Bicrypt ID = 9 символов + Фамилия и инициалы владельца сертификата.
certCenterCode + (certCenterNum +1) + s + ФамилияИО
Примеры
| Если КУЦ 6 символьный | Если КУЦ 4 символьный |
|---|---|
При выполнении запроса /v1/crypto или /v1/crypto/eio:- В параметре certCenterCode получили значение A0001P - В параметре certCenterNum получили значение 08 - увеличиваем его на +1 Фамилия Имя Отчество пользователя, на которого создаем запрос на выпуск нового сертификата ЭП: Иванов Иван Иванович Итоговое значение BicryptId: A0001P09sИвановИИ | При выполнении запроса /v1/crypto или /v1/crypto/eio:- В параметре certCenterCode получили значение A01P - В параметре certCenterNum получили значение 08 - увеличиваем его на +1 и добавляем слева к нему 00 Фамилия Имя Отчество пользователя, на которого создаем запрос на выпуск нового сертификата ЭП: Иванов Иван Иванович Итоговое значение BicryptId: A01P0009sИвановИИ |
Набор разрешенных символов для текстов в КСКП ЭП
См. в файле Набор разрешенных символов в сертификате ЭП.xlsx.
Подпишите документ и отправьте в Банк
Для создания ЭП к документу потребуется инструмент для подписания - средство криптографической защиты информации (СКЗИ).
СКЗИ вы выбираете самостоятельно исходя из ваших задач и потребностей. Вероятнее всего вы его выбрали на предыдущем шаге. При этом бывает такое, что СКЗИ комбинируют - для формирования запроса используют один инструмент, а для создания ЭП (подписания) - другой.
Процесс подписания и отправки
Шаги
- Получить access_token
- Сформировать дайджест документа
- Создать открепленную ЭП
- Закодировать ЭП
- Вызвать метод API
Usecase
Участники usecase
- Платформа - любой web-ресурс или АС, которую вы используете для организации процесса отправки запросов Sber API
- СКЗИ - используемое вашей компанией средство криптографической защиты информации
- Sber API - представляет из себя ресурсы Sber API, к которым обращается Платформа
Предусловия
- Платформа имеет сертификат ЭП на подписанта(-ов)
- Сработал триггер, запускающий процесс подписания и отправки запроса API
- Платформа получила/собрала все необходимые атрибуты для создания и оправки запроса API
Постусловия
- В Банк передан подписанный ЭП документ
Требования к дайджесту
Digest (дайджест) – набор значимых полей платежного документа, который подписывается электронной подписью (ЭП).
- Необходимо использовать кодировку UTF-8;
- Поля дайджеста должны быть отсортированы по алфавиту (от A до Z);
- Значения сумм и комиссий должны задаваться с точностью 2 знака после точки;
- Значения сумм и комиссий в дайджесте и в запросе должны быть идентичны;
- Если какое-то поле не заполняется, его не требуется добавлять в дайджест;
- Разделитель строк должен быть в формате unix (одиночный \n);
- Последняя строка дайджеста не должна содержать перевод строки;
- Перевод строк должен быть экранирован как \n;
- При заполнении полей с данными компании (название компании, например) используйте значения, полученные от Банка в рамках запросов API (в том числе с сохранением регистра).
Передача ЭП в запросе API
Передача электронной подписи (ЭП) осуществляется с использованием массива digestSignatures, где каждый элемент представляет собой подпись (Signature). Каждая подпись должна содержать следующие обязательные поля:
| Наименование поля | Описание поля | Пример |
|---|---|---|
| base64Encoded (string) | Значение ЭП документа | HlaeIHXXEcGT1bFxo1NlpAzpr+kJ2IQrcxVdvDTep6xjsmD1FDb+6NIyLT+/T24S0mPfVCU75sieOMt71TBS7w== |
| certificateUuid (string) | Идентификатор сертификата, использованного при создании ЭП (можно узнать, обратившись к ресурсу /v1/crypto или /v1/crypto/eio) | 22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6 |
В документе можно передать одну или две электронных подписи вместе с реквизитами создаваемого документа.
- Если подписи переданы через API, то они сохраняются вместе с документом, а сам документ продолжает свой жизненный цикл.
- Если подписи не были переданы, то документ сохраняется в начальном статусе и ожидает дальнейшей подписи в интерфейсе СберБизнес.
Документ может быть подписан следующими наборами подписей:
- одна (единственная) подпись;
- первая и вторая подписи.
При отправке единственной подписи с первой или второй подписью, обработка будет происходить как будто отправлена единственная подпись. Порядок наложения подписи не имеет значения при наложении первой и второй подписей. Состав полей дайджеста не изменяется. Тип подписи указывается в настройках криптопрофиля при создании пользователя в СберБизнес.
Требования к ЭП
Банк принимает и обрабатывает ЭП, которая соответствует требованиям:
- Подпись CaDES-BES в формате PEM;
- Подпись открепленная — detatched;
- Алгоритм цифровой подписи ГОСТ Р 34.10-2012 для ключей длины 256 бит;
- Блок с сертификатами (Certificates) обязателен — включает сертификат подписанта;
- Данные подписанта (Signer Info) — содержит информацию только по одному подписанту;
- Присутствует время формирования подписи (Signing Time).
Проверить сформированную подпись можно на странице Удостоверяющего центра:
- Выберете раздел «Проверка электронной подписи»
- Выберете тип электронной подписи - Отсоединенная (электронная подпись содержится в отдельном файле)