Главная – Руководство пользователя NCALayer

Главная - Руководство пользователя NCALayer Сертификаты
На чтение 26 мин. Просмотров 8 Опубликовано
Содержание
  1. # аутентификация информационных систем двусторонним tls
  2. # аутентификация пользователей и информационных систем
  3. # аутентификация пользователей по цифровым сертификатам нуц
  4. # известные oidы применяемые в нуц рк
  5. # контроль доступа
  6. # перечень возможных сообщений об ошибках
  7. # сообщения об ошибках
  8. #get/api/?from=xxx&until=yyy&organization=true – перечисление документов аутентифицированного пользователя
  9. #get/api/{id}/buildfilename?name=xxx – сформировать имя файла с идентификатором sigex
  10. #get/api/{id}/settingsaudit?lasteventid=x – аудит изменений настроек документа
  11. #get/api/{id}/signature/{signid}?signformat=x – экспорт одной подписи документа
  12. #get/api/{id}?lastsignid=x – получение данных о зарегистрированном документе
  13. #get/api/auth – текущее состояние аутентификации
  14. #get/api/externalservicesstats – статистика доступности сторонних сервисов
  15. #get/api/idfromfilename/?name=xxx – получить идентификатор sigex из имени файла
  16. #get/api/organizationpermissions – получить права аутентифицированного пользователя в разрезе его организации
  17. #get/api/organizationsettings – получить настройки организации аутентифицированного пользователя
  18. #get/api/organizationsettingsaudit?lasteventid=x – аудит изменений настроек организации
  19. #get/api/settings – получить настройки аутентифицированного пользователя
  20. #get/api/settingsaudit?lasteventid=x – аудит изменений настроек пользователя
  21. #get/api/strings – перечень известных строк
  22. #get/api/version – версия сервиса
  23. #post/api – регистрация нового документа в системе
  24. #post/api/{id} – добавление подписи к документу
  25. #post/api/{id}/buildddc?filename=x – формирование карточки электронного документа
  26. #post/api/{id}/data – фиксация значений хешей документа
  27. #post/api/{id}/settings – изменение настроек документа
  28. #post/api/{id}/verify – проверка подписей
  29. #post/api/auth – аутентификация
  30. #post/api/auth – аутентификация, подготовительный этап – получение блока случайных данных
  31. #post/api/auth – сброс аутентификации
  32. #post/api/exported – получение идентификаторов документа и подписи по ранее экспортированной подписи документа
  33. #post/api/organizationsettings – сохранить настройки организации аутентифицированного пользователя
  34. #post/api/parseddc?registerunknownsignatures=false – разбор карточки электронного документа
  35. #post/api/settings – сохранить настройки аутентифицированного пользователя
  36. Cистемные требования
  37. Linux
  38. Mac os x
  39. Ssl сертификат — национальный удостоверяющий центр республики казахстан
  40. Windows
  41. Браузеры
  42. Документация — национальный удостоверяющий центр республики казахстан
  43. Перечисление документов
  44. Понятия и сокращения
  45. Просмотр информации о документе
  46. Просмотр/изменение настроек документа
  47. Просмотр/изменение настроек организации
  48. Просмотр/изменение настроек пользователя

# аутентификация информационных систем двусторонним tls

Этот способ аутентификации подходит для тех сценариев, когда действия должны выполняться не от имени определенных пользователей, а от имени информационной системы, к примеру:

  • автоматизированный экспорт подписей из SIGEX в локальную БД;
  • анализ и построение отчетов о документах организации;
  • построение отчетов о действиях сотрудников организации (кто что и когда подписывал).

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

# аутентификация пользователей и информационных систем

Сервис поддерживает два механизма аутентификации:

  • аутентификация пользователей по цифровым сертификатам НУЦ – этот механизм подходит для тех случаев, когда действия выполнятся от имени пользователей (к примеру просмотр своих подписанных документов или документов сотрудников компании);
  • аутентификация информационных систем двусторонним TLS – этот механизм подходит для автоматизированных сценариев, когда действия должны выполняться не от имени определенных пользователей, а от имени информационной системы (к примеру построение отчетов о подписанных документах по расписанию).

