POST /api - регистрация нового документа в системеPOST /api/{id}/data - фиксация значений хешей документаGET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе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}/settings - изменение настроек документаGET /api/{id}/settingsAudit - аудит изменений настроек документаPOST /api/exported - получение идентификаторов документа и подписи по ранее экспортированной подписи документа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/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ы политик:
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 - сохранить настройки организации аутентифицированного пользователя).Просматривать и изменять настройки документа могут:
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 - идентификатор запроса.nonce, использованный при попытке аутентификации, либо не был получен от сервиса, либо просрочен, либо уже был использован.tlsCertificatesList были переданы не все сертификаты в данный момент зарегистрированные сервисом.tlsCertificatesList были передан сертификат выпущенные по неподдерживаемому алгоритму, либо с неподдерживаемой длиной ключа.tlsCertificatesIndices не корректен.POST /api - регистрация нового документа в системеВажно! Регистрация документа не будет завершена до успешного вызова POST /api/{id}/data.
В рамках регистрации нового документа и его первой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.
Сервис допускает регистрацию двух типов подписей:
CMS подписи не должны включать в себя подписанных данных (последний параметр createCMSSignatureFromBase64 и createCAdESFromBase64 следует устанавливать в false), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).
Сервис допускает наличие данных 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"
}
documentId - уникальный идентификатор зарегистрированного документа.POST /api/{id}/data - фиксация значений хешей документа{id} - идентификатор документа.Сервис SIGEX не хранит подписанных документов и ему необходим какой-то способ определить относятся ли две подписи к одному и тому же документу. В том случае, когда алгоритмы подписей идентичны, это просто - в подписях присутствуют хеши документа и достаточно требовать их идентичности. В том же случае, если алгоритмы подписей отличаются, то и значения хешей не будут совпадать, так как они вычисляются по разным алгоритмам.
Отличаться алгоритмы подписей могут в том случае, когда один и тот же документ подписывают юридическое лицо (НУЦ выпускает в этом случае сертификаты ГОСТ 34.310-2004) и физическое лицо (НУЦ выпускает сертификаты RSA).
Выбранное нами решение - попросить передать сервису подписанный документ один раз для завершения его регистрации в системе. SIGEX вычислит все необходимые значения хешей и сохранит их в своей базе данных. Содержимое переданного документа сохранено не будет.
Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream.
В качестве тела запроса следует передать оригинальный документ.
В случае XML подписи необходимо передать XML документ именно в том виде в котором он подписывался, а так же выполнить все указанные в XML подписи трансформации - сервис не будет каким-либо обрабом обрабатывать поступающие данные, он будет хешировать их “как есть”. Больше информации можно найти в стандарте https://www.w3.org/TR/xmldsig-core1.
В том случае, если при регистрации документа было указано поле emailNotifications с не пустым списокм получателей, то сервис попробует отправить уведомления получателям по электронной почте. В том случае, если размер документа не большой (ограничение определяется почтовой системой), то сервис прикрепит документ к отправляемым уведомлениям. О том, был ли прикреплен документ к отправленным уведомлениям, сигрализирует значение поля emailNotifications.attached в ответе.
Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm",
"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
}
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;digests - объект, содержащий вычисленные значения хешей;emailNotifications - опциональное поле, присутствует только в том случае, если при регистрации документа было указано аналогичное поле с не пустым списком получателей, его поле attached говорит о том, был ли прикреплен документ к отправленным уведомлениям, поле message присутствует только в том случае, если в процессе отправки уведомлений произошла ошибка и описывает эту ошибку;automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз регистрирует свою подпись на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings.GET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе{id} - идентификатор документа;lastSignId=X - опционально, последний идентификатор подписи после которого нужно возвращаться подписи.Следует учитывать то, что данная функция возвращает ограниченное количество подписей - то есть в том случае, если подписей много, то за один вызов их получить не получится.
Алгоритм получения всех подписей:
lastSignId;lastSignId=signId из последнего элемента массива подписей;Ответ:
{
"title": "document title",
"description": "document description",
"emailNotifications": {
"to": ["user@example.com","other@example.com"],
},
"settings": {
"private": false,
"signaturesLimit": 2,
"switchToPrivateAfterLimitReached": true,
"unique": ["iin"],
"signersRequirements": [
{
"iin": "IIN112233445566"
}
]
},
"signaturesTotal": 2,
"signatures": [
],
}
title - заголовок документа;description - описание документа;emailNotifications - информация о том, кому была запрошена отправка уведомлений при регистрации первой подписи;settings - объект настроек документа, описание приведено в POST /api/{id}/settings - изменение настроек документа;signaturesTotal - общее количество подписей документа;signatures - массив объектов с данными о подписях документа.Структура объекта данных подписи:
{
"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"],
"storedAt": 1568809427182,
"signId": 1,
"signType": "cms"
}
userId - ИИН подписавшего;businessId - БИН подписавшего, доступен только в случае использования сертификата юридического лица;subject - имя владельца (Subject) сертификата сформированное в соответствии с RFC 4514;subjectStructure - структурированное представление имени владельца (Subject) сертификата;signAlgorithm - OID алгоритма подписи;policyIds - массив OID-ов политик использования сертификата подписавшего;extKeyUsages - массив OID-ов расширенного использования ключа;storedAt - время сохранения подписи в системе (миллисекунд с UNIX Epoch);signId - уникальный идентификатор подписи в системе;signType - тип подписи, поддерживается два строковых значения "cms" и "xml".Структурированное представление имени владельца (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/{id} - добавление подписи к документу{id} - идентификатор документа.В рамках регистрации новой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.
Сервис допускает регистрацию двух типов подписей:
CMS подписи не должны включать в себя подписанных данных (последний параметр createCMSSignatureFromBase64 и createCAdESFromBase64 следует устанавливать в false), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).
Сервис допускает наличие данных 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",
"automaticallyCreatedUserSettings":
{
"userId": "IIN123456789012",
"emailNotificationsEnabled": true,
"email": "email@GMAIL.COM",
"modifiedAt": 1586167317737
}
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору;automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз регистрирует свою подпись на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings.POST /api/{id}/verify - проверка подписей{id} - идентификатор документа.Данный метод выполнит следующее:
Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream.
В качестве тела запроса следует передать оригинальный документ.
В случае XML подписи необходимо передать XML документ именно в том виде в котором он подписывался, а так же выполнить все указанные в XML подписи трансформации - сервис не будет каким-либо обрабом обрабатывать поступающие данные, он будет хешировать их “как есть”. Больше информации можно найти в стандарте https://www.w3.org/TR/xmldsig-core1.
Ответ:
{
"documentId": "lQsqLBaS4nQAIIMm"
}
documentId - идентификатор документа, должен быть идентичен переданному идентификатору.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}/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.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/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 - перечисление документов аутентифицированного пользователяfrom=xxx - с какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;until=yyy - до какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;organization=true - опциональный параметр, определяет следует ли искать документы физического лица или организации, по умолчанию false.Ответ сервиса зависит от значения organization:
false - в этом случае сервис вернет документы которые подписывал аутентифицированный пользователь (как физическое лицо либо как представитель юридического лица);true - в том случае, если пользователь прошел аутентификацию с помощью сертификата представителя организации (юридического лица) и у него в сертификате присутствуют полномочия указанные в настройках организации, то метод вернет перечень документов, которые подписывали любые представители этой организации.Сервис будет возвращать документы сортированными в порядке убывания даты их регистрации, то есть сначала самые новые.
Следует учитывать то, что данный метод возвращает ограниченное количество документов за один вызов, алгоритм получения всех документов:
from=xxx и until=yyy;until=storedAt из последнего элемента массива документов;Ответ:
{
"documentsTotal": 3,
"documents": []
}
documentsTotal - количество документов удовлетворяющих запросу;documents - массив объектов документов.Структура объекта данных документа:
{
"documentId": "lQsqLBaS4nQAIIMm",
"storedAt": 11111111111,
"title": "document title",
"description": "document description"
}
documentId - уникальный идентификатор документа;storedAt - момент регистрации документа в системе (миллисекунд с UNIX Epoch).;title - заголовок документа;description - описание документа.GET /api/settings - получить настройки аутентифицированного пользователяОтвет:
{
"userId": "IIN123456789012",
"emailNotificationsEnabled": true,
"email": "user@example.com",
"modifiedAt": 1585827107000
}
userId - ИИН пользователя;emailNotificationsEnabled - флаг указывающий включена ли отправка уведомлений по электронной почте для данного пользователя;email - электронный адрес пользователя, поле может содержать пустую строку ("");modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. В случае, если настройки ранее не были сохранены, то поле содержит 0.POST /api/settings - сохранить настройки аутентифицированного пользователяЗапрос (Content-Type необходимо установить в application/json):
{
"emailNotificationsEnabled": false,
"email": "otheruser@example.com"
}
emailNotificationsEnabled - новое значение флага указывающего включена ли отправка уведомлений по электронной почте для данного пользователя;email - новый электронный адрес пользователя, разрешено передавать пустую строку ("");Ответ:
{
"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]
},
"modifiedAt": 1585827107000
}
businessId - БИН организации;tlsCertificatesList - массив клиентских сертификатов информационных систем;documentsAccess - контроль доступа к документам организации;documentsList - контроль доступа к перечислению документов организации;documentsSettings - контроль доступа к редактированию настроек документов организации;organizationSettings - контроль доступа к просмотру и редактированию настроек организации;modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. В случае, если настройки ранее не были сохранены, то поле содержит 0.Элементы массива tlsCertificatesList хранят информацию о сертификатах, которые информационные системы могут использовать для клиентской TLS аутентификации и имеют следующую структуру:
description - описание;body - сертификат в формате PEM, то есть строка;disabled - флаг помечающий сертификат как отключенный.Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру:
authorities - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа;tlsCertificatesIndices - массив индексов сертификатов из tlsCertificatesList, определяет по каким сертификатам разрешен доступ.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]
}
}
tlsCertificatesList - массив клиентских сертификатов информационных систем;documentsAccess - контроль доступа к документам организации;documentsList - контроль доступа к перечислению документов организации;documentsSettings - контроль доступа к редактированию настроек документов организации;organizationSettings - контроль доступа к просмотру и редактированию настроек организации.Элементы массива tlsCertificatesList хранят информацию о сертификатах, которые информационные системы могут использовать для клиентской TLS аутентификации и имеют следующую структуру:
description - описание;body - сертификат в формате PEM, то есть строка;disabled - флаг помечающий сертификат как отключенный.Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру:
authorities - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа;tlsCertificatesIndices - массив индексов сертификатов из tlsCertificatesList, определяет по каким сертификатам разрешен доступ.Ответ:
{
"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/version - версия сервисаОтвет:
{
"version":"vX.X.X",
"buildTimeStamp":"XXXXXXXXXX"
}
version - версия сервиса;buildTimeStamp - время сборки сервиса в секундах с UNIX Epoch.Портал SIGEX использует файлы cookie и другие технологии хранения данных в браузере только для персонализации пользовательского опыта: отображения уведомлений, напоминаний и подсказок, а так же хранения некоторых настроек. Мы не используем этих технологий для слежения за своими пользователями, сбора о них информации или отображения рекламы и не предоставляем подобных возможностей третим сторонам. Детали изложены в Политике конфиденциальности.
Мы разыгрываем два устройства KAZTOKEN каждую неделю!