Подписание документов ЭЦП
Услуги по подписанию документов резидентами РК (sign) и нерезидентами РК (non_resident_sign) являются несовместимыми в рамках одного сервиса. В случае если в проекте Партнера предусмотрено подписание документов как резидентами, так и нерезидентами необходимо создать 2 сервиса (один для подписания документов резидентами РК, второй для подписания документов нерезидентами РК). Информацию о создании сервиса см. тут
В Aitu Passport реализовано несколько вариантов работы с облачной ЭЦП:
Подписание любых файлов и получение результата в формате PKCS7.
Подписание PDF файлов (встраивание подписи прямо в PDF файл).
Подписание XML файлов, получение результата в формате XMLDSIG (встраивание подписи и сертификата пользователя прямо в XML файл).
Объем одного файла, передаваемого на подпись, не должен превышать 40 MB
Выбор варианта подписания
PKCS7
В большинстве случаев, если необходимо просто подписать документ и провалидировать подпись нужно использовать вариант с PKCS7.
Вы можете подписывать любой массив байт: любые документы, hash документов, произвольные наборы байт и т.д., в том числе pdf и xml файлы. Массив байт должен быть передан в кодировке base64.
Результирующая подпись будет в формате PKCS7. Контейнер PKCS7 содержит в себе всю цепочку сертификатов от пользовательского до КУЦ, TSP метку, OCSP метку, подпись документа.
PDF
Вы сможете подписывать pdf документы и получать результат в специально предназначенном для этого формате, просматривать подпись в PDF-ридерах (подпись будет вставлена непосредственно в исходный файл).
XMLDSIG
Данный вариант можно использовать только для подписания xml файлов. В случае, если необходимо подписывать xml файлы и валидировать результаты, например, в НУЦ РК - используйте XMLDSIG вариант.
Вы можете подписывать xml документы и получать результат в специально предназначенном для этого формате (результат будет в формате xmldsig). Результат подписи и сертификат пользователя вставляются непосредственно в исходный файл.
Схема процесса подписания документа ЭЦП
Описание процесса подписания документа ЭЦП
Aitu Passport позволяет осуществлять подписание документов ЭЦП для физических лиц (ЭЦП ФЛ) и ЭЦП для юридических лиц (ЭЦП ЮЛ). Так же доступно множественное подписание документов ЭЦП различными лицами.
Подготовительный этап для подписания документов ЭЦП ЮЛ
Прежде чем инициировать процесс подписания документов ЭЦП ЮЛ информационная система партнера должна передать в Aitu Passport следующие данные:
Список сотрудников юридического лица, имеющих право подписи документов от имени данного юридического лица. Данные передаются в методе /api/v1/uls
Правом и обязанностью Партнера является своевременная передача в Aitu Passport актуального списка сотрудников, имеющих право подписи документов от имени юридического лица. В случае, если список сотрудников, имеющих право подписи, меняется (добавление/удаление сотрудника) информационная система Партнера должна передать новый список всех сотрудников, имеющих право подписи в Aitu Passport.
Подписание документа ЭЦП (ЮЛ или ФЛ)
При переходе Пользователя в приложении Партнера к этапу подписания документов ЭЦП, приложение Партнера, до того как начнется процесс подписания, должно загрузить в Aitu Passport документ или документы которые должен подписать Пользователь. Предварительная загрузка применяется для того, чтобы приложение Партнера могло получить signableId. signableId - это уникальный идентификатор документа, присвоенный Aitu Passport, используется в ссылке-запросе авторизации (см. п.2 настоящего раздела) и в методах получения данных о подписании документа (-ов). В зависимости от выбранного варианта подписания (информацию о вариантах подписания см., в разделе "Выбор варианта подписания") используется один из следующих методов загрузки документов.
Для ФЛ :
Если выбран вариант PKCS7, то для загрузки документа используется метод api/v2/oauth/signable
Если выбран вариант PDF, то для загрузки документа используется метод api/v2/oauth/signable/pdf
Если выбран вариант XMLDSIG, то для загрузки документа используется метод api/v2/oauth/signable/xml
Для ЮЛ :
Если выбран вариант PKCS7, то для загрузки документа используется метод api/v3/oauth/signable
Если выбран вариант PDF, то для загрузки документа используется метод api/v3/oauth/signable/pdf
Если выбран вариант XMLDSIG, то для загрузки документа используется метод api/v3/oauth/signable/xml
В методе загрузки документа, приложение Партнера может передать ссылку на страницу с текстом документа, который должен подписать Пользователь в параметре link. Если ссылка передана (параметр link), то в процессе подписания, на платформе Aitu Passport, Пользователь сможет ознакомиться с текстом документа.
Процесс загрузки документов обозначен стрелками 3 и 4 на схеме
После того, как Пользователь в приложении Партнера нажмет на кнопку или ссылку подписи документа (стрелка 5 на схеме), Приложение партнера формирует ссылку-запрос авторизации (с методом генерации ссылки-запроса авторизации oauth2/auth можно ознакомиться здесь, процесс авторизации детально описан в статье "Авторизация" -> глава "Авторизация в Aitu Passport").
Важные моменты при формировании параметров для ссылки-запроса авторизации в процессе подписания документов ЭЦП:
В случае, если по условиям договора на оказание услуг Aitu Passport, номер мобильного телефона Пользователя:
Партнер верифицирует самостоятельно, то приложение Партнера должно в ссылке-запросе авторизации (oauth2/auth) передать параметр
otp_confirmation. Чтобы получить значение для параметраotp_confirmation, приложение Партнера должно вызвать метод api/v1/trusted-phone. Значение для параметраotp_confirmationпередается в параметреsecretответа метода api/v1/trusted-phone. Внимание!secret, а соответственно и значение в параметреotp_confirmationявляется одноразовым, его необходимо получать для каждого запроса авторизации заново!верифицирует Aitu Passport, то параметр
otp_confirmationв ссылке-запросе на авторизацию (oauth2/auth) не передается, метод api/v1/trusted-phone вызывать не нужно.
Процесс получения значения для параметра
otp_confirmationобозначен стрелками 6 и 7 на схемеВ параметре
scopeобязательно указывается параметр услуги подписания документа: sign или non_resident_sign или ul_sign . Параметр услуги подписания документа должен передаваться следующим образом:sign.1,2,3,где 1, 2 и 3 это signableId, полученные от метода загрузки документа (описание методов загрузки см., п.1 настоящего раздела)
3. После того, как приложением Партнера была сгенерирована ссылка-запрос на авторизацию (стрелка 8 на схеме), происходит редирект Пользователя на принимающую страницу Aitu Passport, где Пользователь проходит процессы авторизации, идентификации в Aitu Passport. Путь пользователя в Aitu Passport определяется параметрами, переданными в ссылке-запросе авторизации. Стрелки 9 - 16 на схеме
Для успешного прохождения этапа биометрической идентификации скорость подключения устройства Пользователя к сети интернет должна быть не менее 100кб/сек
4. Aitu Passport предлагает Пользователю подписать документ, Пользователь подписывает документ ЭЦП (стрелки 17 - 22 на схеме)
5. Aitu Passport генерирует код авторизации и передает его приложению Партнера. Описание данного процесса см. в статье "Авторизация" -> глава "Авторизация в Aitu Passport. Стрелки 23 и 24 на схеме
6. Приложение Партнера (серверная часть приложения) обменивает полученный код авторизации на токены (access_token, id_token). Описание данного процесса см. в статье "Авторизация" -> глава "Авторизация в Aitu Passport. Стрелки 25 и 26 на схеме
Получение документов, подписанных ЭЦП
В зависимости от того, какой вариант подписания документа был выбран, для того чтобы получить подписанный документ, приложение Партнера должно вызвать один из следующих методов:
Если выбран PKCS7, то вызывается метод api/v2/oauth/signatures (в сервисе Партнера который используется для подписи документов резидентами) или метод api/v2/oauth/non-residents/signatures (в сервисе Партнера для подписи документов не резидентами). В ответе метода передаются следующие данные:
signableId - идентификатор документа, присвоенный системой Aitu Passport;
signature - контейнер PKCS7 с данными подписи,
registrationCertificate - регистрационное свидетельство в виде строки base64.
Если выбран PDF, то вызывается метод api/v2/oauth/signatures/pdf (в сервисе Партнера для подписи документов резидентами) или метод api/v2/oauth/non-residents/signatures/pdf (в сервисе Партнера для подписи документов не резидентами). В ответе метода передаются следующие данные:
signableId - идентификатор документа, присвоенный системой Aitu Passport;
name - имя документа, переданного сервисом Партнера в систему Aitu Passport;
signedPdf - подписанный документ, в формате pdf. Передача документа в данном параметре говорит о том, что по данным AituPassport документ подписан. Если вы хотите валидировать подпись документа ОЭЦП, то воспользуйтесь одним из сервисов валидации подписи см. раздел Проверка валидности подписи данной статьи;
registrationCertificate - регистрационное свидетельство в виде строки base64. Для метода api/v2/oauth/non-residents/signatures/pdf не передается;
documentCopy - оригинал документа, который был отправлен на подпись в формате pdf, с интегрированным QR-кодом для проверки ЭЦП (для метода api/v2/oauth/non-residents/signatures/pdf не передается). QR-код размешается в нижнем колонтитуле на каждой странице документа.
Если выбран XMLDSIG, то вызывается метод api/v2/oauth/signatures/xml (в сервисе Партнера для подписи документов резидентами) или метод api/v2/oauth/non-residents/signatures/xml (в сервисе Партнера для подписи документов не резидентами). В ответе метода передаются следующие данные:
signableId - идентификатор документа, присвоенный системой Aitu Passport;
name - имя документа, переданного сервисом Партнера в систему Aitu Passport;
signedXml - подписанный документ, в формате xml
Множественное подписание документа ЭЦП
Множественное подписание документа ЭЦП в формате PKCS7
Процесс подписания ЭЦП документа несколькими лицами в формате PKCS7 выглядит следующим образом:
ИС Партнера загружает не подписанный документ используя метод api/v2/oauth/signable и получает signableId (старт процесса первого подписания)
После получения signableId от метода api/v2/oauth/signable, ИС Партнера инициирует процесс подписания документа, Пользователь подписывает документ (процесс описан в разделе Подписание документа ЭЦП (ЮЛ или ФЛ)
После первого подписания документа, ИС Партнера вызывает метод api/v2/oauth/signatures для получения данных подписанного документа и сохраняет эти данные.
В случае если документ должен быть подписан вторым лицом, то ИС партнера должно загрузить уже подписанный ранее документ в Aitu Passport, чтобы получить signableId, для старта процесса подписания. Для получения signableId для второго и последующего подписания документа должен использоваться метод /api/v2/oauth/signable-with-signature. В запросе данного метода передаются следующие параметры:
bytes - оригинальный документ (документ без подписей)
name - имя документа. Данное имя будет отображаться пользователю в процессе подписания
link - ссылка на документ (текст документа)
signature - документ подписанный ЭЦП первым (предыдущим) лицом
После получения signableId от метода /api/v2/oauth/signable-with-signature, ИС Партнера инициирует процесс подписания документа, Пользователь подписывает документ (процесс описан в разделе Подписание документа ЭЦП (ЮЛ или ФЛ)
После подписания документа, ИС Партнера вызывает метод api/v2/oauth/signatures для получения данных подписанного документа и сохраняет эти данные.
В случае если необходимо подписать документ третьим и последующими лицами ИС партнера запускает процесс описанный в п.п. 4 - 6 настоящего раздела
Множественное подписание документа ЭЦП в формате PDF
Процесс подписания ЭЦП документа несколькими лицами в формате PDF выглядит следующим образом:
ИС Партнера загружает не подписанный документ используя метод api/v2/oauth/signable/pdf и получает signableId (старт процесса первого подписания)
После получения signableId от метода api/v2/oauth/signable/pdf , ИС Партнера инициирует процесс подписания документа, Пользователь подписывает документ (процесс описан в разделе Подписание документа ЭЦП (ЮЛ или ФЛ)
После подписания документа, ИС Партнера вызывает метод api/v2/oauth/signatures/pdf для получения данных подписанного документа и сохраняет эти данные.
В случае если документ должен быть подписан вторым и последующим лицом, то ИС партнера должно загрузить уже подписанный ранее документ в Aitu Passport, чтобы получить signableId. Для получения signableId для второго и последующего подписания документа должен вызываться тот же метод - api/v2/oauth/signatures/pdf со следующими параметрами:
bytes - документ, подписанный ЭЦП первым (предыдущим) лицом.
name - имя документа. Данное имя будет отображаться пользователю в процессе подписания
link - ссылка на документ (текст документа)
Дальнейшие действия идентичны описанным в п.п 2-4 настоящего раздела
Нижний колонтитул документа pdf, подписанного несколькими лицами, выглядит следующим образом:
Если документ подписан ЭЦП физического лица, то рядом с QR-кодом отображаются:
для резидентов: ИИН и дата подписания;
для нерезидентов: номер документа, страна выдавшая документ и дата подписания.
Если документ подписан ЭЦП юридического лица, то рядом с QR-кодом отображаются:
для резидентов: ИИН физического лица, подписавшего документ от имени организации, БИН и наименование организации, дата подписания;
для нерезидентов: номер документа и страна выдавшая документ физическому лицу, подписавшего документ от имени организации, БИН и наименование организации, дата подписания.
Сроки действия объектов
Внимание:
Период хранения не подписанных документов, переданных на подписание (signableId) 24 часа с момента генерации signableId;
Параметр
otp_confirmationдействителен в течение 60 минут с момента генерации;Код авторизации (code) действителен в течение 5 минут с момента генерации;
Токен авторизации (access_token ) действителен в течение 30 дней с момента генерации;
Токен пользователя на устройстве действителен 1 год с момента генерации.
Проверка валидности подписи
Проверка валидности ЭЦП осуществляться разными методами Aitu Passport. Метод проверки валидности ЭЦП зависит от того, какой вариант подписания документа был выбран (PKCS7, PDF или XMLDSIGN)
Проверка валидности ЭЦП, полученной от Aitu Passport в формате PKCS7
Проверку ЭЦП, полученной от AituPassport, в формате PKCS7 можно выполнить следующими способами:
через API Aitu Passport вызвав метод:
api/v2/oauth/signatures/verify - для сервиса через который подписывают документы резиденты,
api/v2/oauth/non-residents/signatures/verify - для сервиса через который подписывают документы не резиденты,
самостоятельно. Вы можете обратиться к представителям сервиса Aitu Passport за примерами кода на языке Java/Kotlin,
при помощи метода сервиса проверки ЭЦП, развернутого на стороне Партнера - см. статью Сервис проверки ЭЦП.
Проверка валидности ЭЦП, полученной от Aitu Passport в формате PDF
Проверку ЭЦП, полученной от Aitu Passport, в формате PDF можно выполнить следующими способами:
через API Aitu Passport вызвав метод:
api/v2/oauth/signatures/pdf/verify - для сервиса через который подписывают документы резиденты,
api/v2/oauth/non-residents/signatures/pdf/verify - для сервиса через который подписывают документы не резиденты,
при помощи метода сервиса проверки ЭЦП, развернутого на стороне Партнера - см. статью Сервис проверки ЭЦП.
Проверка валидности ЭЦП, полученной от Aitu Passport в формате XMLDSIGN
через API Aitu Passport вызвав метод api/v2/oauth/signatures/xml/verify
Last updated
Was this helpful?