# аутентификация пользователей по цифровым сертификатам нуц

Этот способ аутентификации подходит для тех сценариев, когда действия предполагается выполнять от имени конкретных пользователей, к примеру:

Аутентификация пользователей по цифровым сертификатам НУЦ основана на подписании пользователем блока случайных данных (nonce) и последующей проверке этой подписи. В том случае, если подпись верна, сервис может быть уверен в том, что пользователь обладает закрытым ключом соответствующим открытому ключу в сертификате (регистрационном свидетельстве) НУЦ.

За данный режим аутентификации отвечают следующие API:

Отличительной особенностью режима внешней аутентификации является то, что в этом режиме сервис SIGEX не устанавливает в своих ответах cookie с JWT токенами содержащими информацию о пользователе прошедшем аутентификацию. Детали приведены в POST/api/auth – аутентификация.

Вводная статья Аутентификация по цифровым сертификатам описывает процесс интеграции аутентификации в информационные системы в режиме внешней аутентификации.

# известные oidы применяемые в нуц рк

Реестр OID и других спеифических строк доступен на странице Известные строки.

# контроль доступа

Определены следущие типы прав доступа:

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

Полномочия первого руководителя всегда присутствуют во всех блоках контроля доступа настроек организации (POST/api/organizationSettings – сохранить настройки организации аутентифицированного пользователя). Таким образом первый руководитель всегда имеет доступ к документам и настройкам организации.

# перечень возможных сообщений об ошибках

Реестр сообщений об ошибках и других спеифических строк доступен на странице Известные строки.

# сообщения об ошибках

При возникновении ошибок все методы API возвращают сообщение об ошибке следующего формата:

  • message – текст сообщения об ошибке на английском языке;
  • requestID – идентификатор запроса.

#get/api/?from=xxx&until=yyy&organization=true – перечисление документов аутентифицированного пользователя

  • from=xxx – с какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;
  • until=yyy – до какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;
  • organization=true – опциональный параметр, определяет следует ли искать документы физического лица или организации, по умолчанию false.

Ответ сервиса зависит от значения organization:

  • false – в этом случае сервис вернет документы которые подписывал аутентифицированный пользователь (как физическое лицо либо как представитель юридического лица);
  • true – в том случае, если пользователь прошел аутентификацию с помощью сертификата представителя организации (юридического лица) и у него в сертификате присутствуют полномочия указанные в настройках организации, то метод вернет перечень документов, которые подписывали любые представители этой организации.

Сервис будет возвращать документы сортированными в порядке убывания даты их регистрации, то есть сначала самые новые.

Следует учитывать то, что данный метод возвращает ограниченное количество документов за один вызов, алгоритм получения всех документов:

  1. получить первый блок документов установив желаемые from=xxx и until=yyy;
  2. получить следующий блок докментов установив until=storedAt из последнего элемента массива документов;
  3. повторять до тех пор пока сервис не вернет пустой массив.

Ответ:

  • documentsTotal – количество документов удовлетворяющих запросу;
  • documents – массив объектов документов.

Структура объекта данных документа:

  • documentId – уникальный идентификатор документа;
  • storedAt – момент регистрации документа в системе (миллисекунд с UNIX Epoch).;
  • title – заголовок документа;
  • description – описание документа.

#get/api/{id}/buildfilename?name=xxx – сформировать имя файла с идентификатором sigex

  • {id} – идентификатор документа;
  • name=XXX – опционально, имя файла без идентификатора, если не указано, то будет использовано значение из title документа.

Ответ:

  • documentId – идентификатор документа, должен быть идентичен переданному идентификатору;
  • fileName – имя файла со встроенным идентификатором SIGEX.

#get/api/{id}/settingsaudit?lasteventid=x – аудит изменений настроек документа

  • {id} – идентификатор документа;
  • lastEventId=X – опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек документа.

