Подписание документов ЭЦП

Для того, чтобы воспользоваться услугами подписания документов ЭЦП системы Aitu Passport необходимо чтобы Партнер:

• был зарегистрирован в соответствующем окружении Aitu Passport (на тестовой площадке, на продакшн площадке)

• создал свой сервис в соответствующем окружении Aitu Passport

• подключил к своему сервису сервис/сервисы (scope) подписания документов (подробнее о scope см., тут):

  • "sign" - подписание резидентом документов ОЭЦП физического лица (ФЛ)

  • "non_resident_sign" - подписание не резидентов документов ОЭЦП ФЛ

  • "ul_sign" - подписание документов ОЭЦП юридического лица

Услуги по подписанию документов резидентами РК (sign) и нерезидентами РК (non_resident_sign) являются несовместимыми в рамках одного сервиса. В случае если в проекте Партнера предусмотрено подписание документов как резидентами, так и нерезидентами необходимо создать 2 сервиса (один для подписания документов резидентами РК, второй для подписания документов нерезидентами РК). Информацию о создании сервиса см. тут

В Aitu Passport реализовано несколько вариантов работы с облачной ЭЦП:

1. Подписание любых файлов и получение результата в формате PKCS7.

2. Подписание PDF файлов (встраивание подписи прямо в PDF файл).

3. Подписание XML файлов, получение результата в формате XMLDSIG (встраивание подписи и сертификата пользователя прямо в XML файл).

Объем одного файла, передаваемого на подпись, не должен превышать 40 MB

Выбор варианта подписания

Отличаются только методы по загрузке документов для подписания и получения/проверки. Процесс для пользователя одинаков вне зависимости от формата.

PKCS7

В большинстве случаев, если необходимо просто подписать документ и провалидировать подпись нужно использовать вариант с PKCS7.

Вы можете подписывать любой массив байт: любые документы, hash документов, произвольные наборы байт и т.д., в том числе pdf и xml файлы. Массив байт должен быть передан в кодировке base64.

Результирующая подпись будет в формате PKCS7. Контейнер PKCS7 содержит в себе всю цепочку сертификатов от пользовательского до КУЦ, TSP метку, OCSP метку, подпись документа.

Контейнер PKCS7, полученный от Aitu Passport, не содержит исходный подписываемый документ.

PDF

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

Так как в облачной ЭЦП Aitu Passport используются ГОСТ алгоритмы подписи, то стандартные PDF-ридеры не смогут корректно отобразить подпись. Для корректного отображения подписи в варианте PDF Партнеру необходимо самостоятельно написать плагин к нужному PDF-ридеру.

Если у вас нет необходимости встраивать подпись непосредственно в исходный файл, то проще использовать PKCS7 формат вместо PDF, даже для PDF файлов.

XMLDSIG

Данный вариант можно использовать только для подписания xml файлов. В случае, если необходимо подписывать xml файлы и валидировать результаты, например, в НУЦ РК - используйте XMLDSIG вариант.

Вы можете подписывать xml документы и получать результат в специально предназначенном для этого формате (результат будет в формате xmldsig). Результат подписи и сертификат пользователя вставляются непосредственно в исходный файл.

Если у вас нет необходимости встраивать подпись непосредственно в исходный файл, то проще использовать PKCS7 формат вместо XMLDSIG, даже для xml файлов.

Проверка документов, подписанных через XMLDSIGN, на стороне Aitu Passport не производится, и должна быть реализована Партнером самостоятельно.

Схема процесса подписания документа ЭЦП

Описание процесса подписания документа ЭЦП

Aitu Passport позволяет осуществлять подписание документов ЭЦП для физических лиц (ЭЦП ФЛ) и ЭЦП для юридических лиц (ЭЦП ЮЛ). Так же доступно множественное подписание документов ЭЦП различными лицами.

Подготовительный этап для подписания документов ЭЦП ЮЛ

Прежде чем инициировать процесс подписания документов ЭЦП ЮЛ информационная система партнера должна передать в Aitu Passport следующие данные:

