POST /api - регистрация нового документа в системеPOST /api/{id}/data - фиксация значений хешей документаGET /api/{id}?lastSignId=X - получение данных о зарегистрированном документеGET /api/{id}/data - получение подписанных данных из архиваPOST /api/{id} - добавление подписи к документуPOST /api/{id}/verify - проверка подписейGET /api/{id}/signature/{signId}?signFormat=X - экспорт одной подписи документаGET /api/{id}/signature/{signId}/qr?signFormat=X&qrVersion=25&qrLevel=M - экспорт подписи в виде набора QR кодовPOST /api/{id}/buildDDC?fileName=X - формирование карточки электронного документаPOST /api/{id}/settings - изменение настроек документаGET /api/{id}/settingsAudit - аудит изменений настроек документаGET /api/{id}/buildFileName?name=XXX - сформировать имя файла с идентификатором SIGEXPOST /api/exported - получение идентификаторов документа и подписи по ранее экспортированной подписи документаPOST /api/parseDDC?registerUnknownSignatures=false - разбор карточки электронного документаPOST /api/auth - аутентификация, подготовительный этап - получение блока случайных данныхPOST /api/auth - аутентификацияPOST /api/auth - сброс аутентификацииGET /api/auth - текущее состояние аутентификацииGET /api/?from=xxx&until=yyy&organization=true - перечисление документов аутентифицированного пользователяGET /api/settings - получить настройки аутентифицированного пользователяPOST /api/settings - сохранить настройки аутентифицированного пользователяGET /api/settingsAudit - аудит изменений настроек пользователяGET /api/organizationSettings - получить настройки организации аутентифицированного пользователяPOST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователяGET /api/organizationSettingsAudit - аудит изменений настроек организацииGET /api/organizationPermissions - получить права аутентифицированного пользователя в разрезе его организацииGET /api/idFromFileName/?name=XXX - получить идентификатор SIGEX из имени файлаGET /api/externalServicesStats - статистика доступности сторонних сервисовGET /api/strings - перечень известных строкGET /api/version - версия сервисаСервис SIGEX предоставляет публичный API по протоколу HTTPS на двух портах:
443 - аутентификация пользователей;10443 - аутентификация информационных систем.Отличия описаны в разделе Аутентификация и контроль доступа.
Статья Аутентификация по цифровым сертификатам описывает процесс интеграции аутентификации в информационные системы.
Кроме тех случаев, когда это явно указано, запросы сервису следует отправлять в формате JSON (с указанием типа содержимого application/json в заголовке Content-Type), сервис должен вернуть HTTP код 200 и ответ в виде JSON строки. Другой код HTTP свидетельствует о серьезной проблеме при обработке запроса, в этом случае нет смысла пробовать анализировать ответ.
Строки в JSON ответах сервиса всегда обрабатываются таким образом, чтобы JSON можно было безопасно встраивать в HTML в тег <script>. Для этого символы '<', '>', '&', U+2028 и U+2029 заменяются на '\u003c', '\u003e', '\u0026', '\u2028' и '\u2029' соответствено. Это не должно вызывать каких-либо неожиданных эффектов, так как по RFC 8259 любые символы в строках могут быть экранированы.
Реестр OID и других спеифических строк доступен на странице Известные строки.
Сервис поддерживает два механизма аутентификации:
Этот способ аутентификации подходит для тех сценариев, когда действия предполагается выполнять от имени конкретных пользователей, к примеру:
Аутентификация пользователей по цифровым сертификатам НУЦ основана на подписании пользователем блока случайных данных (nonce) и последующей проверке этой подписи. В том случае, если подпись верна, сервис может быть уверен в том, что пользователь обладает закрытым ключом соответствующим открытому ключу в сертификате (регистрационном свидетельстве) НУЦ.
За данный режим аутентификации отвечают следующие API:
POST /api/auth - аутентификация, подготовительный этап - получение блока случайных данныхPOST /api/auth - аутентификацияPOST /api/auth - сброс аутентификации - не используется в режиме внешней аутентификацииGET /api/auth - текущее состояние аутентификации - не используется в режиме внешней аутентификацииОтличительной особенностью режима внешней аутентификации является то, что в этом режиме сервис SIGEX не устанавливает в своих ответах cookie с JWT токенами содержащими информацию о пользователе прошедшем аутентификацию. Детали приведены в POST /api/auth - аутентификация.
Вводная статья Аутентификация по цифровым сертификатам описывает процесс интеграции аутентификации в информационные системы в режиме внешней аутентификации.
Этот способ аутентификации подходит для тех сценариев, когда действия должны выполняться не от имени определенных пользователей, а от имени информационной системы, к примеру:
В случае использования этого механизма, с точки зрения SIGEX информационная система будет действовать от имени организации, а не какого-то определенного ее представителя.
Данный механизм аутентификации доступен на отдельном порту https://sigex.kz:10443 и требует предоставления клиентского сертификата https://ru.wikipedia.org/wiki/HTTPS#Идентификация_клиента. Практически все API, доступные на стандартном порту https://sigex.kz, без изменений доступны и тут. Исключение составляют API аутентификации по цифровым сертификатам НУЦ, тут они не работают.
Важный нюанс: реализация данного механизма аутентификации основана на сертификатах только по той причине, что в TLS не предусмотрено аутентификации по открытым ключам, фактически сервис анализирует только открытый ключ содержащийся в сертификате, остальные поля не учитываются.
Для того, чтобы использовать аутентификацию информационных систем двусторонним TLS необходимо:
Поддерживаемые протоколы:
TLS 1.3.Допустимые длины ключей:
RSA не короче 2048 бит;ECDSA не короче 224 бит.Определены следущие типы прав доступа:
Полномочия первого руководителя всегда присутствуют во всех блоках контроля доступа настроек организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя). Таким образом первый руководитель всегда имеет доступ к документам и настройкам организации.
Документ может быть публично доступным, либо с ограниченным доступом, это определяет параметр private в настройках документа (см. POST /api/{id}/settings - изменение настроек документа).
В том случае, если документ является публично доступным (private: false), то доступ к информации о нем может получить любой кто знает идентификатор документа.
В том случае, если доступ к документу ограничен (private: true), то доступ к информации о нем могут получить:
documentsAccess настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя);documentsAccess настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя).Доступ к подписанным данным документа предоставляется аналогично доступу к информации о документе, но с ограничением - он возможен только аутентифицированным пользователям.
В том случае, если документ является публично доступным (private: false), то доступ к подписанным данным может получить любой аутентифицированный пользователь, который знает идентификатор документа. Если же доступ к документу ограничен (private: true), то доступ к подписанным данным имеют те, кто может просматривать информацию о документе.
Просматривать и изменять настройки документа могут:
documentsSettings настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя);documentsSettings настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя).API перечисления документов (GET /api/?from=xxx&until=yyy&organization=true - перечисление документов аутентифицированного пользователя) с помощью параметра organization позволяет указывать какие документы следует перечислять:
Во втором случае следует установить organization=true в запросе.
При перечислении документов пользователя сервис будет возвращать те документы, которые были подписаны прошедшим аутентификацию пользователем.
При перечислении документов юридического лица сервис будет возвращать документы соответствующей организации, но при условии что:
documentsList настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя);documentsList настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя).Просматривать и изменять настроки организации могут:
organizationSettings настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя);organizationSettings настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя).Просматривать и изменять свои настройки может пользователь, выполнивший аутентификацию по сертификату НУЦ как физического, так и юридического лица.
При возникновении ошибок все методы API возвращают сообщение об ошибке следующего формата:
{
"message": "Request processing error",
"requestID": 1570108542768139099
}
message - текст сообщения об ошибке на английском языке;requestID - идентификатор запроса.Реестр сообщений об ошибках и других спеифических строк доступен на странице Известные строки.
В сервисе реализованы уведомления по следующим каналам:
Поддерживаются следующие типы уведомлений по электронной почте (email):
Сервис рассылает уведомления о подписании нового документа (1) тем получателям, которые были указаны в массиве emailNotifications.to при регистрации документа с помощью POST /api - регистрация нового документа в системе. Рассылаемые электронные письма содержат ссылки на страницу подписанного документа, а так же к ним прикреплены подлинники подписанных документов. Подлинник подписанного документа может быть не прикреплен к письму в том случае, если прикрепляемый файл не прошел проверку антивирусным программным обеспечением, либо если он большого размера.
Так же каждому пользователю, подписавшему какой-либо документ, сервис отправляет уведомление в том случае, если к этому документу была добавлена подпись - это уведомления о добавлении подписи к документу, подписанному пользователем (3). В этом случае электронные письма содержат ссылку на страницу подписанного документа и информацию о том, кто добавил подпись, подлинник подписанного документа к письму не прикрепляется. Адреса для отправки этих уведомлений сервис берет из настроек пользователей (поле email в POST /api/settings - сохранить настройки аутентифицированного пользователя), которых сервис идентифицирует по ИИН. По умолчанию в настройки заносится тот адрес электронной почты, который был указан в сертификате НУЦ, который пользователь использовал первый раз для подписания документа на сервисе, либо аутентификации. Пользователи могут отключать отправку этих уведомлений в своих настройках.
Помимо этого сервис рассылает уведомления о новых подписях под документами на те адреса электронной почты, которые были указаны при регистрации документа - уведомления о добавлении подписи к документу (2).
Рассмотрим пример:
Таким образом все заинтересованные стороны получают актуальную информацию о состоянии своих подписанных документов.
Уведомления, связанные с архивированием подписанных данных - уведомление о превышении квоты архива подписанных данных (4) и уведомление об истечении срока действия квоты архива подписанных данных (5), сервис рассылает на отдельные адреса электронной почты указанные в поле dataArchiveContactEmail в ностройках пользователей (POST /api/settings - сохранить настройки аутентифицированного пользователя) и организаций (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя).
Для информирования интегрированных систем и приложений о новых зарегистрированных в SIGEX подписях можно использовать механизм Webhook уведомлений. Параметры рассылки Webhook уведомлений настраиваются индивидуально для каждой организации в настройках соответствующей организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя).
Сервис отправляет POST запросы на указанные в настройках организации URL, тело запроса будет содержать идентификаторы документа и подписи в формате JSON:
{
"documentId": "lQsqLBaS4nQAIIMm",
"signId": 123
}
Получателю следует ответить HTTP кодом 200 (Success) с пустым телом. В том случае, если отправить запрос не удастся, либо получатель ответит иным кодом, сервис попробует повторно отправить запрос через некоторый промежуток времени.
Сервис отправляет Webhook уведомления о новой зарегистрированной подписи в том случае, если:
Рассмотрим пример:
A настроена отправка Webhook уведомлений по URL https://a.kz/webhooksB настроена отправка Webhook уведомлений по URL https://b.kz/webhooksA подписывает документ, идентификатор документа D1, идентификатор подписи S-AD1 и идентификатором подписи S-A по URL одному https://a.kz/webhooksB добавляет подпись к документу D1, идентификатор новой подписи S-BD1 и идентификатором подписи S-B по URL двум https://a.kz/webhooks и https://b.kz/webhooksD1, идентификатор новой подписи S-PD1 и идентификатором подписи S-P по URL двум https://a.kz/webhooks и https://b.kz/webhooksВ сервисе реализована опциональная функция архивирования подписанных данных, именно тех электронных документов (или просто файлов), которые были подписаны электронной цифровой подписью. Данные хранятся в архиве бессрочно, изменять, либо удалять данные в архиве невозможно. Функция может быть полезна, к примеру, в следующих сценариях:
Активировать функцию архивирования подписанных данных нужно в настройках пользователя или организации, по умолчанию она отключена. В том случае, если функция включена в настройках пользователя, то сервис будет архивировать все документы, которое подписывает этот пользователь как физическое лицо. В том случае, если функция архивирования включена в настройках организации, то сервис будет архивировать все документы подписанные сотрудниками соответствующего юридического лица.
Архивирование данных выполняется автоматически (в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота) в рамках обработки следующих API:
POST /api/{id}/data - фиксация значений хешей документаPOST /api/{id}/verify - проверка подписейPOST /api/{id}/buildDDC?fileName=X - формирование карточки электронного документаPOST /api/parseDDC?registerUnknownSignatures=false - разбор карточки электронного документаЕдинственное техническое требование - наличие HTTP заголовка Content-Length с корректным размером данных, большинство библиотек для работы с HTTP устанавливают этот заголовок автоматически.
Отдельного выделенного API для архивирования данных не предусмотрено, в том случае, если необходимо добавить в архив данные уже зарегистрированного документа (к примеру для того, чтобы добавить в архив ранее подписанные документы после включения архивирования), можно воспользоваться POST /api/{id}/verify - проверка подписей.
Для получения данных из архива следует использовать API GET /api/{id}/data - получение подписанных данных из архива.
Определить, добавлены ли данные в архив, можно по полю dataArchived в ответах API, выполняющих архивирование данных, а так же [GET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе] и GET /api/?from=xxx&until=yyy&organization=true - перечисление документов аутентифицированного пользователя.
Для каждого пользователя и организации существует квота, ограничивающая объем соответствующего архива. Информация о квотах и способах их увеличения доступна на странице Для корпоративных клиентов. Текущую квоту и объем данных в архиве можно получить с помощью GET /api/settings - получить настройки аутентифицированного пользователя и GET /api/organizationSettings - получить настройки организации аутентифицированного пользователя.
Для информирования пользователей о событиях, связанных с архивированием, предусмотрены специальные уведомления, рассылаемые по электронной почте. Эти уведомления рассылаются на отдельный настраиваемый адрес электронной почты, указанный в поле dataArchiveContactEmail, настраиваемый через POST /api/settings - сохранить настройки аутентифицированного пользователя и POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя.
POST /api - регистрация нового документа в системеВажно! Регистрация документа не будет завершена до успешного вызова POST /api/{id}/data.
В рамках регистрации нового документа и его первой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.
Сервис допускает регистрацию двух типов подписей:
CMS подписи могут включать в себя подписанные данные (рекомендуется не включать данные в подпись, так как у сервиса есть ограничение на размер принимаемых данных для этого вызова), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).
В том случае, если переданная CMS подпись содержит подписанные данные, эти данные перед сохранением будут извлечены из подписи.
Сервис допускает наличие данных TSP (метка времени) в неподписываемом атрибуте CMS signature-time-stamp со значением, содержащим метку времени. Допускается наличие только одной метки времени.
Сервис допускает наличие данных OCSP (статус сертификата) в неподписываемом атрибуте CMS revocation-values со значением, содержащим в поле RevocationValues.ocspVals[0] OCSP квитанцию со статусом сертификата подписавшего. Допускается наличие только одной квитанции.
Под XML подписью сервис подразумевает только ту часть XML, которая содержит данные о подписи - то есть только элемент <ds:Signature xmlns:ds=“http://www.w3.org/2000/09/xmldsig#">. В том случае, если подпись была сформирована с помощью вызова signXml утилиты NCALayer, то корректное извлечение необходимого элемента и оформление его в соответствии с https://www.w3.org/TR/xmldsig-core1 ложится на плечи разработчика.
Так же при регистрации нового документа можно запросить отправку уведомлений по электронной почте нескольким получателям. Эта функция может быть полезна в том случае, если документ должен быть подписан несколькими лицами - первый подписавший таким образом может запросить отправку уведомлений всем остальным. В сервисе реализовано ограничение на количество адресов. Отправка уведомлений сервисом осуществляется после завершения регистрации документа вызовом POST /api/{id}/data.
Запрос (Content-Type необходимо установить в application/json):
{
"title": "document title",
"description": "document description",
"signType": "cms",
"signature": "base64_encoded_cms",
"emailNotifications": {
"to": ["user@example.com","other@example.com"],
},
"settings": {
"private": false,
"signaturesLimit": 2,
"switchToPrivateAfterLimitReached": true,
"unique": ["iin"],
"signersRequirements": [
{
"iin": "IIN112233445566"
}
]
}
}
title - заголовок документа;description - описание документа;signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";signature - в случае CMS это должна быть закодированная в base64 подпись, в случае XML - текстовое представление XML;emailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о подписании документа, в данный момент поддерживается только поле to которое должно быть массивом адресов электронной почты;settings - опциональное поле, объект настроек документа, описание приведено в POST /api/{id}/settings - изменение настроек документа.Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"signId": 123,
"data": "MTEK"
}
documentId - уникальный идентификатор зарегистрированного документа;signId - уникальный идентификатор добавленной подписи;data - опциональное поле, извлеченные из CMS подписанные данные в виде base64 строки, присутствует только в том случае, если переданная в запросе подпись включала подписанные данные.POST /api/{id}/data - фиксация значений хешей документа{id} - идентификатор документа.Сервис SIGEX, по умолчанию, не хранит подписанных документов и ему необходим какой-то способ определить относятся ли две подписи к одному и тому же документу. В том случае, когда алгоритмы подписей идентичны, это просто - в подписях присутствуют хеши документа и достаточно требовать их идентичности. В том же случае, если алгоритмы подписей отличаются, то и значения хешей не будут совпадать, так как они вычисляются по разным алгоритмам.
Отличаться алгоритмы подписей могут в том случае, когда один и тот же документ подписывают юридическое лицо (НУЦ выпускает в этом случае сертификаты ГОСТ 34.310-2004) и физическое лицо (НУЦ выпускает сертификаты RSA).
Выбранное нами решение - попросить передать сервису подписанный документ один раз для завершения его регистрации в системе. SIGEX вычислит все необходимые значения хешей и сохранит их в своей базе данных. Содержимое переданного документа сохранено не будет.
Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream и заголовок Content-Length с корректным размером передаваемых данных.
В качестве тела запроса следует передать оригинальный документ.
В случае XML подписи необходимо передать XML документ именно в том виде в котором он подписывался, а так же выполнить все указанные в XML подписи трансформации - сервис не будет каким-либо обрабом обрабатывать поступающие данные, он будет хешировать их “как есть”. Больше информации можно найти в стандарте https://www.w3.org/TR/xmldsig-core1.
В том случае, если при регистрации документа было указано поле emailNotifications с не пустым списокм получателей, то сервис попробует отправить уведомления получателям по электронной почте. В том случае, если размер документа не большой (ограничение определяется почтовой системой), то сервис прикрепит документ к отправляемым уведомлениям. О том, был ли прикреплен документ к отправленным уведомлениям, сигрализирует значение поля emailNotifications.attached в ответе.
При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.
Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"signedDataSize": 0,
"digests": {
"oid": "base64_encoded_digest_value",
"otherOid": "base64_encoded_digest_value",
},
"emailNotifications": {
"attached": true,
"message": "Failed to send notification"
},
"automaticallyCreatedUserSettings":
{
"userId": "IIN123456789012",
"emailNotificationsEnabled": true,
"email": "email@GMAIL.COM",
"modifiedAt": 1586167317737
},
"dataArchived": false
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;signedDataSize - размер подписанного документа в байтах (если размер не известен, то 0);digests - объект, содержащий вычисленные значения хешей;emailNotifications - опциональное поле, присутствует только в том случае, если при регистрации документа было указано аналогичное поле с не пустым списком получателей, его поле attached говорит о том, был ли прикреплен документ к отправленным уведомлениям, поле message присутствует только в том случае, если в процессе отправки уведомлений произошла ошибка и описывает эту ошибку;automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз регистрирует свою подпись на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings;dataArchived - информирует о том, находятся ли подписанные данные в архиве.GET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе{id} - идентификатор документа;lastSignId=X - опционально, последний идентификатор подписи после которого нужно возвращаться подписи.Следует учитывать то, что данная функция возвращает ограниченное количество подписей - то есть в том случае, если подписей много, то за один вызов их получить не получится.
Алгоритм получения всех подписей:
lastSignId;lastSignId=signId из последнего элемента массива подписей;Ответ:
{
"title": "document title",
"description": "document description",
"signedDataSize": 0,
"emailNotifications": {
"to": ["user@example.com","other@example.com"],
},
"settings": {
"private": false,
"signaturesLimit": 2,
"switchToPrivateAfterLimitReached": true,
"unique": ["iin"],
"signersRequirements": [
{
"iin": "IIN112233445566"
}
]
},
"signaturesTotal": 2,
"signatures": [
],
"dataArchived": false,
"canBeArchived": true
}
title - заголовок документа;description - описание документа;signedDataSize - размер подписанного документа в байтах (если размер не известен, то 0);emailNotifications - информация о том, кому была запрошена отправка уведомлений по электронной почте при регистрации первой подписи;settings - объект настроек документа, описание приведено в POST /api/{id}/settings - изменение настроек документа;signaturesTotal - общее количество подписей документа;signatures - массив объектов с данными о подписях документа;dataArchived - информирует о том, находятся ли подписанные данные в архиве;canBeArchived - информирует о том, что документ может быть добавлен в архив (такая ситуация может возникнуть если в настройках первого подписавшего архивирование отключено, но включено у кого-то из других подписавших), для того, чтобы добавить документ в архив, следует использовать POST /api/{id}/verify - проверка подписей.Структура объекта данных подписи:
{
"userId": "IIN1234567890AB",
"businessId": "BIN1234567890AB",
"subject": "SERIALINUMBER=IIN1234567890AB,CN=User",
"subjectStructure": [
[
{
"oid": "2.5.4.5",
"name": "SERIALINUMBER",
"valueInB64": false,
"value": "IIN1234567890AB"
}
],
[
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "User"
}
]
],
"certSignAlgorithm": "1.2.840.113549.1.1.11",
"serialNumber": "4beb939d4fb14b047f3bcddf3881eb2ff9acbeb5",
"from": 1535622190000,
"until": 1630120980000,
"issuer": "C=KZ,CN=ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)",
"issuerStructure": [
[
{
"oid": "2.5.4.6",
"name": "C",
"valueInB64": false,
"value": "KZ"
}
],
[
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)"
}
]
],
"signAlgorithm": "1.2.840.113549.1.1.11",
"policyIds": ["OID.0","OID.1"],
"keyUsages": ["digitalSignature", "nonRepudiation"],
"extKeyUsages": ["OID.0","OID.1"],
"storedAt": 1568809427182,
"signId": 1,
"signType": "cms",
"tsp": {},
"ocsp": {}
}
userId - ИИН подписавшего;businessId - БИН подписавшего, доступен только в случае использования сертификата юридического лица;subject - имя владельца (Subject) сертификата сформированное в соответствии с RFC 4514;subjectStructure - структурированное представление имени владельца (Subject) сертификата;certSignAlgorithm - OID алгоритма подписи сертификата;serialNumber - серийный номер сертификата;from - начало срока действия сертификата;until - окончание срока действия сертификата;issuer - имя издателя (Issuer) сертификата сформированное в соответствии с RFC 4514;issuerStructure - структурированное представление имени издателя (Issuer) сертификата;signAlgorithm - OID алгоритма подписи;policyIds - массив OID-ов политик использования сертификата подписавшего;keyUsages - массив строк использования ключа (в соответствии с https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3);extKeyUsages - массив OID-ов расширенного использования ключа;storedAt - время сохранения подписи в системе (миллисекунд с UNIX Epoch);signId - уникальный идентификатор подписи в системе;signType - тип подписи, поддерживается два строковых значения "cms" и "xml";tsp - структура метки времени TSP (опциональное поле);ocsp - структура OCSP ответа о статусе сертификата (опциональное поле).Структура метки времени TSP:
{
"timeStamp": 1621518969000,
"timeStampPolicy": "1.2.398.3.3.2.6.2",
"signAlgorithm": "1.2.840.113549.1.1.11",
"certSignAlgorithm": "1.2.840.113549.1.1.11",
"serialNumber": "3d9de56d5f379c5d06ec7d8b83aa50bdeb437d34",
"from": 1576128125000,
"until": 1670736125000,
"subject": "CN=TSA SERVICE,C=KZ",
"subjectStructure": [
[
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "TSA SERVICE"
}
],
[
{
"oid": "2.5.4.6",
"name": "C",
"valueInB64": false,
"value": "KZ"
}
]
],
"issuer": "C=KZ,CN=ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)",
"issuerStructure": [
[
{
"oid": "2.5.4.6",
"name": "C",
"valueInB64": false,
"value": "KZ"
}
],
[
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)"
}
]
],
"policyIds": [],
"keyUsages": [],
"extKeyUsages": [
"1.3.6.1.5.5.7.3.8"
]
}
timeStamp - метка времени (миллисекунды с UNIX Epoch);timeStampPolicy - OID политики выпуска метки времен;signAlgorithm - OID алгоритма подписи;certSignAlgorithm - OID алгоритма подписи сертификата, использованного УЦ для подписания метки времени;serialNumber - серийный номер сертификата, использованного УЦ для подписания метки времени;from - начало срока действия сертификата, использованного УЦ для подписания метки времени;until - окончание срока действия сертификата, использованного УЦ для подписания метки времени.subject - имя владельца (Subject) сертификата, использованного УЦ для подписания метки времени, сформированное в соответствии с RFC 4514;subjectStructure - структурированное представление имени владельца (Subject) сертификата, использованного УЦ для подписания метки времени;issuer - имя издателя (Issuer) сертификата, использованного УЦ для подписания метки времени, сформированное в соответствии с RFC 4514;issuerStructure - структурированное представление имени издателя (Issuer) сертификата, использованного УЦ для подписания метки времени;policyIds - массив OID-ов политик использования сертификата, использованного УЦ для подписания метки времени;keyUsages - массив строк использования ключа (в соответствии с https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3) сертификата, использованного УЦ для подписания метки времени;extKeyUsages - массив OID-ов расширенного использования ключа сертификата, использованного УЦ для подписания метки времени.Структура OCSP ответа о статусе сертификата:
{
"producedAt": 1621518968000,
"thisUpdate": 1621518968000,
"certStatus": "good",
"signAlgorithm": "1.2.840.113549.1.1.11",
"certSignAlgorithm": "1.2.840.113549.1.1.11",
"serialNumber": "1dd4d03a63db59beea1375d34908fd6655e7e4a9",
"from": 1607001246000,
"until": 1638537246000,
"subject": "CN=OCSP RESPONDER,C=KZ",
"subjectStructure": [
[
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "OCSP RESPONDER"
}
],
[
{
"oid": "2.5.4.6",
"name": "C",
"valueInB64": false,
"value": "KZ"
}
]
],
"issuer": "C=KZ,CN=ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)",
"issuerStructure": [
[
{
"oid": "2.5.4.6",
"name": "C",
"valueInB64": false,
"value": "KZ"
}
],
[
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (RSA)"
}
]
],
"policyIds": [],
"keyUsages": [],
"extKeyUsages": [
"1.3.6.1.5.5.7.3.9"
]
}
producedAt - момент формирования ответа сервером УЦ (миллисекунды с UNIX Epoch);thisUpdate - дата с которой можно считать предоставленную информации о статусе сертификата актуальной (миллисекунды с UNIX Epoch);nextUpdate - дата до которой можно считать предоставленную информации о статусе сертификата актуальной (миллисекунды с UNIX Epoch)(опциональное поле);certStatus - строка, должна быть "good", так как сервис не принимает подписи для которых не удалось получить ответа с хорошим статусом;signAlgorithm - OID алгоритма подписи;certSignAlgorithm - OID алгоритма подписи сертификата, использованного УЦ для подписания ответа;serialNumber - серийный номер сертификата, использованного УЦ для подписания ответа;from - начало срока действия сертификата, использованного УЦ для подписания ответа;until - окончание срока действия сертификата, использованного УЦ для подписания ответа.subject - имя владельца (Subject) сертификата, использованного УЦ для подписания ответа, сформированное в соответствии с RFC 4514;subjectStructure - структурированное представление имени владельца (Subject) сертификата, использованного УЦ для подписания ответа;issuer - имя издателя (Issuer) сертификата, использованного УЦ для подписания ответа, сформированное в соответствии с RFC 4514;issuerStructure - структурированное представление имени издателя (Issuer) сертификата, использованного УЦ для подписания ответа;policyIds - массив OID-ов политик использования сертификата, использованного УЦ для подписания ответа;keyUsages - массив строк использования ключа (в соответствии с https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3) сертификата, использованного УЦ для подписания ответа;extKeyUsages - массив OID-ов расширенного использования ключа сертификата, использованного УЦ для подписания ответа.Структурированные представления имен владельца (Subject) сертификата и издателя (Issuer) сертификата - это массивы, содержащий набор RDN, каждый из которых, в свою очередь, является массивом аттрибутов. Представление основывается на структуре поля Subject сертификата, описанного в RFC 5280.
Каждый атрибут представлен в виде объекта:
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "User CommonName",
}
oid - объектный идентификатор типа атрибута;name - тестовое представление типа атрибута в соответствии со структурами регистрационных свидетельств (сертификатов) описанных в документе “Правила применения регистрационных свидетельств НУЦ РК” доступного на портале НУЦ РК в разделе Документация;valueInB64 - флаг, определяющий является ли значение в поле value строкой, либо base64 представлением бинарных данных;value - значение атрибута, значения некоторых атрибутов не могут быть представлены в текстовом виде, в этом случае в это поле будет записано base64 представление бинарного значения атрибута и valueInB64 будет установлен в true.GET /api/{id}/data - получение подписанных данных из архива{id} - идентификатор документа.Позволяет получить подписанные данные в том случае, если они предварительно были помещены в архив.
Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"document": "MTEK",
"signedDataSize":13567
}
documentId - уникальный идентификатор зарегистрированного документа;document - подписанные данные в виде base64 строки;signedDataSize - размер подписанного документа (в байтах).POST /api/{id} - добавление подписи к документу{id} - идентификатор документа.В рамках регистрации новой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.
Сервис допускает регистрацию двух типов подписей:
CMS подписи могут включать в себя подписанные данные (рекомендуется не включать данные в подпись, так как у сервиса есть ограничение на размер принимаемых данных для этого вызова), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).
В том случае, если переданная CMS подпись содержит подписанные данные, эти данные перед сохранением будут извлечены из подписи.
Сервис допускает наличие данных TSP (метка времени) в неподписываемом атрибуте CMS signature-time-stamp со значением, содержащим метку времени. Допускается наличие только одной метки времени.
Сервис допускает наличие данных OCSP (статус сертификата) в неподписываемом атрибуте CMS revocation-values со значением, содержащим в поле RevocationValues.ocspVals[0] OCSP квитанцию со статусом сертификата подписавшего. Допускается наличие только одной квитанции.
Под XML подписью сервис подразумевает только ту часть XML, которая содержит данные о подписи - то есть только элемент <ds:Signature xmlns:ds=“http://www.w3.org/2000/09/xmldsig#">. В том случае, если подпись была сформирована с помощью вызова signXml утилиты NCALayer, то корректное извлечение необходимого элемента и оформление его в соответствии с https://www.w3.org/TR/xmldsig-core1 ложится на плечи разработчика.
Запрос (Content-Type необходимо установить в application/json):
{
"signType": "cms",
"signature": "base64_encoded_cms"
}
signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";signature - в случае CMS это должна быть закодированная в base64 подпись, в случае XML - текстовое представление XML.Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"signId": 123,
"data": "MTEK",
"automaticallyCreatedUserSettings":
{
"userId": "IIN123456789012",
"emailNotificationsEnabled": true,
"email": "email@GMAIL.COM",
"modifiedAt": 1586167317737
},
"dataArchived": false,
"canBeArchived": true
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;signId - уникальный идентификатор добавленной подписи;data - опциональное поле, извлеченные из CMS подписанные данные в виде base64 строки, присутствует только в том случае, если переданная в запросе подпись включала подписанные данные;automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз регистрирует свою подпись на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings;dataArchived - информирует о том, находятся ли подписанные данные в архиве;canBeArchived - информирует о том, что документ может быть добавлен в архив (такая ситуация может возникнуть если в настройках первого подписавшего архивирование отключено, но включено у кого-то из других подписавших), для того, чтобы добавить документ в архив, следует использовать POST /api/{id}/verify - проверка подписей.POST /api/{id}/verify - проверка подписей{id} - идентификатор документа.Данный метод выполнит следующее:
Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream и заголовок Content-Length с корректным размером передаваемых данных.
В качестве тела запроса следует передать оригинальный документ.
В случае XML подписи необходимо передать XML документ именно в том виде в котором он подписывался, а так же выполнить все указанные в XML подписи трансформации - сервис не будет каким-либо обрабом обрабатывать поступающие данные, он будет хешировать их “как есть”. Больше информации можно найти в стандарте https://www.w3.org/TR/xmldsig-core1.
При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.
Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"dataArchived": false
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;dataArchived - информирует о том, находятся ли подписанные данные в архиве.GET /api/{id}/signature/{signId}?signFormat=X - экспорт одной подписи документа{id} - идентификатор документа;{signId} - идентификатор подписи;signFormat=X - опционально, формат экспорта, по умолчанию 0.Поддерживаются следующие форматы экспорта:
0 (по умолчанию) - CMS с интегрированными меткой времени (TimeStampToken, CMS атрибут с OID 1.2.840.113549.1.9.16.2.14) и квитанцией OCSP (BasicOCSPResponse, CMS атрибут с OID-ом 1.2.840.113549.1.9.16.2.24);1 - оригинальный CMS, принятый в систему при добавлении подписи.Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"signId": 1,
"signType": "cms",
"signFormat": 0,
"signature": "base64_encoded_cms"
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;signId - уникальный идентификатор подписи в системе;signType - тип подписи, поддерживается два строковых значения "cms" и "xml";signFormat - формат подписи;signature - в случае CMS это закодированная в base64 подпись, в случае XML - текстовое представление XML.GET /api/{id}/signature/{signId}/qr?signFormat=X&qrVersion=25&qrLevel=M - экспорт подписи в виде набора QR кодов{id} - идентификатор документа;{signId} - идентификатор подписи;signFormat=X - опционально, формат экспорта, по умолчанию 0;qrVersion=25 - опционально, версия QR кода (размер), по умолчанию 25, версии ниже 11 не поддерживаются, детали тут https://www.qrcode.com/en/about/version.html;qrLevel=M - опционально, уровень коррекции ошибок (ECC), по умолчанию M, детали тут https://www.qrcode.com/en/about/version.html.Поддерживаются следующие форматы экспорта:
0 (по умолчанию) - CMS с интегрированными меткой времени (TimeStampToken, CMS атрибут с OID 1.2.840.113549.1.9.16.2.14) и квитанцией OCSP (BasicOCSPResponse, CMS атрибут с OID-ом 1.2.840.113549.1.9.16.2.24);1 - оригинальный CMS, принятый в систему при добавлении подписи.Формирование набора QR кодов осуществляется по следующему алгоритму:
{signId}.{signType}, то есть имя файла - это идентификатор подписи, а расширение - тип подписи (в текущей реализации "xml" или "cms").qrVersion (версия) и qrLevel (уровень коррекции ошибок).qrCodes который является частью ответа, изображения в нем закодированы в base64.JSON структура части подписи:
{
"documentId": "Nzxn6JCumwKKhEv4",
"signId": 9,
"signType": "xml",
"total": 7,
"index": 1,
"data": "part_of_archived_and_base64_encoded_signature"
}
где:
documentId - идентификатор документа;signId - уникальный идентификатор подписи в системе;signType - тип подписи, поддерживается два строковых значения "cms" и "xml";total - общее количество частей;index - индекс данной части;data - строка, часть base64 представления ZIP архива.Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"signId": 1,
"signType": "cms",
"signFormat": 0,
"qrCodes": [
"base64_encoded_png_with_qr_code_part1",
...
"base64_encoded_png_with_qr_code_partn"
]
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;signId - уникальный идентификатор подписи в системе;signType - тип подписи, поддерживается два строковых значения "cms" и "xml";signFormat - формат подписи;qrCodes - массив строк каждая из которых содержит закодированное в base64 изображение в формате PNG с закодированным QR кодом.POST /api/{id}/buildDDC?fileName=X - формирование карточки электронного документа{id} - идентификатор документа;fileName=X - опционально, имя файла для встраивания подлинника электронного документа, если не передан, будет использован заголовок документа в системе.Сервис выполнит следующее:
Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream и заголовок Content-Length с корректным размером передаваемых данных.
В качестве тела запроса следует передать оригинальный документ. В данный момент поддерживаются исключительно документы в формате PDF.
При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.
Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"ddc": "MTEK",
"dataArchived": false
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;ddc - файл карточки электронного документа в виде base64 строки;dataArchived - информирует о том, находятся ли подписанные данные в архиве.POST /api/{id}/settings - изменение настроек документа{id} - идентификатор документа.Отправка нового объекта с настройками документа. Все поля объекта опциональны, то есть можно указывать только те настройки, которые должны отличаться от настройек по умолчанию.
Все текущие настройки документа будут перезаписаны. Даже в том случае, если в передаваемом новом объекте настроек какая-то настройка отсутствует, будет использовано значение по умолчанию.
Запрос (Content-Type необходимо установить в application/json):
{
"private": false,
"signaturesLimit": 2,
"switchToPrivateAfterLimitReached": true,
"unique": ["iin", "bin"],
"signersRequirements": [
{
"iin": "IIN112233445566"
},
{
"bin": "BIN112233445566",
"authorities": ["OID1", "OID2"],
},
{
"bin": "BIN112233445566",
"iin": "IIN112233445566"
},
{
"bin": "BIN112233445566",
"authorities": ["OID1", "OID2"],
"iin": "IIN112233445566"
}
]
}
private - опциональное поле, определяет ограничен ли доступ к документу (см. Аутентификация и контроль доступа), либо он является общедоступным документом, по умолчанию false;signaturesLimit - опциональное поле, ограничение на разрешенное количество подписей под документом (0 - не ограничено), по умолчанию 0;switchToPrivateAfterLimitReached - опциональное поле, определяет должен ли сервис автоматически переключить настройку private в true после того, как будет зарегистрировано signaturesLimit подписей, по умолчанию false;unique - опциональное поле, массив требований к уникальности, может включать в себя константы "iin" и "bin", константы ограничивают возможность регистрации подписей с идентичными ИИН и БИН, по умолчанию [] (то есть ограничения отсутствуют);signersRequirements - опциональное поле, массив требований к подписям, в том случае, если он не пуст, каждая регистрируемая подпись перед регистрацией должна быть проверена на соответствие требованиям (должна удовлетворить хотя бы одному элементу массива - объединяются через ИЛИ), по умолчанию [] (то есть требования отсутствуют).Требования signersRequirements - это объекты со следующими опциональными полями (необходимо одно любое поле):
{
"bin": "BIN112233445566",
"authorities": ["OID1", "OID2"],
"iin": "IIN112233445566"
}
bin - опциональное поле, в сертификате в подписи должен присутствовать соответствующий БИН;authorities - опциональное поле, в сертификате в подписи должно присутствовать одно из указанных полномочий;iin - опциональное поле, в сертификате в подписи должен присутствовать соответствующий ИИН.В том случае, если указано несколько полей, то они ужесточают друг друга (объединяются через И).
Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm"
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору.GET /api/{id}/settingsAudit?lastEventId=X - аудит изменений настроек документа{id} - идентификатор документа;lastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.Возвращает журнал изменений настроек документа.
Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"eventsTotal": 3,
"events": []
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;eventsTotal - количество изменений зарегистрированных в системе;events - массив объектов описывающих изменения.Структура объектов описывающих изменения:
{
"eventId": 1,
"original": {},
"modified": {},
"modifiedBy": "IIN123456789",
"modifiedByDigest": "XXXXXXXXXXXXXXX",
"modifiedAt": 1586167317737
}
eventId - идентификатор события;original - настройки до изменения;modified - настройки после изменения;modifiedBy - кем были произведены изменения, ИИН;modifiedByDigest - хеш клиентского сертификата в том случае, если изменение было выполненой от имени информационной системы;modifiedAt - момент изменения в миллисекундах с UNIX Epoch.GET /api/{id}/buildFileName?name=XXX - сформировать имя файла с идентификатором SIGEX{id} - идентификатор документа;name=XXX - опционально, имя файла без идентификатора, если не указано, то будет использовано значение из title документа.Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"fileName": "XXX-SigexId{id}"
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;fileName - имя файла со встроенным идентификатором SIGEX.POST /api/exported - получение идентификаторов документа и подписи по ранее экспортированной подписи документаВ передаваемой подписи допускается наличие метки времени TSP (signature-time-stamp) и квитанции OCSP (revocation-values). Важно чтобы метка времени и квитанция, в том случае, если они присутствуют, были именно теми же, которые зарегистрированы в сервисе. Это обусловлено тем, что метка времени и квитанция фиксируют момент подписания и, в том случае, если были получены другие метка времени и квитанция, эти данные не будут совпадать с теми, которые зарегистрированы в сервисе.
В частности поддерживаются подписи полученные следующими способами:
GET /api/{id}/signature/{signId};Запрос (Content-Type необходимо установить в application/json):
{
"signType": "cms",
"signature": "base64_encoded_cms"
}
signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";signature - в случае CMS это должна быть закодированная в base64 подпись, в случае XML - текстовое представление XML.Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"signId": 1
}
documentId - уникальный идентификатор документа;signId - уникальный идентификатор подписи.POST /api/parseDDC?registerUnknownSignatures=false - разбор карточки электронного документаregisterUnknownSignatures=false - опционально, определяет должен ли сервис регистрировать новые неизвестные подписи, по умолчанию false.Сервис выполнит следующее:
registerUnknownSignatures=true, попробует их зарегистрировать, вернет ошибку в том случае, если не удалось зарегистрировать какую-либо из них;registerUnknownSignatures=false, вернет ошибку;Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream.
В качестве тела запроса следует передать файл Карточки электронного документа.
При обработке этого API сервис автоматически выполняет архивирование подписанных данных в том случае, если в настройках хотя бы одной из подписавших документ сторон включено архивирование и, при этом, не превышена квота.
Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"signIds": [1, 2],
"document": "MTEK",
"dataArchived": false
}
documentId - идентификатор документа;signIds - массив идентификаторов подписей;document - файл извлеченного подлинника подписанного документа в виде base64 строки;dataArchived - информирует о том, находятся ли подписанные данные в архиве.POST /api/auth - аутентификация, подготовительный этап - получение блока случайных данныхАутентификация основана на подписании пользователем блока случайных данных полученных от сервиса. Подготовительный этап заключается в передаче сервису запроса на новый блок случайных данных.
Важно! Каждый блок случйных данных может быть использован только один раз и имеет ограниченный срок действия.
Вопросы интеграции аутентификации по цифровым сертификатам в информационные системы освещен в заметке Аутентификация по цифровым сертификатам
Запрос (Content-Type необходимо установить в application/json):
{
}
Ответ:
{
"nonce": "base64_encoded_nonce"
}
nonce - блок случайных данных в base64.POST /api/auth - аутентификацияДля выполнения аутентификации необходимо передать сервису цифровую подпись ранее полученного блока случайных данных. В том случае, если проверка подписи сервисом пройдет успешно, пользователь будет идентифицирован по данным содержащемся в его сертификате.
Поддерживается два режима работы:
В режиме внутренней аутентификации для хранения информации об аутентификации используется cookie (Secure, HttpOnly и SameSite=Strict) с именем jwt в котором хранятся данные о прошедшем аутентификацию пользователе в формате JWT. Полезная нагрузка JWT токена содержит информацию, необходимую для идентификации пользователя.
При обращении к защищенным API сервис проверяет наличие в заголовках запроса cookie jwt и на основании данных в JWT токене принимает решение об авторизации.
В рамках обработки всех API выполняется проверка оставшего времени жизни JWT токена в cookie jwt и, при необходимости, его обновление. Новый JWT токен передается в ответе в cookie jwt.
Так же в режиме внутренней аутентификации в SIGEX будет создан профиль с настройками нового пользователя.
В режиме внешней аутентификации никаких cookie не устанавливается и профилей не создается, сторонняя информационная система получает ответ с данными сертификата которые она может использовать для авторизации (принятия решения о предоставлении пользователю прав доступа в систему).
Вопросы интеграции аутентификации по цифровым сертификатам в информационные системы освещен в заметке Аутентификация по цифровым сертификатам
Запрос (Content-Type необходимо установить в application/json):
{
"nonce": "base64_encoded_nonce",
"signature": "base64_encoded_cms",
"external": true
}
nonce - блок случайных данных в base64 полученный от сервиса на подготовительном этапе;signature - закодированная в base64 подпись nonce, ее можно получить у NCALayer методом createCAdESFromBase64;external - опциональное поле, позволяет установить режим внешней аутентификации, по умолчанию false.Ответ:
{
"userId": "IIN1234567890AB",
"businessId": "BIN1234567890AB",
"subject": "SERIALINUMBER=IIN1234567890AB,CN=User",
"subjectStructure": [
[
{
"oid": "2.5.4.5",
"name": "SERIALINUMBER",
"valueInB64": false,
"value": "IIN1234567890AB"
}
],
[
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "User"
}
]
],
"signAlgorithm": "1.2.840.113549.1.1.11",
"policyIds": ["OID.0","OID.1"],
"extKeyUsages": ["OID.0","OID.1"]
}
userId - ИИН пользователя прошедшего аутентификацию;businessId - БИН пользователя прошедшего аутентификацию, доступен только в случае использования сертификата юридического лица;subject - имя владельца (Subject) сертификата сформированное в соответствии с RFC 4514;subjectStructure - структурированное представление имени владельца (Subject) сертификата;signAlgorithm - OID алгоритма подписи;policyIds - массив OID-ов политик использования сертификата;extKeyUsages - массив OID-ов расширенного использования ключа.Структурированное представление имени владельца (Subject) сертификата - это массив, содержащий набор RDN, каждый из которых, в свою очередь, является массивом аттрибутов. Представление основывается на структуре поля Subject сертификата, описанного в RFC 5280.
Каждый атрибут представлен в виде объекта:
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "User CommonName",
}
oid - объектный идентификатор типа атрибута;name - тестовое представление типа атрибута в соответствии со структурами регистрационных свидетельств (сертификатов) описанных в документе “Правила применения регистрационных свидетельств НУЦ РК” доступного на портале НУЦ РК в разделе Документация;valueInB64 - флаг, определяющий является ли значение в поле value строкой, либо base64 представлением бинарных данных;value - значение атрибута, значения некоторых атрибутов не могут быть представлены в текстовом виде, в этом случае в это поле будет записано base64 представление бинарного значения атрибута и valueInB64 будет установлен в true.POST /api/auth - сброс аутентификацииТехнически сброс аутентификации заключается в возврате cookie с именем jwt с пустым значением, атрибутом Max-Age установленным в 0 и атрибутом Expires содержащим дату до текущей даты. Ожидаемая реакция совместимого браузера заключается в удалении cookie с именем jwt из локального хранилища.
Запрос (Content-Type необходимо установить в application/json):
{
"logout": true
}
logout - должно быть установлено в true.Ответ:
{
}
GET /api/auth - текущее состояние аутентификацииВ случае том случае, если аутентификация пройдена и в заголовках запроса присутствовал cookie jwt, то ответ будет идентичен тому, который возвращает POST /api/auth - аутентификация.
GET /api/?from=xxx&until=yyy&organization=true?dataArchived=true - перечисление документов аутентифицированного пользователяfrom=xxx - с какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;until=yyy - до какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;organization=true - опциональный параметр, определяет следует ли искать документы физического лица или организации, по умолчанию false;dataArchived=true - опциональный параметр, определяет следует ли искать документы, данные которых находятся в архиве или нет.Ответ сервиса зависит от значения organization:
false - в этом случае сервис вернет документы которые подписывал аутентифицированный пользователь (как физическое лицо либо как представитель юридического лица);true - в том случае, если пользователь прошел аутентификацию с помощью сертификата представителя организации (юридического лица) и у него в сертификате присутствуют полномочия указанные в настройках организации, то метод вернет перечень документов, которые подписывали любые представители этой организации.Так же на ответ влияет значение dataArchived:
false - в этом случае сервис вернет только те документы, подписанные данные которых не сохранены в архиве;true - в этом случае сервис вернет только те документы, подписанные данные которых сохранены в архиве;Сервис будет возвращать документы сортированными в порядке убывания даты их регистрации, то есть сначала самые новые.
Следует учитывать то, что данный метод возвращает ограниченное количество документов за один вызов, алгоритм получения всех документов:
from=xxx и until=yyy;until=storedAt из последнего элемента массива документов;Ответ:
{
"documentsTotal": 3,
"documents": []
}
documentsTotal - количество документов удовлетворяющих запросу;documents - массив объектов документов.Структура объекта данных документа:
{
"documentId": "lQsqLBaS4nQAIIMm",
"storedAt": 11111111111,
"title": "document title",
"description": "document description",
"dataArchived": false,
"signedDataSize": 123
}
documentId - уникальный идентификатор документа;storedAt - момент регистрации документа в системе (миллисекунд с UNIX Epoch).;title - заголовок документа;description - описание документа;dataArchived - информирует о том, находятся ли подписанные данные в архиве;signedDataSize - размер подписанного документа в байтах (если размер не известен, то 0).GET /api/settings - получить настройки аутентифицированного пользователяОтвет:
{
"userId": "IIN123456789012",
"emailNotificationsEnabled": true,
"email": "user@example.com",
"modifiedAt": 1585827107000,
"dataArchiveEnabled": false,
"dataArchiveQuota": 123,
"dataArchiveQuotaExpires": 1585827107001,
"dataArchiveUsage": 123,
"dataArchiveContactEmail": "userArchiver@example.com"
}
userId - ИИН пользователя;emailNotificationsEnabled - флаг указывающий включена ли отправка уведомлений по электронной почте для данного пользователя;email - электронный адрес пользователя, поле может содержать пустую строку ("");modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. В случае, если настройки ранее не были сохранены, то поле содержит 0;dataArchiveEnabled - флаг, указывающий активировано ли архивирование подписанных данных, если включен, необходимо указать dataArchiveContactEmail;dataArchiveQuota - размер текущей квоты архивирования (в байтах);dataArchiveQuotaExpires - опциональное поле, содержащее дату истечения срока действия дополнительной квоты (в миллисекундах с UNIX Epoch);dataArchiveUsage - объем хранящихся в архиве данных (в байтах);dataArchiveContactEmail - электронный адрес для отправки уведомлений, связанных с архивированием данных.POST /api/settings - сохранить настройки аутентифицированного пользователяЗапрос (Content-Type необходимо установить в application/json):
{
"emailNotificationsEnabled": false,
"email": "otheruser@example.com",
"dataArchiveEnabled": true,
"dataArchiveContactEmail": "userArchiver@example.com"
}
emailNotificationsEnabled - новое значение флага указывающего включена ли отправка уведомлений по электронной почте для данного пользователя;email - новый электронный адрес пользователя, разрешено передавать пустую строку ("");dataArchiveEnabled - новое значение флага, позволяющего включить/отключить архивирование подписанных данных;dataArchiveContactEmail - новый электронный адрес для отправки уведомлений, связанных с архивированием данных.Ответ:
{
"userId": "IIN123456789012",
"modifiedAt": 1585827107000
}
userId - ИИН пользователя;modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch.GET /api/settingsAudit?lastEventId=X - аудит изменений настроек пользователяlastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.Возвращает журнал изменений настроек пользователя.
Ответ:
{
"userId": "IIN112233445566",
"eventsTotal": 3,
"events": []
}
userId - ИИН пользователя;eventsTotal - количество изменений зарегистрированных в системе;events - массив объектов описывающих изменения.Структура объектов описывающих изменения:
{
"eventId": 1,
"original": {},
"modified": {},
"modifiedAt": 1586167317737
}
eventId - идентификатор события;original - настройки до изменения;modified - настройки после изменения;modifiedAt - момент изменения в миллисекундах с UNIX Epoch.GET /api/organizationSettings - получить настройки организации аутентифицированного пользователяНастройки организации определяют уровень доступа к документам организации сотрудникам, имеющим указанные полномочия, и информационным системам, прошедшим аутентификацию по указанным клиентским сертификатам.
Подробнее о методах аутентификации и настройках читайте в разделе Аутентификация и контроль доступа.
Ответ:
{
"businessId": "BIN123456789012",
"tlsCertificatesList": [
{
"description": "First certificate",
"body": "PEM-ENCODED-CERT-1",
"disabled": false
},
{
"description": "Second certificate",
"body": "PEM-ENCODED-CERT-2",
"disabled": false
},
{
"description": "Third certificate",
"body": "PEM-ENCODED-CERT-3",
"disabled": true
},
],
"documentsAccess": {
"authorities": ["OID1", "OID2"],
"tlsCertificatesIndices": [0]
},
"documentsList": {
"authorities": ["OID1", "OID2"],
"tlsCertificatesIndices": [0, 1]
},
"documentsSettings": {
"authorities": ["OID1", "OID2"],
"tlsCertificatesIndices": [1]
},
"organizationSettings": {
"authorities": ["OID1", "OID2"],
"tlsCertificatesIndices": [1]
},
"webhooks":{
"urls":["https://example.com/webhook-for-sigex","http://192.168.1.12"]
},
"modifiedAt": 1585827107000,
"dataArchiveEnabled": false,
"dataArchiveQuota": 123,
"dataArchiveQuotaExpires": 1585827107001,
"dataArchiveUsage": 123,
"dataArchiveContactEmail": "orgArchiver@example.com"
}
businessId - БИН организации;tlsCertificatesList - массив клиентских сертификатов информационных систем;documentsAccess - контроль доступа к документам организации;documentsList - контроль доступа к перечислению документов организации;documentsSettings - контроль доступа к редактированию настроек документов организации;organizationSettings - контроль доступа к просмотру и редактированию настроек организации;webhooks - параметры доставки Webhook уведомлений;modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. В случае, если настройки ранее не были сохранены, то поле содержит 0;dataArchiveEnabled - флаг, указывающий активировано ли архивирование подписанных данных, если включен, необходимо указать dataArchiveContactEmail;dataArchiveQuota - размер текущей квоты архивирования (в байтах);dataArchiveQuotaExpires - опциональное поле, содержащее дату истечения срока действия дополнительной квоты (в миллисекундах с UNIX Epoch);dataArchiveUsage - объем хранящихся в архиве данных (в байтах);dataArchiveContactEmail - электронный адрес для отправки уведомлений, связанных с архивированием данных.Элементы массива tlsCertificatesList хранят информацию о сертификатах, которые информационные системы могут использовать для клиентской TLS аутентификации и имеют следующую структуру:
description - описание;body - сертификат в формате PEM, то есть строка;disabled - флаг помечающий сертификат как отключенный.Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру:
authorities - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа;tlsCertificatesIndices - массив индексов сертификатов из tlsCertificatesList, определяет по каким сертификатам разрешен доступ.Поле webhooks имеет следующую структуру:
urls - массив строк с URL для отправки Webhook уведомлений.POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователяНастройки организации позволяют предоставлять доступ к документам организации сотрудникам, имеющим указанные полномочия, и информационным системам, прошедшим аутентификацию по указанным клиентским сертификатам.
Подробнее о методах аутентификации и настройках читайте в разделе Аутентификация и контроль доступа.
Запрос (Content-Type необходимо установить в application/json):
{
"tlsCertificatesList": [
{
"description": "First certificate",
"body": "PEM-ENCODED-CERT-1",
"disabled": false
},
{
"description": "Second certificate",
"body": "PEM-ENCODED-CERT-2",
"disabled": false
},
{
"description": "Third certificate",
"body": "PEM-ENCODED-CERT-3",
"disabled": true
},
],
"documentsAccess": {
"authorities": ["OID1", "OID2"],
"tlsCertificatesIndices": [0]
},
"documentsList": {
"authorities": ["OID1", "OID2"],
"tlsCertificatesIndices": [0, 1]
},
"documentsSettings": {
"authorities": ["OID1", "OID2"],
"tlsCertificatesIndices": [1]
},
"organizationSettings": {
"authorities": ["OID1", "OID2"],
"tlsCertificatesIndices": [1]
},
"webhooks":{
"urls":["https://example.com/webhook-for-sigex","http://192.168.1.12"]
},
"dataArchiveEnabled": true,
"dataArchiveContactEmail": "orgArchiver@example.com"
}
tlsCertificatesList - массив клиентских сертификатов информационных систем;documentsAccess - контроль доступа к документам организации;documentsList - контроль доступа к перечислению документов организации;documentsSettings - контроль доступа к редактированию настроек документов организации;organizationSettings - контроль доступа к просмотру и редактированию настроек организации;webhooks - параметры доставки Webhook уведомлений;dataArchiveEnabled - новое значение флага, позволяющего включить/отключить архивирование подписанных данных;dataArchiveContactEmail - новый электронный адрес для отправки уведомлений, связанных с архивированием данных.Элементы массива tlsCertificatesList хранят информацию о сертификатах, которые информационные системы могут использовать для клиентской TLS аутентификации и имеют следующую структуру:
description - описание;body - сертификат в формате PEM, то есть строка;disabled - флаг помечающий сертификат как отключенный.Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру:
authorities - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа;tlsCertificatesIndices - массив индексов сертификатов из tlsCertificatesList, определяет по каким сертификатам разрешен доступ.Поле webhooks имеет следующую структуру:
urls - массив строк с URL для отправки Webhook уведомлений.Ответ:
{
"businessId": "BIN123456789012",
"modifiedAt": 1585827107000
}
businessId - БИН организации;modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch.GET /api/organizationSettingsAudit?lastEventId=X - аудит изменений настроек организацииlastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.Возвращает журнал изменений настроек организации.
Ответ:
{
"businessId": "BIN112233445566",
"eventsTotal": 3,
"events": []
}
businessId - БИН организации;eventsTotal - количество изменений зарегистрированных в системе;events - массив объектов описывающих изменения.Структура объектов описывающих изменения:
{
"eventId": 1,
"original": {},
"modified": {},
"modifiedBy": "IIN123456789",
"modifiedByDigest": "XXXXXXXXXXXXXXX",
"modifiedAt": 1586167317737
}
eventId - идентификатор события;original - настройки до изменения;modified - настройки после изменения;modifiedBy - кем были произведены изменения, ИИН;modifiedByDigest - хеш клиентского сертификата в том случае, если изменение было выполненой от имени информационной системы;modifiedAt - момент изменения в миллисекундах с UNIX Epoch.GET /api/organizationPermissions - получить права аутентифицированного пользователя в разрезе его организацииОтвет:
{
"documentsAccess": true,
"documentsList": true,
"documentsSettings": true,
"organizationSettings": true
}
documentsAccess - имеет ли текущий аутентифицированный пользователь доступ к документам организации;documentsList - имеет ли текущий аутентифицированный пользователь право перечислять документы организации;documentsSettings - имеет ли текущий аутентифицированный пользователь право менять настройки документов организации;organizationSettings - имеет ли текущий аутентифицированный пользователь право менять настройки организации.GET /api/idFromFileName/?name=XXX - получить идентификатор SIGEX из имени файлаname=XXX - имя файла из которого необходимо извлечь идентификатор.Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm"
}
documentId - полученный из имени файла идентификатор документа.GET /api/externalServicesStats - статистика доступности сторонних сервисовСервис постоянно поддерживает текущую статистику доступности различных сторонних сервисов, таких как OCSP и TSP НУЦ РК. Статистика формируется за некий определенный промежуток времени, обычно от 10 до 30 минут.
Для того, чтобы не раскрывать лишней информации, но при этом предотсавлять полезную статистику, мы решили выделить следующие статусы доступности:
"white" - наш сервис в последнее время не обращался к данному сервису, статистика не доступна;"green" - в последнее время все обращения к сервису были успешны;"yellow" - в последнее время были как успешные, так и не успешные (включая сетевые проблемы и неожиданные коды или ответы) обращения к сервису;"red" - в последнее время были только не успешные (включая сетевые проблемы и неожиданные коды или ответы) обращения к сервису.Ответ:
[
{
"protocol": "ocsp",
"url": "http://ocsp.pki.gov.kz",
"status": "yellow"
},
{
"protocol": "tsp",
"url": "http://tsp.pki.gov.kz",
"status": "green"
}
]
protocol - протокол, такой как "ocsp", "tsp", либо какой-то другой;url - URL стороннего сервиса;status - состояние доступности в последнее время, может быть "white", "green", "yellow" или "red".GET /api/strings - перечень известных строкОтвет:
{
"errorMessages": {
"Access denied": {
"ru": "доступ запрещен",
"description": "сервис возвращает эту ошибку при попытке выполнить действие, для выполнения которого у текущего аутентифицированного пользователя или ИС не достаточно прав"
},
...
"User does not represent an organization": {
"ru": "пользователь не является представителем организации",
"description": "эту ошибку сервис вернет при попытке поиска документов организации пользователем без достаточных прав, в частности в том случае когда его сертификат не содержит БИН в имени владельца или в сертификате не указаны необходимые полномочия"
}
},
"consts": {
"OIDs": {
"1.2.398.3.10.1.1.1.1": {
"ru": "Ключ ГОСТ 34.310-2004"
},
...
"1.3.6.1.5.5.7.3.9": {
"ru": "Подписание OCSP ответов"
}
},
"policyOIDs": {
"1.2.398.3.3.2.1": {
"ru": "Юридическое лицо"
},
...
"1.2.398.5.19.1.2.2.1.2": {
"ru": "ЭЦП информационной системы К2"
}
},
"timeStampPolicyOIDs": {
"1.2.398.3.3.2.6.1": {
"ru": "Политика для подписи квитанции метки времени на алгоритме ГОСТ 34.310-2004 с OID 1.2.398.3.10.1.1.1.2"
},
...
"1.2.398.3.3.2.6.3": {
"ru": "Политика для подписи квитанции метки времени на алгоритме ГОСТ 34.310-2004 с OID 1.3.6.1.4.1.6801.1.2.2"
}
},
"extKeyUsageOIDs": {
"1.2.398.3.3.4.1.1": {
"ru": "Физическое лицо"
},
...
"1.3.6.1.5.5.7.3.9": {
"ru": "Подписание OCSP ответов"
}
},
"signatureAlgorithmOIDs": {
"1.2.398.3.10.1.1.1.2": {
"ru": "Подпись ГОСТ 34.310-2004"
},
...
"1.2.840.113549.1.1.11": {
"ru": "Подпись RSA с SHA256"
}
},
"ncaAuthorityOIDs": {
"1.2.398.3.3.4.1.2.1": {
"ru": "Первый руководитель"
},
...
"1.2.398.3.3.4.1.2.5": {
"ru": "Сотрудник организации"
}
},
"keyUsages": {
"cRLSign": {
"ru": "Подписание CRL"
},
...
"nonRepudiation": {
"ru": "Неотрекаемость"
}
}
}
}
errorMessages - реестр всех сообщений об ошибках, которые может возвращать сервис в виде объекта, поля которого - строки сообщений, а значения содержат перевод и описание;consts - реестр известных OIDов и других специфических строк, поля - строки, значения содержат перевод:
OIDs - все известные OIDы,policyOIDs - OIDы политик сертификатов,timeStampPolicyOIDs - OIDы политик TSP,extKeyUsageOIDs - OIDы значений расширенного использования ключа,signatureAlgorithmOIDs - OIDы алгоритмов ЭЦП,ncaAuthorityOIDs - OIDы полномочий НУЦ,keyUsages - константы использования ключа.GET /api/version - версия сервисаОтвет:
{
"version":"vX.X.X",
"buildTimeStamp":"XXXXXXXXXX"
}
version - версия сервиса;buildTimeStamp - время сборки сервиса в секундах с UNIX Epoch.Портал SIGEX использует файлы cookie и другие технологии хранения данных в браузере только для персонализации пользовательского опыта: отображения уведомлений, напоминаний и подсказок, а так же хранения некоторых настроек. Мы не используем этих технологий для слежения за своими пользователями, сбора о них информации или отображения рекламы и не предоставляем подобных возможностей третим сторонам. Детали изложены в Политике конфиденциальности.
Мы разыгрываем два устройства KAZTOKEN каждую неделю!