Ответ:

  • documentId – идентификатор документа, должен быть идентичен переданному идентификатору;
  • eventsTotal – количество изменений зарегистрированных в системе;
  • events – массив объектов описывающих изменения.

Структура объектов описывающих изменения:

  • eventId – идентификатор события;
  • original – настройки до изменения;
  • modified – настройки после изменения;
  • modifiedBy – кем были произведены изменения, ИИН;
  • modifiedByDigest – хеш клиентского сертификата в том случае, если изменение было выполненой от имени информационной системы;
  • modifiedAt – момент изменения в миллисекундах с UNIX Epoch.

#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 – идентификатор документа, должен быть идентичен переданному идентификатору;
  • signId – уникальный идентификатор подписи в системе;
  • signType – тип подписи, поддерживается два строковых значения "cms" и "xml";
  • signFormat – формат подписи;
  • signature – в случае CMS это закодированная в base64 подпись, в случае XML – текстовое представление XML.

#get/api/{id}?lastsignid=x – получение данных о зарегистрированном документе

  • {id} – идентификатор документа;
  • lastSignId=X – опционально, последний идентификатор подписи после которого нужно возвращаться подписи.

Следует учитывать то, что данная функция возвращает ограниченное количество подписей – то есть в том случае, если подписей много, то за один вызов их получить не получится.

Алгоритм получения всех подписей:

  1. получить первый блок подписей не указывая lastSignId;
  2. получить следующий блок подписей установив lastSignId=signId из последнего элемента массива подписей;
  3. повторять до тех пор пока сервис не вернет пустой массив.

Ответ: 

{
  "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": [
  ],
}

Структура объекта данных подписи:

{
  "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": {}
}

Структура метки времени 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"
  ]
}

#get/api/auth – текущее состояние аутентификации

В случае том случае, если аутентификация пройдена и в заголовках запроса присутствовал cookiejwt, то ответ будет идентичен тому, который возвращает POST/api/auth – аутентификация.

Про сертификаты:  В России изменили форму сертификата о вакцинации против COVID-19 :: Общество :: РБК

#get/api/externalservicesstats – статистика доступности сторонних сервисов

Сервис постоянно поддерживает текущую статистику доступности различных сторонних сервисов, таких как OCSP и TSP НУЦ РК. Статистика формируется за некий определенный промежуток времени, обычно от 10 до 30 минут.

Для того, чтобы не раскрывать лишней информации, но при этом предотсавлять полезную статистику, мы решили выделить следующие статусы доступности:

  • "white" – наш сервис в последнее время не обращался к данному сервису, статистика не доступна;
  • "green" – в последнее время все обращения к сервису были успешны;
  • "yellow" – в последнее время были как успешные, так и не успешные (включая сетевые проблемы и неожиданные коды или ответы) обращения к сервису;
  • "red" – в последнее время были только не успешные (включая сетевые проблемы и неожиданные коды или ответы) обращения к сервису.

Ответ:

  • protocol – протокол, такой как "ocsp", "tsp", либо какой-то другой;
  • url – URL стороннего сервиса;
  • status – состояние доступности в последнее время, может быть "white", "green", "yellow" или "red".

#get/api/idfromfilename/?name=xxx – получить идентификатор sigex из имени файла

  • name=XXX – имя файла из которого необходимо извлечь идентификатор.

Ответ:

  • documentId – полученный из имени файла идентификатор документа.

#get/api/organizationpermissions – получить права аутентифицированного пользователя в разрезе его организации

Ответ:

  • documentsAccess – имеет ли текущий аутентифицированный пользователь доступ к документам организации;
  • documentsList – имеет ли текущий аутентифицированный пользователь право перечислять документы организации;
  • documentsSettings – имеет ли текущий аутентифицированный пользователь право менять настройки документов организации;
  • organizationSettings – имеет ли текущий аутентифицированный пользователь право менять настройки организации.

#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, определяет по каким сертификатам разрешен доступ.

#get/api/organizationsettingsaudit?lasteventid=x – аудит изменений настроек организации

  • lastEventId=X – опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек организации.