1. Список сотрудников юридического лица, имеющих право подписи документов от имени данного юридического лица. Данные передаются в методе /api/v1/uls

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

Подписание документа ЭЦП (ЮЛ или ФЛ)

1. При переходе Пользователя в приложении Партнера к этапу подписания документов ЭЦП, приложение Партнера, до того как начнется процесс подписания, должно загрузить в 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 на схеме

1. После того, как Пользователь в приложении Партнера нажмет на кнопку или ссылку подписи документа (стрелка 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;

  • registrationCertificate - регистрационное свидетельство в виде строки base64. Для метода api/v2/oauth/non-residents/signatures/pdf не передается;
  • documentCopy - оригинал документа, который был отправлен на подпись в формате pdf, с интегрированным QR-кодом для проверки ЭЦП (для метода api/v2/oauth/non-residents/signatures/pdf не передается). QR-код размешается в нижнем колонтитуле на каждой странице документа.

QR-код для проверки ЭЦП и данные лиц, подписавших документ

• Если выбран XMLDSIG, то вызывается метод api/v2/oauth/signatures/xml (в сервисе Партнера для подписи документов резидентами) или метод api/v2/oauth/non-residents/signatures/xml (в сервисе Партнера для подписи документов не резидентами). В ответе метода передаются следующие данные:

  • signableId - идентификатор документа, присвоенный системой Aitu Passport;

  • name - имя документа, переданного сервисом Партнера в систему Aitu Passport;

  • signedXml - подписанный документ, в формате xml

Множественное подписание документа ЭЦП

Множественное подписание документа ЭЦП в формате PKCS7

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

1. ИС Партнера загружает не подписанный документ используя метод api/v2/oauth/signable и получает signableId (старт процесса первого подписания)
2. После получения signableId от метода api/v2/oauth/signable, ИС Партнера инициирует процесс подписания документа, Пользователь подписывает документ (процесс описан в разделе Подписание документа ЭЦП (ЮЛ или ФЛ)
3. После первого подписания документа, ИС Партнера вызывает метод api/v2/oauth/signatures для получения данных подписанного документа и сохраняет эти данные.
4. В случае если документ должен быть подписан вторым лицом, то ИС партнера должно загрузить уже подписанный ранее документ в Aitu Passport, чтобы получить signableId, для старта процесса подписания. Для получения signableId для второго и последующего подписания документа должен использоваться метод /api/v2/oauth/signable-with-signature. В запросе данного метода передаются следующие параметры:

   • bytes - оригинальный документ (документ без подписей)

   • name - имя документа. Данное имя будет отображаться пользователю в процессе подписания

   • link - ссылка на документ (текст документа)

   • signature - документ подписанный ЭЦП первым (предыдущим) лицом

5. После получения signableId от метода /api/v2/oauth/signable-with-signature, ИС Партнера инициирует процесс подписания документа, Пользователь подписывает документ (процесс описан в разделе Подписание документа ЭЦП (ЮЛ или ФЛ)
6. После подписания документа, ИС Партнера вызывает метод api/v2/oauth/signatures для получения данных подписанного документа и сохраняет эти данные.
7. В случае если необходимо подписать документ третьим и последующими лицами ИС партнера запускает процесс описанный в п.п. 4 - 6 настоящего раздела

Множественное подписание документа ЭЦП в формате PDF

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

1. ИС Партнера загружает не подписанный документ используя метод api/v2/oauth/signable/pdf и получает signableId (старт процесса первого подписания)
2. После получения signableId от метода api/v2/oauth/signable/pdf , ИС Партнера инициирует процесс подписания документа, Пользователь подписывает документ (процесс описан в разделе Подписание документа ЭЦП (ЮЛ или ФЛ)
3. После подписания документа, ИС Партнера вызывает метод api/v2/oauth/signatures/pdf для получения данных подписанного документа и сохраняет эти данные.
4. В случае если документ должен быть подписан вторым и последующим лицом, то ИС партнера должно загрузить уже подписанный ранее документ в Aitu Passport, чтобы получить signableId. Для получения signableId для второго и последующего подписания документа должен вызываться тот же метод - api/v2/oauth/signatures/pdf со следующими параметрами:

   • bytes - документ, подписанный ЭЦП первым (предыдущим) лицом.

   • name - имя документа. Данное имя будет отображаться пользователю в процессе подписания

   • link - ссылка на документ (текст документа)

5. Дальнейшие действия идентичны описанным в п.п 2-4 настоящего раздела

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

• Если документ подписан ЭЦП физического лица, то рядом с QR-кодом отображаются:

  • для резидентов: ИИН и дата подписания;

  • для нерезидентов: номер документа, страна выдавшая документ и дата подписания.

Документ подписан ЭЦП физического лица - резидентами

Документ подписан ЭЦП физического лица - нерезидентами

• Если документ подписан ЭЦП юридического лица, то рядом с QR-кодом отображаются:

  • для резидентов: ИИН физического лица, подписавшего документ от имени организации, БИН и наименование организации, дата подписания;

  • для нерезидентов: номер документа и страна выдавшая документ физическому лицу, подписавшего документ от имени организации, БИН и наименование организации, дата подписания.

Документ подписан ЭЦП юридического лица - резидентами и нерезидентами

Сроки действия объектов

Внимание:

• Период хранения не подписанных документов, переданных на подписание (signableId) 24 часа с момента генерации signableId;

• Параметр otp_confirmation действителен в течение 60 минут с момента генерации;

• Код авторизации (code) действителен в течение 5 минут с момента генерации;

• Токен авторизации (access_token ) действителен в течение 30 дней с момента генерации;

• Токен пользователя на устройстве действителен 1 год с момента генерации.

Проверка валидности подписи

Проверка валидности ЭЦП осуществляться разными методами Aitu Passport. Метод проверки валидности ЭЦП зависит от того, какой вариант подписания документа был выбран (PKCS7 или PDF)

Проверка валидности ЭЦП в формате XMLDSIGN, на стороне Aitu Passport не производится, и должна быть реализована Партнером самостоятельно либо возможна проверка через ШЭП.

Проверка валидности ЭЦП, полученной от Aitu Passport в формате PKCS7

Проверку ЭЦП, полученной от AituPassport, в формате PKCS7 можно выполнить следующими способами:

• через API Aitu Passport вызвав метод:

  • api/v2/oauth/signatures/verify - для сервиса через который подписывают документы резиденты,
  • api/v2/oauth/non-residents/signatures/verify - для сервиса через который подписывают документы не резиденты,
• самостоятельно. Вы можете обратиться к представителям сервиса Aitu Passport за примерами кода на языке Java/Kotlin,

• при помощи метода сервиса проверки ЭЦП, развернутого на стороне Партнера - см. статью Сервис проверки ЭЦП.
• через ШЭП - https://sb.egov.kz/smart-bridge/services/passport/ORGC2-S-5737

Проверка валидности ЭЦП, полученной от Aitu Passport в формате PDF

Проверку ЭЦП, полученной от Aitu Passport, в формате PDF можно выполнить следующими способами:

• через API Aitu Passport вызвав метод:

  • api/v2/oauth/signatures/pdf/verify - для сервиса через который подписывают документы резиденты,
  • api/v2/oauth/non-residents/signatures/pdf/verify - для сервиса через который подписывают документы не резиденты,
• при помощи метода сервиса проверки ЭЦП, развернутого на стороне Партнера - см. статью Сервис проверки ЭЦП.
• через ШЭП - https://sb.egov.kz/smart-bridge/services/passport/ORGC2-S-5738

Проверка валидности ЭЦП, полученной от Aitu Passport в формате XML

• через API Aitu Passport вызвав метод api/v2/oauth/signatures/xml/verify
• через ШЭП - https://sb.egov.kz/smart-bridge/services/passport/ORGC2-S-5828