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 каждую неделю!