Ответ:

  • businessId – БИН организации;
  • eventsTotal – количество изменений зарегистрированных в системе;
  • events – массив объектов описывающих изменения.

Структура объектов описывающих изменения:

  • eventId – идентификатор события;
  • original – настройки до изменения;
  • modified – настройки после изменения;
  • modifiedBy – кем были произведены изменения, ИИН;
  • modifiedByDigest – хеш клиентского сертификата в том случае, если изменение было выполненой от имени информационной системы;
  • modifiedAt – момент изменения в миллисекундах с UNIX Epoch.

#get/api/settings – получить настройки аутентифицированного пользователя

Ответ:

#get/api/settingsaudit?lasteventid=x – аудит изменений настроек пользователя

  • lastEventId=X – опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек пользователя.

Ответ:

Структура объектов описывающих изменения:

  • eventId – идентификатор события;
  • original – настройки до изменения;
  • modified – настройки после изменения;
  • modifiedAt – момент изменения в миллисекундах с UNIX Epoch.

#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 – версия сервиса;
  • buildTimeStamp – время сборки сервиса в секундах с UNIX Epoch.

#post/api – регистрация нового документа в системе

Важно! Регистрация документа не будет завершена до успешного вызова POST/api/{id}/data.

В рамках регистрации нового документа и его первой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.

Сервис допускает регистрацию двух типов подписей:

  • CMS – можно получить у NCALayer методом createCAdESFromBase64;
  • XML – можно получить у NCALayer методом signXml, но с некоторыми оговорками (см. ниже).

CMS подписи могут включать в себя подписанные данные (рекомендуется не включать данные в подпись, так как у сервиса есть ограничение на размер принимаемых данных для этого вызова), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).

Про сертификаты:  Купить шины Yokohama с бесплатным монтажом/доставкой, области и России.. В подарок - шиномонтаж или доставка

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

Сервис допускает наличие данных TSP (метка времени) в неподписываемом атрибуте CMS signature-time-stamp со значением, содержащим метку времени. Допускается наличие только одной метки времени.

Сервис допускает наличие данных OCSP (статус сертификата) в неподписываемом атрибуте CMS revocation-values со значением, содержащим в поле RevocationValues.ocspVals[0] OCSP квитанцию со статусом сертификата подписавшего. Допускается наличие только одной квитанции.

#post/api/{id} – добавление подписи к документу

  • {id} – идентификатор документа.

В рамках регистрации новой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.

Сервис допускает регистрацию двух типов подписей:

  • CMS – можно получить у NCALayer методом createCAdESFromBase64;
  • XML – можно получить у NCALayer методом signXml, но с некоторыми оговорками (см. ниже).

CMS подписи могут включать в себя подписанные данные (рекомендуется не включать данные в подпись, так как у сервиса есть ограничение на размер принимаемых данных для этого вызова), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).

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

Сервис допускает наличие данных TSP (метка времени) в неподписываемом атрибуте CMS signature-time-stamp со значением, содержащим метку времени. Допускается наличие только одной метки времени.

Сервис допускает наличие данных OCSP (статус сертификата) в неподписываемом атрибуте CMS revocation-values со значением, содержащим в поле RevocationValues.ocspVals[0] OCSP квитанцию со статусом сертификата подписавшего. Допускается наличие только одной квитанции.

#post/api/{id}/buildddc?filename=x – формирование карточки электронного документа

  • {id} – идентификатор документа;
  • fileName=X – опционально, имя файла для встраивания подлинника электронного документа, если не передан, будет использован заголовок документа в системе.

Сервис выполнит следующее:

  • удостоверится в том, что под документом зарегистрированы исключительно CMS подписи, так как спецификация карточки электронного документа допускает только такие подписи;
  • удостоверится в том, что зарегистрированные в сервисе подписи являются подписями именно под переданным документом (то есть что не произошло подмены или изменения документа);
  • выполнит проверку каждой подписи на момент ее регистрации в сервисе используя сохраненные данные OCSP и TSP;
  • сформирует карточку электронного документа – PDF файл, содержащий в себе подлинник электронного документа, подписи и визуализацию.

#post/api/{id}/data – фиксация значений хешей документа

  • {id} – идентификатор документа.

Сервис SIGEX не хранит подписанных документов и ему необходим какой-то способ определить относятся ли две подписи к одному и тому же документу. В том случае, когда алгоритмы подписей идентичны, это просто – в подписях присутствуют хеши документа и достаточно требовать их идентичности.

Отличаться алгоритмы подписей могут в том случае, когда один и тот же документ подписывают юридическое лицо (НУЦ выпускает в этом случае сертификаты ГОСТ 34.310-2004) и физическое лицо (НУЦ выпускает сертификаты RSA).

Выбранное нами решение – попросить передать сервису подписанный документ один раз для завершения его регистрации в системе. SIGEX вычислит все необходимые значения хешей и сохранит их в своей базе данных. Содержимое переданного документа сохранено не будет.

#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 – опциональное поле, в сертификате в подписи должен присутствовать соответствующий БИН;
  • authorities – опциональное поле, в сертификате в подписи должно присутствовать одно из указанных полномочий;
  • iin – опциональное поле, в сертификате в подписи должен присутствовать соответствующий ИИН.

В том случае, если указано несколько полей, то они ужесточают друг друга (объединяются через И).

Ответ:

  • documentId – идентификатор документа, должен быть идентичен переданному идентификатору.

#post/api/{id}/verify – проверка подписей

  • {id} – идентификатор документа.

Данный метод выполнит следующее:

  • удостоверится в том, что сохраненные в системе подписи являются подписями именно под переданным документом (то есть что не произошло подмены или изменения документа);
  • выполнит проверку каждой подписи на момент ее регистрации в системе используя сохраненные данные OCSP и TSP.

#post/api/auth – аутентификация

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

Поддерживается два режима работы:

  • внутренняя аутентификация для нужд сервиса SIGEX;
  • внешняя аутентификация для нужд сторонней информационной системы.

#post/api/auth – аутентификация, подготовительный этап – получение блока случайных данных

Аутентификация основана на подписании пользователем блока случайных данных полученных от сервиса. Подготовительный этап заключается в передаче сервису запроса на новый блок случайных данных.

Важно! Каждый блок случйных данных может быть использован только один раз и имеет ограниченный срок действия.

Вопросы интеграции аутентификации по цифровым сертификатам в информационные системы освещен в заметке Аутентификация по цифровым сертификатам

Запрос (Content-Type необходимо установить в application/json):

Ответ:

  • nonce – блок случайных данных в base64.

#post/api/auth – сброс аутентификации

Технически сброс аутентификации заключается в возврате cookie с именем jwt с пустым значением, атрибутом Max-Age установленным в 0 и атрибутом Expires содержащим дату до текущей даты. Ожидаемая реакция совместимого браузера заключается в удалении cookie с именем jwt из локального хранилища.

Запрос (Content-Type необходимо установить в application/json):

  • logout – должно быть установлено в true.

Ответ:

#post/api/exported – получение идентификаторов документа и подписи по ранее экспортированной подписи документа

В передаваемой подписи допускается наличие метки времени TSP (signature-time-stamp) и квитанции OCSP (revocation-values). Важно чтобы метка времени и квитанция, в том случае, если они присутствуют, были именно теми же, которые зарегистрированы в сервисе.

В частности поддерживаются подписи полученные следующими способами:

  • через API SIGEX с помощью запроса GET/api/{id}/signature/{signId};
  • методом createCAdESFromBase64NCALayer – такая подпись не содержит ни метки времени, ни квитанции OCSP.

Запрос (Content-Type необходимо установить в application/json):

  • signType – опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";
  • signature – в случае CMS это должна быть закодированная в base64 подпись, в случае XML – текстовое представление XML.

Ответ:

  • documentId – уникальный идентификатор документа;
  • signId – уникальный идентификатор подписи.

#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 – БИН организации;
  • modifiedAt – дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch.

#post/api/parseddc?registerunknownsignatures=false – разбор карточки электронного документа

  • registerUnknownSignatures=false – опционально, определяет должен ли сервис регистрировать новые неизвестные подписи, по умолчанию false.

Сервис выполнит следующее:

  • выполнит разбор полученного файла, удостоверится в том, что это файл карточки электронного документа;
  • проверит зарегистрированы ли в SIGEX все вложенные подписи;
  • в том случае, если были обнаружены еще не зарегистрированные вложенные подписи и registerUnknownSignatures=true, попробует их зарегистрировать, вернет ошибку в том случае, если не удалось зарегистрировать какую-либо из них;
  • в том случае, если были обнаружены еще не зарегистрированные вложенные подписи и registerUnknownSignatures=false, вернет ошибку;
  • удостоверится в том, что все вложенные подписи относятся к одному и тому же зарегистрированному в SIGEX документу;
  • удостоверится в том, что вложенные подписи являются подписями именно под вложенным в карточку документом (то есть что не произошло подмены или изменения документа);
  • выполнит проверку каждой подписи на момент ее регистрации в системе используя сохраненные данные OCSP и TSP;
  • вернет идентификатор электронного документа, идентификаторы подписей и извлеченный вложенный подлинник электронного документа.

#post/api/settings – сохранить настройки аутентифицированного пользователя

Запрос (Content-Type необходимо установить в application/json):

  • emailNotificationsEnabled – новое значение флага указывающего включена ли отправка уведомлений по электронной почте для данного пользователя;
  • email – новый электронный адрес пользователя, разрешено передавать пустую строку ("");

Ответ:

Cистемные требования

Системные требования исходят из среды выполнения для Java 8. Более подробные описания указаны по ссылкам:

Для ОС Windows и Mac OS X не требуется устанавливать Java, так как среда выполнения поставляется вместе с NCALayer.

Linux

  • Oracle Java SE Runtime Environment 8 или OpenJDK 8 OpenJFX 8 (например, для семейства Debian – пакет openjfx).

Mac os x

  • Mac OS X 10.11 и выше
  • Пространство на диске: не менее 200 МБ

Ssl сертификат — национальный удостоверяющий центр республики казахстан

В целях отказа от циркуляции бумажных носителей информации, как потенциальных источников распространения коронавируса COVID-19, сообщаем о возможности получения SSL сертификата для юридического лица без посещения НАО ГК «Правительство для граждан» (ЦОН).

Для получения SSL сертификата необходимо подать заявку, а после подтвердить ее Первым руководителем юридического лица — владельцем доменного имени в личном кабинете НУЦ РК. После подтверждения заявки на получения SSL сертификата Первым руководителем, заявка будет рассмотрена в течении одного рабочего дня.

Windows

  • Vista SP2 и выше
  • Пространство на диске: не менее 200 МБ

Браузеры

  • Все популярные браузеры с поддержкой протокола WebSocket – Firefox, Safari, IE 11, основанные на Chromium (Chrome, Opera, Yandex, Vivaldi и т.д.)

Документация — национальный удостоверяющий центр республики казахстан

Copyright © 2021 Национальный удостоверяющий центр Республики Казахстан

Перечисление документов

API перечисления документов (GET/api/?from=xxx&until=yyy&organization=true – перечисление документов аутентифицированного пользователя) с помощью параметра organization позволяет указывать какие документы следует перечислять:

  • Документы пользователя (их возможно перечислять после прохождения аутентификации по сертификату НУЦ физического, либо юридического лица) – это документы, подписанные пользователем, как физическим лицом, либо представителем юридического лица. То есть это все те документы, которые подписывал пользователь не зависимо от того, подписывал он их сертификатом физического лица или сертификатом юридического лица.
  • Документы юридического лица (их возможно перечислять после прохождения аутентификации по сертификату НУЦ юридического лица, либо информационной системой по двустороннему TLS) – это документы, подписанные сотрудниками той же организации, что пользователь или информационная система.

Во втором случае следует установить organization=true в запросе.

При перечислении документов пользователя сервис будет возвращать те документы, которые были подписаны прошедшим аутентификацию пользователем.

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

Понятия и сокращения

НУЦ РКНациональный удостоверяющий центр Республики Казахстан, обслуживающий участников «электронного правительства», государственных и негосударственных информационных систем
КУЦ РККорневой удостоверяющий центр Республики Казахстан, осуществляющий подтверждение принадлежности и действительности открытых ключей электронной цифровой подписи удостоверяющих центров
ЭЦПЭлектронная цифровая подпись ‑ набор электронных цифровых символов, созданный средствами электронной цифровой подписи и подтверждающий достоверность электронного документа, его принадлежность и неизменность содержания
Регистрационное свидетельство (сертификат)Документ на бумажном носителе или электронный документ, выдаваемый НУЦ РК для подтверждения соответствия электронной цифровой подписи требованиям, установленным нормативно-правовыми актами Республики Казахстан
Защищенный носительУстройство безопасного хранения информации, шифрование данных для которого выполняется непосредственно при записи информации на накопитель с использованием специализированного контроллера. Для доступа к информации пользователь должен указать персональный пароль.
ОСОперационная система ‑ комплекс взаимосвязанных программ, предназначенных для управления ресурсами компьютера и организации взаимодействия с пользователем
ПКПерсональный компьютер
Веб-приложениеКлиент-серверное приложение, в котором клиент взаимодействует с сервером при помощи браузера, а за сервер отвечает — веб-сервер

Просмотр информации о документе

Документ может быть публично доступным, либо с ограниченным доступом, это определяет параметр private в настройках документа (см. POST/api/{id}/settings – изменение настроек документа).

В том случае, если документ является публично доступным (private: false), то доступ к информации о нем может получить любой кто знает идентификатор документа.

В том случае, если доступ к документу ограничен (private: true), то доступ к информации о нем могут получить:

  • пользователи, прошедшие аутентификацию по сертификату НУЦ, чьи подписи присутствуют под документом (не зависимо от того, подписан ли документ с использованием сертификатом физического или юридического лица);
  • сотрудники той же организации, подпись сотрудника которой присутствует под документом, но только после прохождения аутентификации по сертификату НУЦ юридического лица и при условии того, что в сертификате, использованном для аутентификации, присутствует полномочие, указанное в блоке documentsAccess настроек этой организации (POST/api/organizationSettings – сохранить настройки организации аутентифицированного пользователя);
  • те информационные системы, которые прошли аутентификацию по двустороннему TLS и чьи сертификаты указаны в блоке documentsAccess настроек этой организации (POST/api/organizationSettings – сохранить настройки организации аутентифицированного пользователя).

Просмотр/изменение настроек документа

Просматривать и изменять настройки документа могут:

  • пользователи, прошедшие аутентификацию по сертификату НУЦ физического лица, чьи подписи с использованием сертификата физического лица присутствуют под документом;
  • пользователи, прошедшие аутентификацию по сертификату НУЦ юридического лица, чьи подписи с использованием сертификата того же самого юридического лица присутствуют под документом;
  • сотрудники той же организации, подпись сотрудника которой присутствует под документом, но только после прохождения аутентификации по сертификату НУЦ юридического лица и при условии того, что в сертификате, использованном для аутентификации, присутствует полномочие, указанное в блоке documentsSettings настроек этой организации (POST/api/organizationSettings – сохранить настройки организации аутентифицированного пользователя);
  • те информационные системы, которые прошли аутентификацию по двустороннему TLS и чьи сертификаты указаны в блоке documentsSettings настроек этой организации (POST/api/organizationSettings – сохранить настройки организации аутентифицированного пользователя).

Просмотр/изменение настроек организации

Просматривать и изменять настроки организации могут:

Просмотр/изменение настроек пользователя

Просматривать и изменять свои настройки может пользователь, выполнивший аутентификацию по сертификату НУЦ как физического, так и юридического лица.

Оцените статью
Мой сертификат
Добавить комментарий

© 2025 Мой сертификат