umcaservice / документация
umcaservice - кроссплатформенный криптографический REST API сервис на базе сертифицированной ГСССЗИ библиотеки CryptoLib для интеграции криптографии в веб-приложения.
На данный момент доступны две редакции сервиса:
- basic - свободная версия сервиса для некоммерческого использования. Основной функционал - постановка усовершенствованной или квалифицированной электронной подписи
- full - версия сервиса для коммерческого использования. Функционал - постановка и проверка усовершенствованной или квалифицированной ЭП, менеджмент сертификатов и носителей ключевой информации, направленное шифрование и расшифрование
- Windows 7 (с Service Pack 1), 8, 10, Windows Server 2012, 2016, 2019
- GNU/Linux (дистрибутивы на основе Debian, также есть серверные сборки для CentOS/RHEL)
- Mac OS X 10.13+
- iOS 13+
- Android 7+
- Постановки ЭП(чистая подпись или конверты формата CAdES BES, CAdES TS, CAdES Long C, CAdES Long X)
- Проверка конвертов ЭП, меток времени и сертификатов
- Менеджмент носителей ключевой информации(генерация и удаление ключей с сертификатами, обновление сертификатов на НКИ, изменение pin-кода)
- Направленное шифрование и расшифрование данных
- Аппаратные: устройства с интерфейсом PKCS#11
- Программные в форматах: Pfx(PKCS#12), JKS (Java Key Store), .DAT(АТ "ІІТ"), .ZS2(АЦСК "Україна")
Использование
По умолчанию, сервис имеет стандартный набор настроек и не требует дополнительных настроек, однако есть возможность дополнительного настраивания утилиты.
Основные настройки утилиты записаны в файле конфигурации, если он отсутствует - утилита создает его по пути %APPDATA%/Avtor/UmCAService/umcago.conf
для Windows
и $HOME/.umcad/umcago.conf
для Linux и Mac OS X. Также доступен веб-конфигуратор сервиса(пункт меню "Конфигурация" в меню утилиты).
В комплекте umcaservice имеются две библиотеки PKCS#11 для токенов/смарт-карт ООО "АВТОР" моделей CC337 и CC338. Для поддержки других смарт-карт или токенов необходимо добавить в список Pkcs11Modules пути к библиотекам PKCS#11 для этих устройств.
Примеры использования API доступны в виде коллекции Postman.
Также доступно демонстрационное веб-приложение UmCADemo, которое использует API umcaservice.
Параметры командной строки утилиты:
--text-mode, -t
- запустить утилиты в режиме командной строки вместо иконки в системном трее(только Linux, Mac OS X)--config path_to_config, -c path_to_config,
- указать собственный файл конфигурации--send-crashes, -s
- отправлять крэш-дампы сервиса на наш сервер обработки, чтоб мы могли устранить проблему--language lang_code, -l lang_code
- переопределить язык интерфейса сервиса (доступные значения:uk, en, de, ru, el
)--doc, -d
- запустить в режиме разработчика(в контекстном меню будет пункт, который открывает документацию)
В случае, когда сервис нештатно завершает работу - система мониторинга формирует отчет про ошибку при следующем запуске сервиса.
Все отчеты хранятся в папке %APPDATA%/Avtor/UmCAService/
для ОС Windows или $HOME/.umcad/
для Unix-систем с именами:
вида umcago_{время формирования}.crash
.
Сервис поддерживает опцию отправки отчетов про ошибки на наш сервер сбора крэш-дампов, чтоб мы имели информацию для
решения проблемы. По умолчанию эта функция отключена. Чтоб включить - необходимо запустить сервис с флажком --send-crashes
.
При этом трафик между клиентом и сервером сбора крэш-дампов защищен с помощью TLS. Важно: никакие другие персональные данные пользователя,
кроме версии сервиса, ОС, архитектуры и крэш-дампа не собираются и на сервер не передаются.
API
Взаимодействие с сервисом происходит через HHTP API, которое описано на этой странице. Корневой URI API по умолчанию: https://localhost:25989. При потребности его можно переопределить через файл конфигурации. Ниже представлены схемы API для редакций basic и full
- указывает на наличие метода только в full версии сервиса
- указывает на то, что метод использует cookie-файлы для увеличения продуктивности
- указывает на то, что метод доступен только при локальных вызовах(
Referer=localhost
)- указывает на необходимость заполнения поля
- указывает на то, что поле должно быть base64-строкой при передаче с помощью multipart/form-data или application/x-www-form-urlencoded
About
About
Получить информацию о сервисе
GET
/about
Response
application/json
AboutResponse
Struct
Name
Type
Description
Name
string
Version
string
Edition
string
Author
string
Email
string
AppID
string
OS
string
Arch
string
Certificates
CreateCertificate
Создание нового ключа и самоподписанного сертификата на ключевом носителе
POST
/certificates
Request
application/json
GenerateCertificateRequest
Struct
Структура запроса генерации нового ключа
Name
Type
Description
Pin
string
KeyRequest
KeyRequest
Запрос ключа
KeyStore
SlotInfo
НКИ для генерации ключа
Response
application/json
CertificateDescriptorWide
Struct
Расширенный дескриптор сертификата
Name
Type
Description
Base64
string
Subject
map[string]string
Словарь полей subjectRDN
Issuer
map[string]string
Словарь полей issuerRDN
DirectoryAttributes
map[string]string
Словарь расширения "атрибуты директории"
NotBefore
Timestamp
Начало действия сертификата
NotAfter
Timestamp
Окончание действия сертификата
Email
string
Email согласно RFC 822
CertificateSerialNumber
string
Серийный номер сертификата
KeyUsage
KU
Использование ключа
PublicKey
string
Открытый ключ
PublicKeyAlg
string
Алгоритм открытого ключа
KeyLength
int
Длинна ключа
CriticalEkus
[]string
Критические расширенные использования ключа
CertificatePolicies
[]string
Расширение "политики сертификата"
SubjectKeyIdentifier
string
Расширение "идентификатор ключа"
AuthorityKeyIdentifier
string
Расширение "идентификатор ключа издателя"
SubjectFingerprint
string
Хеш-сумма структуры subjectRDN
SelfSigned
bool
Определение, самоподписанный ли сертификат
AlternativeName
map[string][]string
Словарь расширения "альтернативное имя субъекта", возможные ключи словаря: "IPs", "DNSNames", "URIs", "EmailAddresses" или произвольные объектные идентификаторы
ExtendedKeyUsage
ExtendedKeyUsage
extended key usage extension
QcStatements
QcStatements
qcStatements extension
DeleteCertificate
Удаление сертификата из ключевого носителя
DELETE
/certificates
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
DeleteCertificateRequest
Struct
Структура запроса на удаление сертификата
Name
Type
Description
Certificate
[]byte
Pin
string
Response
application/json
GetCertificateStructure
Получение структуры сертификата
POST
/certificates/structure
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
CertificateStructRequest
Struct
Name
Type
Description
Certificate
[]byte
Response
application/json
CertificateDescriptor
Struct
Дескриптор сертификата
Name
Type
Description
Subject
map[string]string
Словарь полей subjectRDN
Issuer
map[string]string
Словарь полей issuerRDN
DirectoryAttributes
map[string]string
Словарь расширения "атрибуты директории"
NotBefore
Timestamp
Начало действия сертификата
NotAfter
Timestamp
Окончание действия сертификата
Email
string
Email согласно RFC 822
CertificateSerialNumber
string
Серийный номер сертификата
KeyUsage
KU
Использование ключа
PublicKey
string
Открытый ключ
PublicKeyAlg
string
Алгоритм открытого ключа
KeyLength
int
Длинна ключа
CriticalEkus
[]string
Критические расширенные использования ключа
CertificatePolicies
[]string
Расширение "политики сертификата"
SubjectKeyIdentifier
string
Расширение "идентификатор ключа"
AuthorityKeyIdentifier
string
Расширение "идентификатор ключа издателя"
SubjectFingerprint
string
Хеш-сумма структуры subjectRDN
SelfSigned
bool
Определение, самоподписанный ли сертификат
AlternativeName
map[string][]string
Словарь расширения "альтернативное имя субъекта", возможные ключи словаря: "IPs", "DNSNames", "URIs", "EmailAddresses" или произвольные объектные идентификаторы
ExtendedKeyUsage
ExtendedKeyUsage
extended key usage extension
QcStatements
QcStatements
qcStatements extension
GetCertificates
Получения списка сертификатов согласно фильтра
GET
/certificates
GetCertificatesRequest
Struct
Фильтр для поиска сертификатов в НКИ
Name
Type
Description
KsType
KsType
SubjectCN
string
SubjectSerialNumber
string
SelfSigned
bool
SubjectKeyIdentifier
string
SubjectFingerprint
string
KeyUsage
string
CertificateSerialNumber
string
SubjectUid
string
Email
string
IssuerCN
string
IssuerSN
string
Response
application/json
[]CertificateDescriptorWide
Array of CertificateDescriptorWide
UpdateCertificate
Обновление сертификата на ключевом носителе или запись идентификатора запроса на сертификат
PATCH
/certificates
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
UpdateCertificateRequest
Struct
Структура запроса обновления сертификата
Name
Type
Description
Certificate
[]byte
Pin
string
CaRequestID
string
Идентификатор запроса на получение сертификата в ЦСК
Response
application/json
Config
DeleteConfig
Удалить текущий конфигурационный файл и восстановить по-умолчанию
DELETE
/config
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
Response
application/json
GetConfig
Получение файла конфигурации
GET
/config
Response
application/json
UmCAConfig
Struct
Структура конфигурации UmCAService
Name
Type
Description
Port
int
Порт на котором стартует сервис
TLSKeyFile
string
Путь к файлу с TLS ключом PKCS#8(формат PEM)
TLSCertFile
string
Путь к файлу с TLS сертификатом (формат PEM)
IsLocal
bool
Флажок, что указывает необходимо ли запускать сервис в локальном режиме
WhiteList
[]string
Белый список разрешенных сервисов (звездочка '*' - означает не выполнять проверку Referer)
CmpServices
[]string
Cписок CMP-сервисов
TspServices
[]string
Список TSP-сервисов
FileKeyStores
[]string
Список путей к директориям с программными ключами('%/' - укороченное обозначение для всех снимаемых носителей информации, например Flash-носителей)
ProxySettings
ProxySettings
Настройки прокси
CertificateCacheDir
string
Путь к директории с кэшем сертификатов и списком отзывов сертификатов
Pkcs11Modules
[]string
Список PKCS#11 модулей
TrustedCertificatesDir
string
Путь к директории с доверенными сертификатами
IntermediateCertificatesDir
string
Путь к директории с промежуточным сертификатами
IntermediateCertificatesCmsURL
string
URL Cms - контейнер с промежуточными сертификатами
TrustedCertificatesCmsURL
string
URL Cms - контейнер с доверенными сертификатами
Log
string
Путь к файлу с логом, или пустое значение, если лог необходимо записать в STDOUT
LogLevel
int
Уровень логирования: 1 - DEBUG - максимальный уровень (в том числе наличие запросов логируется), 4 - ERRORS - уровень ошибок, 5 - OFF - без логирования
SimplifiedMode
bool
Флажок, что указывает на запуск сервиса в упрощенном режиме
UpdateConfig
Обновление файла конфигурации
POST
/config
Request
application/json
UmCAConfig
Struct
Структура конфигурации UmCAService
Name
Type
Description
Port
int
Порт на котором стартует сервис
TLSKeyFile
string
Путь к файлу с TLS ключом PKCS#8(формат PEM)
TLSCertFile
string
Путь к файлу с TLS сертификатом (формат PEM)
IsLocal
bool
Флажок, что указывает необходимо ли запускать сервис в локальном режиме
WhiteList
[]string
Белый список разрешенных сервисов (звездочка '*' - означает не выполнять проверку Referer)
CmpServices
[]string
Cписок CMP-сервисов
TspServices
[]string
Список TSP-сервисов
FileKeyStores
[]string
Список путей к директориям с программными ключами('%/' - укороченное обозначение для всех снимаемых носителей информации, например Flash-носителей)
ProxySettings
ProxySettings
Настройки прокси
CertificateCacheDir
string
Путь к директории с кэшем сертификатов и списком отзывов сертификатов
Pkcs11Modules
[]string
Список PKCS#11 модулей
TrustedCertificatesDir
string
Путь к директории с доверенными сертификатами
IntermediateCertificatesDir
string
Путь к директории с промежуточным сертификатами
IntermediateCertificatesCmsURL
string
URL Cms - контейнер с промежуточными сертификатами
TrustedCertificatesCmsURL
string
URL Cms - контейнер с доверенными сертификатами
Log
string
Путь к файлу с логом, или пустое значение, если лог необходимо записать в STDOUT
LogLevel
int
Уровень логирования: 1 - DEBUG - максимальный уровень (в том числе наличие запросов логируется), 4 - ERRORS - уровень ошибок, 5 - OFF - без логирования
SimplifiedMode
bool
Флажок, что указывает на запуск сервиса в упрощенном режиме
Response
application/json
UpdateConfigPartial
Частичное обновление конфигурации сервиса
PATCH
/config
Request
application/json
UpdateConfRequest
Struct
Структура запроса на частичное обновление поточной конфигурации сервиса
Name
Type
Description
CmpServices
[]string
TspServices
[]string
Response
application/json
Decrypt
Decrypt
Расшифрование данных
POST
/decrypt
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
DecryptRequest
Struct
Запрос на расшифрование конверта
Name
Type
Description
Data
[]byte
Зашифрованные данные, если они не прикреплены к CMS или конкатенация CMS Detached и шифрованных данных(формат .enc)
Cms
[]byte
CMS Enveloped конверт
Pin
string
Пин-код к носителю, на котором хранится ключ получателя
Response
application/octet-stream
Encrypt
Encrypt
Шифрование данных абонентов
POST
/encrypt
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
EncryptRequest
Struct
Структура запроса зашифрования данных
Name
Type
Description
Certificates
[][]byte
Сертификаты получателей
Data
[]byte
Данные для шифрования
AsBlob
bool
Флажок, что указывает формат возвращения ответа(octet-stream
если значение true
). Также может быть задан http-заголовком Accept: application/octet-stream
EncSchema
int
Схема вывода ключа шифрования, ключа для направленного шифрования ДСТУ4145, обычно 0 или 256 для совместимости
IDByIssuerSN
bool
Идентификация сертификата по серийному номеру сертификата и выдающему
AttachedData
bool
Флажок, что указывает необходимо ли прикрепить зашифрованные данные к конверту CMS Enveloped
EncryptionAlgOid
string
Идентификатор алгоритма шифрования
Response
application/octet-stream
application/json
EncryptedResponse
Struct
Структура результата шифрования; при сериализации в 'application/octet-stream' значения 'Cms' и 'EncryptedContent' конкатенируются(формат .enc)
Name
Type
Description
Cms
[]byte
EncryptedContent
[]byte
Envelope
MakeEnvelope
Создать подписанный/зашифрованный конверт
POST
/envelope/make
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
MakeEnvelopeRequest
Struct
Name
Type
Description
Files
[][]byte
Список файлов, которые необходимо прикрепить к конверту
Certificate
[]byte
Сертификат подписчика (оставить пустым, если подпись не требуется)
Pin
string
Пин-код носителя с ключом подписчика
Recipients
[][]byte
Список сертификатов шифрования получателей(оставить пустым, если шифрование не необходимо)
EncryptionAlgOid
string
oid-идентификатор симметричного алгоритма для шифрования
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/octet-stream
OpenEnvelope
Открытие подписанного/зашифрованного конверта
POST
/envelope/open
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
OpenEnvelopeRequest
Struct
Name
Type
Description
Data
[]byte
Конверт в формате AvtorEnvelope, который необходимо открыть
Pin
string
Пин-код носителя с ключом для расшифрования
Certificate
[]byte
Сертификат шифрования (или пустое его значение для автоматического его поиска в хранилище ключей пользователя)
IntendedEku
string
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование.
MustBeTimestamped
bool
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки
ValidateAsCADES
bool
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов
ValidateContentTimeStamp
bool
Флажок, что указывает на необходимость проверки метки времени на данных
PreferOCSP
bool
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке
Policy
string
Политика проверки сертификатов
Возможные значение в запросе:
default
- политика по умолчанию
stdua
- политика STDUA
qcua
- политика QCUA
czoua
- политика совместимости с ЦУО
AttachedDataAsResource
bool
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание
GenerateValidationReport
bool
Флажок, что указывает на необходимость формирования отчета проверки подписи
Response
application/octet-stream
PreOpenEnvelope
preopen a signed/ecnrypted envelope
POST
/envelope/preopen
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
PreOpenEnvelopeRequest
Struct
Name
Type
Description
Data
[]byte
Response
application/json
PreOpenEnvelopeResponse
Struct
Name
Type
Description
EnvelopeType
int
Тип конверта: 1 - подписанный, 2 - зашифрованный, 3 - и то, и другое
RecieverKeyStore
KeyStoreSlotDescriptor
Дескриптор НКИ получателя конверта
Keystores
ChangePin
Изменение пин-кода на ключевом носителе
PATCH
/keystores
Request
application/json
ChangePinRequest
Struct
Структура запроса изменения пин-кода
Name
Type
Description
OldPin
string
Старый пин-код
NewPin
string
Новый пин-код
KeyStore
KeyStoreSelector
Селектор НКИ
Response
application/json
CheckPin
Проверка пин-кода на НКИ
POST
/keystores/checkpin
Request
application/json
CheckPinRequest
Struct
Структура запроса проверки пин-кода
Name
Type
Description
Pin
string
KeyStore
KeyStoreSelector
Response
application/json
GetKeyStores
Получение списка носителей ключевой информации
GET
/keystores
GetKeyStoresRequest
Struct
Структура запроса на получение списка НКИ
Name
Type
Description
ReadCertificates
bool
Флажок, что указывает необходимо ли чтение сертификатов
EnfoldFileKeyStores
bool
Флажок, что указывает необходимо ли прочитать директории сохранения файловых носителей(настройки FileKeyStores в конфигурации) вместо непосредственно программных НКИ
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
SubjectCN
string
SubjectSerialNumber
string
SelfSigned
bool
SubjectKeyIdentifier
string
SubjectFingerprint
string
KeyUsage
string
CertificateSerialNumber
string
SubjectUid
string
Email
string
IssuerCN
string
IssuerSN
string
Response
application/json
[]KeyStoreSlotDescriptor
Array of KeyStoreSlotDescriptor
ImportKeyStore
Импортировать файл НКИ в хранилище UmCAService
POST
/keystores/import
Request
application/json
ImportKeyStoreRequest
Struct
Name
Type
Description
Data
[]byte
Файл НКИ, который должен быть импортирован
KeyStore
SlotInfo
Дескриптор ключевого хранилища. В данный момент времени поддерживаются только файловые хранилища, поэтому KeyStore.Description должен содержать путь к директории хранения ключей, а KeyStore.Hw=true. Также опционально можно указать имя файла в KeyStore.Label
Response
application/json
KeyStoreSlotDescriptor
Struct
Дескриптор НКИ
Name
Type
Description
Certs
[]CertificateDescriptorWide
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
LoadAssociatedCertificates
Загрузить ассоциированные сертификаты (создать дополнительные key11.dat-файли при необходимости)
POST
/keystores/loadcerts
Request
application/json
LoadAssociatedCertificatesRequest
Struct
Структура запроса загрузки требуемых сертификатов
Name
Type
Description
Pin
string
KeyStore
SlotInfoRequest
Response
application/json
[]CertificateDescriptorWide
Array of CertificateDescriptorWide
SelectKeyStore
Нахождение НКИ по селектору
POST
/keystores/select
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
KeyStoreSelector
Struct
Селектор носителя ключевой информации: для выбора НКИ необходимо задать сертификат или cms-конверт (зашифрованный или подписанный) или некоторые из полей дескриптора НКИ
Name
Type
Description
Certificate
[]byte
Сертификат для поиска НКИ, которому он принадлежит
Cms
[]byte
Зашифрованный или подписанный конверт в формате CMS для поиска НКИ, который содержит сертификат получателя или подписчика соответственно
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
Response
application/json
KeyStoreSlotDescriptor
Struct
Дескриптор НКИ
Name
Type
Description
Certs
[]CertificateDescriptorWide
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
Log
GetLog
Получение файла с логом (если есть)
GET
/log
Response
application/json
Sign
CreateMultipleSignatures
Подписать пакет документов
POST
/sign/multiple
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
MultipleSignaturesRequest
Struct
Структура запроса для пакетной подписи
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
MultipleData
[][]byte
Массив документов для подписи
MultipleCms
[][]byte
Список существующих конвертов подписи для добавления новых подписей
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/json
[][]byte
CreateSignature
Подписание документа (новый или существующий)
POST
/sign
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
SignatureRequest
Struct
Структура запроса на получение ЭЦП
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
Cms
[]byte
Существующий конверт, который необходимо подписать (или оставить пустым, если необходимо создать новый)
Data
[]byte
Данные для подписи
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
AsBlob
bool
Флажок, что указывает формат возвращения ответа(octet-stream
если значение true
). Также может быть задан http-заголовком Accept: application/octet-stream
AsResource
bool
Флажок, что указывает на необходимость создания файла с подписью в кэше, ответ должен содержать ссылку на созданный ресурс
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/octet-stream
application/json
GetSignatureFile
Загрузить файл с подписью или прикрепленные к конверту данные
GET
/sign/:id
Response
application/octet-stream
application/pdf
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/x-pkcs7-signature
Verify
Verify
Проверка подписанного документа или сертификата
POST
/verify
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
ValidationRequest
Struct
Структура запроса проверки cms-конверта или сертификата
Name
Type
Description
Certificate
[]byte
Сертификат для проверки (указывать, только если необходима проверка только сертификата, а не конверта)
Data
[]byte
Данные, которые подписывались (только если они отсутствуют в конверте)
Cms
[]byte
CMS-конверт для проверки(возможно расширенный до CADES-C(X) Long)
IntendedEku
string
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование.
MustBeTimestamped
bool
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки
ValidateAsCADES
bool
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов
ValidateContentTimeStamp
bool
Флажок, что указывает на необходимость проверки метки времени на данных
PreferOCSP
bool
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке
Policy
string
Политика проверки сертификатов
Возможные значение в запросе:
default
- политика по умолчанию
stdua
- политика STDUA
qcua
- политика QCUA
czoua
- политика совместимости с ЦУО
AttachedDataAsResource
bool
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание
GenerateValidationReport
bool
Флажок, что указывает на необходимость формирования отчета проверки подписи
Response
application/json
ValidationResponse
Struct
Name
Type
Description
Status
string
Общий статус проверки:
Ok если конверт или сертификат прошли валидацию полностью
Nok если конверт прошел валидацию частично, то есть существуют проблемы с валидацией отдельных сертификатов подписчиков или меток времени
текcт ошибки если конверт не прошел базовый этап валидации(испорченный формат, отсутствие данных и т.д.), если проверялся только сертификат - ошибка при валидации сертификата
Signers
[]SignerInfo
Массив с информацией про подписчиков (только при проверке CMS)
AttachedData
AttachedData
Прикрепленные к конверту данные(байтовый массив или url)
ValidationReportURL
string
ссылка на отчет о проверке подписи
About
Получить информацию о сервисе
AboutResponse
Struct
Name | Type | Description | |
---|---|---|---|
Name |
string
|
||
Version |
string
|
||
Edition |
string
|
||
Author |
string
|
||
Email |
string
|
||
AppID |
string
|
||
OS |
string
|
||
Arch |
string
|
CreateCertificate
Создание нового ключа и самоподписанного сертификата на ключевом носителе
GenerateCertificateRequest
Struct
Name | Type | Description | |
---|---|---|---|
Pin |
string
|
||
KeyRequest |
KeyRequest
|
Запрос ключа | |
KeyStore |
SlotInfo
|
НКИ для генерации ключа |
CertificateDescriptorWide
Struct
Name | Type | Description | |
---|---|---|---|
Base64 |
string
|
||
Subject |
map[string]string
|
Словарь полей subjectRDN | |
Issuer |
map[string]string
|
Словарь полей issuerRDN | |
DirectoryAttributes |
map[string]string
|
Словарь расширения "атрибуты директории" | |
NotBefore |
Timestamp
|
Начало действия сертификата | |
NotAfter |
Timestamp
|
Окончание действия сертификата | |
Email |
string
|
Email согласно RFC 822 | |
CertificateSerialNumber |
string
|
Серийный номер сертификата | |
KeyUsage |
KU
|
Использование ключа | |
PublicKey |
string
|
Открытый ключ | |
PublicKeyAlg |
string
|
Алгоритм открытого ключа | |
KeyLength |
int
|
Длинна ключа | |
CriticalEkus |
[]string
|
Критические расширенные использования ключа | |
CertificatePolicies |
[]string
|
Расширение "политики сертификата" | |
SubjectKeyIdentifier |
string
|
Расширение "идентификатор ключа" | |
AuthorityKeyIdentifier |
string
|
Расширение "идентификатор ключа издателя" | |
SubjectFingerprint |
string
|
Хеш-сумма структуры subjectRDN | |
SelfSigned |
bool
|
Определение, самоподписанный ли сертификат | |
AlternativeName |
map[string][]string
|
Словарь расширения "альтернативное имя субъекта", возможные ключи словаря: "IPs", "DNSNames", "URIs", "EmailAddresses" или произвольные объектные идентификаторы | |
ExtendedKeyUsage |
ExtendedKeyUsage
|
extended key usage extension | |
QcStatements |
QcStatements
|
qcStatements extension |
DeleteCertificate
Удаление сертификата из ключевого носителя
DeleteCertificateRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
||
Pin |
string
|
GetCertificateStructure
Получение структуры сертификата
CertificateStructRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
CertificateDescriptor
Struct
Name | Type | Description | |
---|---|---|---|
Subject |
map[string]string
|
Словарь полей subjectRDN | |
Issuer |
map[string]string
|
Словарь полей issuerRDN | |
DirectoryAttributes |
map[string]string
|
Словарь расширения "атрибуты директории" | |
NotBefore |
Timestamp
|
Начало действия сертификата | |
NotAfter |
Timestamp
|
Окончание действия сертификата | |
Email |
string
|
Email согласно RFC 822 | |
CertificateSerialNumber |
string
|
Серийный номер сертификата | |
KeyUsage |
KU
|
Использование ключа | |
PublicKey |
string
|
Открытый ключ | |
PublicKeyAlg |
string
|
Алгоритм открытого ключа | |
KeyLength |
int
|
Длинна ключа | |
CriticalEkus |
[]string
|
Критические расширенные использования ключа | |
CertificatePolicies |
[]string
|
Расширение "политики сертификата" | |
SubjectKeyIdentifier |
string
|
Расширение "идентификатор ключа" | |
AuthorityKeyIdentifier |
string
|
Расширение "идентификатор ключа издателя" | |
SubjectFingerprint |
string
|
Хеш-сумма структуры subjectRDN | |
SelfSigned |
bool
|
Определение, самоподписанный ли сертификат | |
AlternativeName |
map[string][]string
|
Словарь расширения "альтернативное имя субъекта", возможные ключи словаря: "IPs", "DNSNames", "URIs", "EmailAddresses" или произвольные объектные идентификаторы | |
ExtendedKeyUsage |
ExtendedKeyUsage
|
extended key usage extension | |
QcStatements |
QcStatements
|
qcStatements extension |
GetCertificates
Получения списка сертификатов согласно фильтра
GetCertificatesRequest
Struct
Name | Type | Description | |
---|---|---|---|
KsType |
KsType
|
||
SubjectCN |
string
|
||
SubjectSerialNumber |
string
|
||
SelfSigned |
bool
|
||
SubjectKeyIdentifier |
string
|
||
SubjectFingerprint |
string
|
||
KeyUsage |
string
|
||
CertificateSerialNumber |
string
|
||
SubjectUid |
string
|
||
Email |
string
|
||
IssuerCN |
string
|
||
IssuerSN |
string
|
[]CertificateDescriptorWide
Array of CertificateDescriptorWide
UpdateCertificate
Обновление сертификата на ключевом носителе или запись идентификатора запроса на сертификат
UpdateCertificateRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
||
Pin |
string
|
||
CaRequestID |
string
|
Идентификатор запроса на получение сертификата в ЦСК |
Config
DeleteConfig
Удалить текущий конфигурационный файл и восстановить по-умолчанию
DELETE
/config
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
Response
application/json
GetConfig
Получение файла конфигурации
GET
/config
Response
application/json
UmCAConfig
Struct
Структура конфигурации UmCAService
Name
Type
Description
Port
int
Порт на котором стартует сервис
TLSKeyFile
string
Путь к файлу с TLS ключом PKCS#8(формат PEM)
TLSCertFile
string
Путь к файлу с TLS сертификатом (формат PEM)
IsLocal
bool
Флажок, что указывает необходимо ли запускать сервис в локальном режиме
WhiteList
[]string
Белый список разрешенных сервисов (звездочка '*' - означает не выполнять проверку Referer)
CmpServices
[]string
Cписок CMP-сервисов
TspServices
[]string
Список TSP-сервисов
FileKeyStores
[]string
Список путей к директориям с программными ключами('%/' - укороченное обозначение для всех снимаемых носителей информации, например Flash-носителей)
ProxySettings
ProxySettings
Настройки прокси
CertificateCacheDir
string
Путь к директории с кэшем сертификатов и списком отзывов сертификатов
Pkcs11Modules
[]string
Список PKCS#11 модулей
TrustedCertificatesDir
string
Путь к директории с доверенными сертификатами
IntermediateCertificatesDir
string
Путь к директории с промежуточным сертификатами
IntermediateCertificatesCmsURL
string
URL Cms - контейнер с промежуточными сертификатами
TrustedCertificatesCmsURL
string
URL Cms - контейнер с доверенными сертификатами
Log
string
Путь к файлу с логом, или пустое значение, если лог необходимо записать в STDOUT
LogLevel
int
Уровень логирования: 1 - DEBUG - максимальный уровень (в том числе наличие запросов логируется), 4 - ERRORS - уровень ошибок, 5 - OFF - без логирования
SimplifiedMode
bool
Флажок, что указывает на запуск сервиса в упрощенном режиме
UpdateConfig
Обновление файла конфигурации
POST
/config
Request
application/json
UmCAConfig
Struct
Структура конфигурации UmCAService
Name
Type
Description
Port
int
Порт на котором стартует сервис
TLSKeyFile
string
Путь к файлу с TLS ключом PKCS#8(формат PEM)
TLSCertFile
string
Путь к файлу с TLS сертификатом (формат PEM)
IsLocal
bool
Флажок, что указывает необходимо ли запускать сервис в локальном режиме
WhiteList
[]string
Белый список разрешенных сервисов (звездочка '*' - означает не выполнять проверку Referer)
CmpServices
[]string
Cписок CMP-сервисов
TspServices
[]string
Список TSP-сервисов
FileKeyStores
[]string
Список путей к директориям с программными ключами('%/' - укороченное обозначение для всех снимаемых носителей информации, например Flash-носителей)
ProxySettings
ProxySettings
Настройки прокси
CertificateCacheDir
string
Путь к директории с кэшем сертификатов и списком отзывов сертификатов
Pkcs11Modules
[]string
Список PKCS#11 модулей
TrustedCertificatesDir
string
Путь к директории с доверенными сертификатами
IntermediateCertificatesDir
string
Путь к директории с промежуточным сертификатами
IntermediateCertificatesCmsURL
string
URL Cms - контейнер с промежуточными сертификатами
TrustedCertificatesCmsURL
string
URL Cms - контейнер с доверенными сертификатами
Log
string
Путь к файлу с логом, или пустое значение, если лог необходимо записать в STDOUT
LogLevel
int
Уровень логирования: 1 - DEBUG - максимальный уровень (в том числе наличие запросов логируется), 4 - ERRORS - уровень ошибок, 5 - OFF - без логирования
SimplifiedMode
bool
Флажок, что указывает на запуск сервиса в упрощенном режиме
Response
application/json
UpdateConfigPartial
Частичное обновление конфигурации сервиса
PATCH
/config
Request
application/json
UpdateConfRequest
Struct
Структура запроса на частичное обновление поточной конфигурации сервиса
Name
Type
Description
CmpServices
[]string
TspServices
[]string
Response
application/json
Decrypt
Decrypt
Расшифрование данных
POST
/decrypt
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
DecryptRequest
Struct
Запрос на расшифрование конверта
Name
Type
Description
Data
[]byte
Зашифрованные данные, если они не прикреплены к CMS или конкатенация CMS Detached и шифрованных данных(формат .enc)
Cms
[]byte
CMS Enveloped конверт
Pin
string
Пин-код к носителю, на котором хранится ключ получателя
Response
application/octet-stream
Encrypt
Encrypt
Шифрование данных абонентов
POST
/encrypt
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
EncryptRequest
Struct
Структура запроса зашифрования данных
Name
Type
Description
Certificates
[][]byte
Сертификаты получателей
Data
[]byte
Данные для шифрования
AsBlob
bool
Флажок, что указывает формат возвращения ответа(octet-stream
если значение true
). Также может быть задан http-заголовком Accept: application/octet-stream
EncSchema
int
Схема вывода ключа шифрования, ключа для направленного шифрования ДСТУ4145, обычно 0 или 256 для совместимости
IDByIssuerSN
bool
Идентификация сертификата по серийному номеру сертификата и выдающему
AttachedData
bool
Флажок, что указывает необходимо ли прикрепить зашифрованные данные к конверту CMS Enveloped
EncryptionAlgOid
string
Идентификатор алгоритма шифрования
Response
application/octet-stream
application/json
EncryptedResponse
Struct
Структура результата шифрования; при сериализации в 'application/octet-stream' значения 'Cms' и 'EncryptedContent' конкатенируются(формат .enc)
Name
Type
Description
Cms
[]byte
EncryptedContent
[]byte
Envelope
MakeEnvelope
Создать подписанный/зашифрованный конверт
POST
/envelope/make
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
MakeEnvelopeRequest
Struct
Name
Type
Description
Files
[][]byte
Список файлов, которые необходимо прикрепить к конверту
Certificate
[]byte
Сертификат подписчика (оставить пустым, если подпись не требуется)
Pin
string
Пин-код носителя с ключом подписчика
Recipients
[][]byte
Список сертификатов шифрования получателей(оставить пустым, если шифрование не необходимо)
EncryptionAlgOid
string
oid-идентификатор симметричного алгоритма для шифрования
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/octet-stream
OpenEnvelope
Открытие подписанного/зашифрованного конверта
POST
/envelope/open
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
OpenEnvelopeRequest
Struct
Name
Type
Description
Data
[]byte
Конверт в формате AvtorEnvelope, который необходимо открыть
Pin
string
Пин-код носителя с ключом для расшифрования
Certificate
[]byte
Сертификат шифрования (или пустое его значение для автоматического его поиска в хранилище ключей пользователя)
IntendedEku
string
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование.
MustBeTimestamped
bool
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки
ValidateAsCADES
bool
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов
ValidateContentTimeStamp
bool
Флажок, что указывает на необходимость проверки метки времени на данных
PreferOCSP
bool
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке
Policy
string
Политика проверки сертификатов
Возможные значение в запросе:
default
- политика по умолчанию
stdua
- политика STDUA
qcua
- политика QCUA
czoua
- политика совместимости с ЦУО
AttachedDataAsResource
bool
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание
GenerateValidationReport
bool
Флажок, что указывает на необходимость формирования отчета проверки подписи
Response
application/octet-stream
PreOpenEnvelope
preopen a signed/ecnrypted envelope
POST
/envelope/preopen
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
PreOpenEnvelopeRequest
Struct
Name
Type
Description
Data
[]byte
Response
application/json
PreOpenEnvelopeResponse
Struct
Name
Type
Description
EnvelopeType
int
Тип конверта: 1 - подписанный, 2 - зашифрованный, 3 - и то, и другое
RecieverKeyStore
KeyStoreSlotDescriptor
Дескриптор НКИ получателя конверта
Keystores
ChangePin
Изменение пин-кода на ключевом носителе
PATCH
/keystores
Request
application/json
ChangePinRequest
Struct
Структура запроса изменения пин-кода
Name
Type
Description
OldPin
string
Старый пин-код
NewPin
string
Новый пин-код
KeyStore
KeyStoreSelector
Селектор НКИ
Response
application/json
CheckPin
Проверка пин-кода на НКИ
POST
/keystores/checkpin
Request
application/json
CheckPinRequest
Struct
Структура запроса проверки пин-кода
Name
Type
Description
Pin
string
KeyStore
KeyStoreSelector
Response
application/json
GetKeyStores
Получение списка носителей ключевой информации
GET
/keystores
GetKeyStoresRequest
Struct
Структура запроса на получение списка НКИ
Name
Type
Description
ReadCertificates
bool
Флажок, что указывает необходимо ли чтение сертификатов
EnfoldFileKeyStores
bool
Флажок, что указывает необходимо ли прочитать директории сохранения файловых носителей(настройки FileKeyStores в конфигурации) вместо непосредственно программных НКИ
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
SubjectCN
string
SubjectSerialNumber
string
SelfSigned
bool
SubjectKeyIdentifier
string
SubjectFingerprint
string
KeyUsage
string
CertificateSerialNumber
string
SubjectUid
string
Email
string
IssuerCN
string
IssuerSN
string
Response
application/json
[]KeyStoreSlotDescriptor
Array of KeyStoreSlotDescriptor
ImportKeyStore
Импортировать файл НКИ в хранилище UmCAService
POST
/keystores/import
Request
application/json
ImportKeyStoreRequest
Struct
Name
Type
Description
Data
[]byte
Файл НКИ, который должен быть импортирован
KeyStore
SlotInfo
Дескриптор ключевого хранилища. В данный момент времени поддерживаются только файловые хранилища, поэтому KeyStore.Description должен содержать путь к директории хранения ключей, а KeyStore.Hw=true. Также опционально можно указать имя файла в KeyStore.Label
Response
application/json
KeyStoreSlotDescriptor
Struct
Дескриптор НКИ
Name
Type
Description
Certs
[]CertificateDescriptorWide
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
LoadAssociatedCertificates
Загрузить ассоциированные сертификаты (создать дополнительные key11.dat-файли при необходимости)
POST
/keystores/loadcerts
Request
application/json
LoadAssociatedCertificatesRequest
Struct
Структура запроса загрузки требуемых сертификатов
Name
Type
Description
Pin
string
KeyStore
SlotInfoRequest
Response
application/json
[]CertificateDescriptorWide
Array of CertificateDescriptorWide
SelectKeyStore
Нахождение НКИ по селектору
POST
/keystores/select
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
KeyStoreSelector
Struct
Селектор носителя ключевой информации: для выбора НКИ необходимо задать сертификат или cms-конверт (зашифрованный или подписанный) или некоторые из полей дескриптора НКИ
Name
Type
Description
Certificate
[]byte
Сертификат для поиска НКИ, которому он принадлежит
Cms
[]byte
Зашифрованный или подписанный конверт в формате CMS для поиска НКИ, который содержит сертификат получателя или подписчика соответственно
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
Response
application/json
KeyStoreSlotDescriptor
Struct
Дескриптор НКИ
Name
Type
Description
Certs
[]CertificateDescriptorWide
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
Log
GetLog
Получение файла с логом (если есть)
GET
/log
Response
application/json
Sign
CreateMultipleSignatures
Подписать пакет документов
POST
/sign/multiple
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
MultipleSignaturesRequest
Struct
Структура запроса для пакетной подписи
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
MultipleData
[][]byte
Массив документов для подписи
MultipleCms
[][]byte
Список существующих конвертов подписи для добавления новых подписей
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/json
[][]byte
CreateSignature
Подписание документа (новый или существующий)
POST
/sign
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
SignatureRequest
Struct
Структура запроса на получение ЭЦП
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
Cms
[]byte
Существующий конверт, который необходимо подписать (или оставить пустым, если необходимо создать новый)
Data
[]byte
Данные для подписи
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
AsBlob
bool
Флажок, что указывает формат возвращения ответа(octet-stream
если значение true
). Также может быть задан http-заголовком Accept: application/octet-stream
AsResource
bool
Флажок, что указывает на необходимость создания файла с подписью в кэше, ответ должен содержать ссылку на созданный ресурс
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/octet-stream
application/json
GetSignatureFile
Загрузить файл с подписью или прикрепленные к конверту данные
GET
/sign/:id
Response
application/octet-stream
application/pdf
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/x-pkcs7-signature
Verify
Verify
Проверка подписанного документа или сертификата
POST
/verify
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
ValidationRequest
Struct
Структура запроса проверки cms-конверта или сертификата
Name
Type
Description
Certificate
[]byte
Сертификат для проверки (указывать, только если необходима проверка только сертификата, а не конверта)
Data
[]byte
Данные, которые подписывались (только если они отсутствуют в конверте)
Cms
[]byte
CMS-конверт для проверки(возможно расширенный до CADES-C(X) Long)
IntendedEku
string
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование.
MustBeTimestamped
bool
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки
ValidateAsCADES
bool
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов
ValidateContentTimeStamp
bool
Флажок, что указывает на необходимость проверки метки времени на данных
PreferOCSP
bool
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке
Policy
string
Политика проверки сертификатов
Возможные значение в запросе:
default
- политика по умолчанию
stdua
- политика STDUA
qcua
- политика QCUA
czoua
- политика совместимости с ЦУО
AttachedDataAsResource
bool
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание
GenerateValidationReport
bool
Флажок, что указывает на необходимость формирования отчета проверки подписи
Response
application/json
ValidationResponse
Struct
Name
Type
Description
Status
string
Общий статус проверки:
Ok если конверт или сертификат прошли валидацию полностью
Nok если конверт прошел валидацию частично, то есть существуют проблемы с валидацией отдельных сертификатов подписчиков или меток времени
текcт ошибки если конверт не прошел базовый этап валидации(испорченный формат, отсутствие данных и т.д.), если проверялся только сертификат - ошибка при валидации сертификата
Signers
[]SignerInfo
Массив с информацией про подписчиков (только при проверке CMS)
AttachedData
AttachedData
Прикрепленные к конверту данные(байтовый массив или url)
ValidationReportURL
string
ссылка на отчет о проверке подписи
DeleteConfig
Удалить текущий конфигурационный файл и восстановить по-умолчанию
GetConfig
Получение файла конфигурации
UmCAConfig
Struct
Name | Type | Description | |
---|---|---|---|
Port |
int
|
Порт на котором стартует сервис | |
TLSKeyFile |
string
|
Путь к файлу с TLS ключом PKCS#8(формат PEM) | |
TLSCertFile |
string
|
Путь к файлу с TLS сертификатом (формат PEM) | |
IsLocal |
bool
|
Флажок, что указывает необходимо ли запускать сервис в локальном режиме | |
WhiteList |
[]string
|
Белый список разрешенных сервисов (звездочка '*' - означает не выполнять проверку Referer) | |
CmpServices |
[]string
|
Cписок CMP-сервисов | |
TspServices |
[]string
|
Список TSP-сервисов | |
FileKeyStores |
[]string
|
Список путей к директориям с программными ключами('%/' - укороченное обозначение для всех снимаемых носителей информации, например Flash-носителей) | |
ProxySettings |
ProxySettings
|
Настройки прокси | |
CertificateCacheDir |
string
|
Путь к директории с кэшем сертификатов и списком отзывов сертификатов | |
Pkcs11Modules |
[]string
|
Список PKCS#11 модулей | |
TrustedCertificatesDir |
string
|
Путь к директории с доверенными сертификатами | |
IntermediateCertificatesDir |
string
|
Путь к директории с промежуточным сертификатами | |
IntermediateCertificatesCmsURL |
string
|
URL Cms - контейнер с промежуточными сертификатами | |
TrustedCertificatesCmsURL |
string
|
URL Cms - контейнер с доверенными сертификатами | |
Log |
string
|
Путь к файлу с логом, или пустое значение, если лог необходимо записать в STDOUT | |
LogLevel |
int
|
Уровень логирования: 1 - DEBUG - максимальный уровень (в том числе наличие запросов логируется), 4 - ERRORS - уровень ошибок, 5 - OFF - без логирования | |
SimplifiedMode |
bool
|
Флажок, что указывает на запуск сервиса в упрощенном режиме |
UpdateConfig
Обновление файла конфигурации
UmCAConfig
Struct
Name | Type | Description | |
---|---|---|---|
Port |
int
|
Порт на котором стартует сервис | |
TLSKeyFile |
string
|
Путь к файлу с TLS ключом PKCS#8(формат PEM) | |
TLSCertFile |
string
|
Путь к файлу с TLS сертификатом (формат PEM) | |
IsLocal |
bool
|
Флажок, что указывает необходимо ли запускать сервис в локальном режиме | |
WhiteList |
[]string
|
Белый список разрешенных сервисов (звездочка '*' - означает не выполнять проверку Referer) | |
CmpServices |
[]string
|
Cписок CMP-сервисов | |
TspServices |
[]string
|
Список TSP-сервисов | |
FileKeyStores |
[]string
|
Список путей к директориям с программными ключами('%/' - укороченное обозначение для всех снимаемых носителей информации, например Flash-носителей) | |
ProxySettings |
ProxySettings
|
Настройки прокси | |
CertificateCacheDir |
string
|
Путь к директории с кэшем сертификатов и списком отзывов сертификатов | |
Pkcs11Modules |
[]string
|
Список PKCS#11 модулей | |
TrustedCertificatesDir |
string
|
Путь к директории с доверенными сертификатами | |
IntermediateCertificatesDir |
string
|
Путь к директории с промежуточным сертификатами | |
IntermediateCertificatesCmsURL |
string
|
URL Cms - контейнер с промежуточными сертификатами | |
TrustedCertificatesCmsURL |
string
|
URL Cms - контейнер с доверенными сертификатами | |
Log |
string
|
Путь к файлу с логом, или пустое значение, если лог необходимо записать в STDOUT | |
LogLevel |
int
|
Уровень логирования: 1 - DEBUG - максимальный уровень (в том числе наличие запросов логируется), 4 - ERRORS - уровень ошибок, 5 - OFF - без логирования | |
SimplifiedMode |
bool
|
Флажок, что указывает на запуск сервиса в упрощенном режиме |
UpdateConfigPartial
Частичное обновление конфигурации сервиса
UpdateConfRequest
Struct
Name | Type | Description | |
---|---|---|---|
CmpServices |
[]string
|
||
TspServices |
[]string
|
Decrypt
Расшифрование данных
DecryptRequest
Struct
Name | Type | Description | |
---|---|---|---|
Data |
[]byte
|
Зашифрованные данные, если они не прикреплены к CMS или конкатенация CMS Detached и шифрованных данных(формат .enc) | |
Cms |
[]byte
|
CMS Enveloped конверт | |
Pin |
string
|
Пин-код к носителю, на котором хранится ключ получателя |
Encrypt
Encrypt
Шифрование данных абонентов
POST
/encrypt
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
EncryptRequest
Struct
Структура запроса зашифрования данных
Name
Type
Description
Certificates
[][]byte
Сертификаты получателей
Data
[]byte
Данные для шифрования
AsBlob
bool
Флажок, что указывает формат возвращения ответа(octet-stream
если значение true
). Также может быть задан http-заголовком Accept: application/octet-stream
EncSchema
int
Схема вывода ключа шифрования, ключа для направленного шифрования ДСТУ4145, обычно 0 или 256 для совместимости
IDByIssuerSN
bool
Идентификация сертификата по серийному номеру сертификата и выдающему
AttachedData
bool
Флажок, что указывает необходимо ли прикрепить зашифрованные данные к конверту CMS Enveloped
EncryptionAlgOid
string
Идентификатор алгоритма шифрования
Response
application/octet-stream
application/json
EncryptedResponse
Struct
Структура результата шифрования; при сериализации в 'application/octet-stream' значения 'Cms' и 'EncryptedContent' конкатенируются(формат .enc)
Name
Type
Description
Cms
[]byte
EncryptedContent
[]byte
Envelope
MakeEnvelope
Создать подписанный/зашифрованный конверт
POST
/envelope/make
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
MakeEnvelopeRequest
Struct
Name
Type
Description
Files
[][]byte
Список файлов, которые необходимо прикрепить к конверту
Certificate
[]byte
Сертификат подписчика (оставить пустым, если подпись не требуется)
Pin
string
Пин-код носителя с ключом подписчика
Recipients
[][]byte
Список сертификатов шифрования получателей(оставить пустым, если шифрование не необходимо)
EncryptionAlgOid
string
oid-идентификатор симметричного алгоритма для шифрования
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/octet-stream
OpenEnvelope
Открытие подписанного/зашифрованного конверта
POST
/envelope/open
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
OpenEnvelopeRequest
Struct
Name
Type
Description
Data
[]byte
Конверт в формате AvtorEnvelope, который необходимо открыть
Pin
string
Пин-код носителя с ключом для расшифрования
Certificate
[]byte
Сертификат шифрования (или пустое его значение для автоматического его поиска в хранилище ключей пользователя)
IntendedEku
string
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование.
MustBeTimestamped
bool
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки
ValidateAsCADES
bool
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов
ValidateContentTimeStamp
bool
Флажок, что указывает на необходимость проверки метки времени на данных
PreferOCSP
bool
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке
Policy
string
Политика проверки сертификатов
Возможные значение в запросе:
default
- политика по умолчанию
stdua
- политика STDUA
qcua
- политика QCUA
czoua
- политика совместимости с ЦУО
AttachedDataAsResource
bool
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание
GenerateValidationReport
bool
Флажок, что указывает на необходимость формирования отчета проверки подписи
Response
application/octet-stream
PreOpenEnvelope
preopen a signed/ecnrypted envelope
POST
/envelope/preopen
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
PreOpenEnvelopeRequest
Struct
Name
Type
Description
Data
[]byte
Response
application/json
PreOpenEnvelopeResponse
Struct
Name
Type
Description
EnvelopeType
int
Тип конверта: 1 - подписанный, 2 - зашифрованный, 3 - и то, и другое
RecieverKeyStore
KeyStoreSlotDescriptor
Дескриптор НКИ получателя конверта
Keystores
ChangePin
Изменение пин-кода на ключевом носителе
PATCH
/keystores
Request
application/json
ChangePinRequest
Struct
Структура запроса изменения пин-кода
Name
Type
Description
OldPin
string
Старый пин-код
NewPin
string
Новый пин-код
KeyStore
KeyStoreSelector
Селектор НКИ
Response
application/json
CheckPin
Проверка пин-кода на НКИ
POST
/keystores/checkpin
Request
application/json
CheckPinRequest
Struct
Структура запроса проверки пин-кода
Name
Type
Description
Pin
string
KeyStore
KeyStoreSelector
Response
application/json
GetKeyStores
Получение списка носителей ключевой информации
GET
/keystores
GetKeyStoresRequest
Struct
Структура запроса на получение списка НКИ
Name
Type
Description
ReadCertificates
bool
Флажок, что указывает необходимо ли чтение сертификатов
EnfoldFileKeyStores
bool
Флажок, что указывает необходимо ли прочитать директории сохранения файловых носителей(настройки FileKeyStores в конфигурации) вместо непосредственно программных НКИ
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
SubjectCN
string
SubjectSerialNumber
string
SelfSigned
bool
SubjectKeyIdentifier
string
SubjectFingerprint
string
KeyUsage
string
CertificateSerialNumber
string
SubjectUid
string
Email
string
IssuerCN
string
IssuerSN
string
Response
application/json
[]KeyStoreSlotDescriptor
Array of KeyStoreSlotDescriptor
ImportKeyStore
Импортировать файл НКИ в хранилище UmCAService
POST
/keystores/import
Request
application/json
ImportKeyStoreRequest
Struct
Name
Type
Description
Data
[]byte
Файл НКИ, который должен быть импортирован
KeyStore
SlotInfo
Дескриптор ключевого хранилища. В данный момент времени поддерживаются только файловые хранилища, поэтому KeyStore.Description должен содержать путь к директории хранения ключей, а KeyStore.Hw=true. Также опционально можно указать имя файла в KeyStore.Label
Response
application/json
KeyStoreSlotDescriptor
Struct
Дескриптор НКИ
Name
Type
Description
Certs
[]CertificateDescriptorWide
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
LoadAssociatedCertificates
Загрузить ассоциированные сертификаты (создать дополнительные key11.dat-файли при необходимости)
POST
/keystores/loadcerts
Request
application/json
LoadAssociatedCertificatesRequest
Struct
Структура запроса загрузки требуемых сертификатов
Name
Type
Description
Pin
string
KeyStore
SlotInfoRequest
Response
application/json
[]CertificateDescriptorWide
Array of CertificateDescriptorWide
SelectKeyStore
Нахождение НКИ по селектору
POST
/keystores/select
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
KeyStoreSelector
Struct
Селектор носителя ключевой информации: для выбора НКИ необходимо задать сертификат или cms-конверт (зашифрованный или подписанный) или некоторые из полей дескриптора НКИ
Name
Type
Description
Certificate
[]byte
Сертификат для поиска НКИ, которому он принадлежит
Cms
[]byte
Зашифрованный или подписанный конверт в формате CMS для поиска НКИ, который содержит сертификат получателя или подписчика соответственно
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
Response
application/json
KeyStoreSlotDescriptor
Struct
Дескриптор НКИ
Name
Type
Description
Certs
[]CertificateDescriptorWide
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
Log
GetLog
Получение файла с логом (если есть)
GET
/log
Response
application/json
Sign
CreateMultipleSignatures
Подписать пакет документов
POST
/sign/multiple
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
MultipleSignaturesRequest
Struct
Структура запроса для пакетной подписи
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
MultipleData
[][]byte
Массив документов для подписи
MultipleCms
[][]byte
Список существующих конвертов подписи для добавления новых подписей
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/json
[][]byte
CreateSignature
Подписание документа (новый или существующий)
POST
/sign
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
SignatureRequest
Struct
Структура запроса на получение ЭЦП
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
Cms
[]byte
Существующий конверт, который необходимо подписать (или оставить пустым, если необходимо создать новый)
Data
[]byte
Данные для подписи
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
AsBlob
bool
Флажок, что указывает формат возвращения ответа(octet-stream
если значение true
). Также может быть задан http-заголовком Accept: application/octet-stream
AsResource
bool
Флажок, что указывает на необходимость создания файла с подписью в кэше, ответ должен содержать ссылку на созданный ресурс
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/octet-stream
application/json
GetSignatureFile
Загрузить файл с подписью или прикрепленные к конверту данные
GET
/sign/:id
Response
application/octet-stream
application/pdf
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/x-pkcs7-signature
Verify
Verify
Проверка подписанного документа или сертификата
POST
/verify
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
ValidationRequest
Struct
Структура запроса проверки cms-конверта или сертификата
Name
Type
Description
Certificate
[]byte
Сертификат для проверки (указывать, только если необходима проверка только сертификата, а не конверта)
Data
[]byte
Данные, которые подписывались (только если они отсутствуют в конверте)
Cms
[]byte
CMS-конверт для проверки(возможно расширенный до CADES-C(X) Long)
IntendedEku
string
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование.
MustBeTimestamped
bool
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки
ValidateAsCADES
bool
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов
ValidateContentTimeStamp
bool
Флажок, что указывает на необходимость проверки метки времени на данных
PreferOCSP
bool
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке
Policy
string
Политика проверки сертификатов
Возможные значение в запросе:
default
- политика по умолчанию
stdua
- политика STDUA
qcua
- политика QCUA
czoua
- политика совместимости с ЦУО
AttachedDataAsResource
bool
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание
GenerateValidationReport
bool
Флажок, что указывает на необходимость формирования отчета проверки подписи
Response
application/json
ValidationResponse
Struct
Name
Type
Description
Status
string
Общий статус проверки:
Ok если конверт или сертификат прошли валидацию полностью
Nok если конверт прошел валидацию частично, то есть существуют проблемы с валидацией отдельных сертификатов подписчиков или меток времени
текcт ошибки если конверт не прошел базовый этап валидации(испорченный формат, отсутствие данных и т.д.), если проверялся только сертификат - ошибка при валидации сертификата
Signers
[]SignerInfo
Массив с информацией про подписчиков (только при проверке CMS)
AttachedData
AttachedData
Прикрепленные к конверту данные(байтовый массив или url)
ValidationReportURL
string
ссылка на отчет о проверке подписи
Encrypt
Шифрование данных абонентов
EncryptRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificates |
[][]byte
|
Сертификаты получателей | |
Data |
[]byte
|
Данные для шифрования | |
AsBlob |
bool
|
Флажок, что указывает формат возвращения ответа(octet-stream если значение true ). Также может быть задан http-заголовком Accept: application/octet-stream |
|
EncSchema |
int
|
Схема вывода ключа шифрования, ключа для направленного шифрования ДСТУ4145, обычно 0 или 256 для совместимости | |
IDByIssuerSN |
bool
|
Идентификация сертификата по серийному номеру сертификата и выдающему | |
AttachedData |
bool
|
Флажок, что указывает необходимо ли прикрепить зашифрованные данные к конверту CMS Enveloped | |
EncryptionAlgOid |
string
|
Идентификатор алгоритма шифрования |
EncryptedResponse
Struct
Name | Type | Description | |
---|---|---|---|
Cms |
[]byte
|
||
EncryptedContent |
[]byte
|
MakeEnvelope
Создать подписанный/зашифрованный конверт
MakeEnvelopeRequest
Struct
Name | Type | Description | |
---|---|---|---|
Files |
[][]byte
|
Список файлов, которые необходимо прикрепить к конверту | |
Certificate |
[]byte
|
Сертификат подписчика (оставить пустым, если подпись не требуется) | |
Pin |
string
|
Пин-код носителя с ключом подписчика | |
Recipients |
[][]byte
|
Список сертификатов шифрования получателей(оставить пустым, если шифрование не необходимо) | |
EncryptionAlgOid |
string
|
oid-идентификатор симметричного алгоритма для шифрования | |
SigType |
SignatureDescriptor
|
Дескриптор подписи | |
DigestAlgOid |
string
|
Идентификатор алгоритма подписи |
OpenEnvelope
Открытие подписанного/зашифрованного конверта
OpenEnvelopeRequest
Struct
Name | Type | Description | |
---|---|---|---|
Data |
[]byte
|
Конверт в формате AvtorEnvelope, который необходимо открыть | |
Pin |
string
|
Пин-код носителя с ключом для расшифрования | |
Certificate |
[]byte
|
Сертификат шифрования (или пустое его значение для автоматического его поиска в хранилище ключей пользователя) | |
IntendedEku |
string
|
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование. | |
MustBeTimestamped |
bool
|
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки | |
ValidateAsCADES |
bool
|
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов | |
ValidateContentTimeStamp |
bool
|
Флажок, что указывает на необходимость проверки метки времени на данных | |
PreferOCSP |
bool
|
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке | |
Policy |
string
|
Политика проверки сертификатов Возможные значение в запросе: default - политика по умолчаниюstdua - политика STDUAqcua - политика QCUAczoua - политика совместимости с ЦУО |
|
AttachedDataAsResource |
bool
|
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание | |
GenerateValidationReport |
bool
|
Флажок, что указывает на необходимость формирования отчета проверки подписи |
PreOpenEnvelope
preopen a signed/ecnrypted envelope
PreOpenEnvelopeRequest
Struct
Name | Type | Description | |
---|---|---|---|
Data |
[]byte
|
PreOpenEnvelopeResponse
Struct
Name | Type | Description | |
---|---|---|---|
EnvelopeType |
int
|
Тип конверта: 1 - подписанный, 2 - зашифрованный, 3 - и то, и другое | |
RecieverKeyStore |
KeyStoreSlotDescriptor
|
Дескриптор НКИ получателя конверта |
Keystores
ChangePin
Изменение пин-кода на ключевом носителе
PATCH
/keystores
Request
application/json
ChangePinRequest
Struct
Структура запроса изменения пин-кода
Name
Type
Description
OldPin
string
Старый пин-код
NewPin
string
Новый пин-код
KeyStore
KeyStoreSelector
Селектор НКИ
Response
application/json
CheckPin
Проверка пин-кода на НКИ
POST
/keystores/checkpin
Request
application/json
CheckPinRequest
Struct
Структура запроса проверки пин-кода
Name
Type
Description
Pin
string
KeyStore
KeyStoreSelector
Response
application/json
GetKeyStores
Получение списка носителей ключевой информации
GET
/keystores
GetKeyStoresRequest
Struct
Структура запроса на получение списка НКИ
Name
Type
Description
ReadCertificates
bool
Флажок, что указывает необходимо ли чтение сертификатов
EnfoldFileKeyStores
bool
Флажок, что указывает необходимо ли прочитать директории сохранения файловых носителей(настройки FileKeyStores в конфигурации) вместо непосредственно программных НКИ
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
SubjectCN
string
SubjectSerialNumber
string
SelfSigned
bool
SubjectKeyIdentifier
string
SubjectFingerprint
string
KeyUsage
string
CertificateSerialNumber
string
SubjectUid
string
Email
string
IssuerCN
string
IssuerSN
string
Response
application/json
[]KeyStoreSlotDescriptor
Array of KeyStoreSlotDescriptor
ImportKeyStore
Импортировать файл НКИ в хранилище UmCAService
POST
/keystores/import
Request
application/json
ImportKeyStoreRequest
Struct
Name
Type
Description
Data
[]byte
Файл НКИ, который должен быть импортирован
KeyStore
SlotInfo
Дескриптор ключевого хранилища. В данный момент времени поддерживаются только файловые хранилища, поэтому KeyStore.Description должен содержать путь к директории хранения ключей, а KeyStore.Hw=true. Также опционально можно указать имя файла в KeyStore.Label
Response
application/json
KeyStoreSlotDescriptor
Struct
Дескриптор НКИ
Name
Type
Description
Certs
[]CertificateDescriptorWide
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
LoadAssociatedCertificates
Загрузить ассоциированные сертификаты (создать дополнительные key11.dat-файли при необходимости)
POST
/keystores/loadcerts
Request
application/json
LoadAssociatedCertificatesRequest
Struct
Структура запроса загрузки требуемых сертификатов
Name
Type
Description
Pin
string
KeyStore
SlotInfoRequest
Response
application/json
[]CertificateDescriptorWide
Array of CertificateDescriptorWide
SelectKeyStore
Нахождение НКИ по селектору
POST
/keystores/select
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
KeyStoreSelector
Struct
Селектор носителя ключевой информации: для выбора НКИ необходимо задать сертификат или cms-конверт (зашифрованный или подписанный) или некоторые из полей дескриптора НКИ
Name
Type
Description
Certificate
[]byte
Сертификат для поиска НКИ, которому он принадлежит
Cms
[]byte
Зашифрованный или подписанный конверт в формате CMS для поиска НКИ, который содержит сертификат получателя или подписчика соответственно
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
Response
application/json
KeyStoreSlotDescriptor
Struct
Дескриптор НКИ
Name
Type
Description
Certs
[]CertificateDescriptorWide
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
Log
GetLog
Получение файла с логом (если есть)
GET
/log
Response
application/json
Sign
CreateMultipleSignatures
Подписать пакет документов
POST
/sign/multiple
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
MultipleSignaturesRequest
Struct
Структура запроса для пакетной подписи
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
MultipleData
[][]byte
Массив документов для подписи
MultipleCms
[][]byte
Список существующих конвертов подписи для добавления новых подписей
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/json
[][]byte
CreateSignature
Подписание документа (новый или существующий)
POST
/sign
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
SignatureRequest
Struct
Структура запроса на получение ЭЦП
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
Cms
[]byte
Существующий конверт, который необходимо подписать (или оставить пустым, если необходимо создать новый)
Data
[]byte
Данные для подписи
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
AsBlob
bool
Флажок, что указывает формат возвращения ответа(octet-stream
если значение true
). Также может быть задан http-заголовком Accept: application/octet-stream
AsResource
bool
Флажок, что указывает на необходимость создания файла с подписью в кэше, ответ должен содержать ссылку на созданный ресурс
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/octet-stream
application/json
GetSignatureFile
Загрузить файл с подписью или прикрепленные к конверту данные
GET
/sign/:id
Response
application/octet-stream
application/pdf
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/x-pkcs7-signature
Verify
Verify
Проверка подписанного документа или сертификата
POST
/verify
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
ValidationRequest
Struct
Структура запроса проверки cms-конверта или сертификата
Name
Type
Description
Certificate
[]byte
Сертификат для проверки (указывать, только если необходима проверка только сертификата, а не конверта)
Data
[]byte
Данные, которые подписывались (только если они отсутствуют в конверте)
Cms
[]byte
CMS-конверт для проверки(возможно расширенный до CADES-C(X) Long)
IntendedEku
string
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование.
MustBeTimestamped
bool
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки
ValidateAsCADES
bool
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов
ValidateContentTimeStamp
bool
Флажок, что указывает на необходимость проверки метки времени на данных
PreferOCSP
bool
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке
Policy
string
Политика проверки сертификатов
Возможные значение в запросе:
default
- политика по умолчанию
stdua
- политика STDUA
qcua
- политика QCUA
czoua
- политика совместимости с ЦУО
AttachedDataAsResource
bool
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание
GenerateValidationReport
bool
Флажок, что указывает на необходимость формирования отчета проверки подписи
Response
application/json
ValidationResponse
Struct
Name
Type
Description
Status
string
Общий статус проверки:
Ok если конверт или сертификат прошли валидацию полностью
Nok если конверт прошел валидацию частично, то есть существуют проблемы с валидацией отдельных сертификатов подписчиков или меток времени
текcт ошибки если конверт не прошел базовый этап валидации(испорченный формат, отсутствие данных и т.д.), если проверялся только сертификат - ошибка при валидации сертификата
Signers
[]SignerInfo
Массив с информацией про подписчиков (только при проверке CMS)
AttachedData
AttachedData
Прикрепленные к конверту данные(байтовый массив или url)
ValidationReportURL
string
ссылка на отчет о проверке подписи
ChangePin
Изменение пин-кода на ключевом носителе
ChangePinRequest
Struct
Name | Type | Description | |
---|---|---|---|
OldPin |
string
|
Старый пин-код | |
NewPin |
string
|
Новый пин-код | |
KeyStore |
KeyStoreSelector
|
Селектор НКИ |
CheckPin
Проверка пин-кода на НКИ
CheckPinRequest
Struct
Name | Type | Description | |
---|---|---|---|
Pin |
string
|
||
KeyStore |
KeyStoreSelector
|
GetKeyStores
Получение списка носителей ключевой информации
GetKeyStoresRequest
Struct
Name | Type | Description | |
---|---|---|---|
ReadCertificates |
bool
|
Флажок, что указывает необходимо ли чтение сертификатов | |
EnfoldFileKeyStores |
bool
|
Флажок, что указывает необходимо ли прочитать директории сохранения файловых носителей(настройки FileKeyStores в конфигурации) вместо непосредственно программных НКИ | |
Hw |
bool
|
Флажок, что указывает на тип НКИ(программный/аппаратный) | |
Description |
string
|
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных) | |
Label |
string
|
Метка НКИ | |
Serial |
string
|
Серийный номер НКИ (только для аппаратных) | |
SubjectCN |
string
|
||
SubjectSerialNumber |
string
|
||
SelfSigned |
bool
|
||
SubjectKeyIdentifier |
string
|
||
SubjectFingerprint |
string
|
||
KeyUsage |
string
|
||
CertificateSerialNumber |
string
|
||
SubjectUid |
string
|
||
Email |
string
|
||
IssuerCN |
string
|
||
IssuerSN |
string
|
[]KeyStoreSlotDescriptor
Array of KeyStoreSlotDescriptor
ImportKeyStore
Импортировать файл НКИ в хранилище UmCAService
ImportKeyStoreRequest
Struct
Name | Type | Description | |
---|---|---|---|
Data |
[]byte
|
Файл НКИ, который должен быть импортирован | |
KeyStore |
SlotInfo
|
Дескриптор ключевого хранилища. В данный момент времени поддерживаются только файловые хранилища, поэтому KeyStore.Description должен содержать путь к директории хранения ключей, а KeyStore.Hw=true. Также опционально можно указать имя файла в KeyStore.Label |
KeyStoreSlotDescriptor
Struct
Name | Type | Description | |
---|---|---|---|
Certs |
[]CertificateDescriptorWide
|
||
Hw |
bool
|
Флажок, что указывает на тип НКИ(программный/аппаратный) | |
Description |
string
|
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate | |
Label |
string
|
Метка НКИ(имя файла для программных НКИ в CreateCertificate) | |
Serial |
string
|
Серийный номер НКИ (только для аппаратных) |
LoadAssociatedCertificates
Загрузить ассоциированные сертификаты (создать дополнительные key11.dat-файли при необходимости)
LoadAssociatedCertificatesRequest
Struct
Name | Type | Description | |
---|---|---|---|
Pin |
string
|
||
KeyStore |
SlotInfoRequest
|
[]CertificateDescriptorWide
Array of CertificateDescriptorWide
SelectKeyStore
Нахождение НКИ по селектору
KeyStoreSelector
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
Сертификат для поиска НКИ, которому он принадлежит | |
Cms |
[]byte
|
Зашифрованный или подписанный конверт в формате CMS для поиска НКИ, который содержит сертификат получателя или подписчика соответственно | |
Hw |
bool
|
Флажок, что указывает на тип НКИ(программный/аппаратный) | |
Description |
string
|
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных) | |
Label |
string
|
Метка НКИ | |
Serial |
string
|
Серийный номер НКИ (только для аппаратных) |
KeyStoreSlotDescriptor
Struct
Name | Type | Description | |
---|---|---|---|
Certs |
[]CertificateDescriptorWide
|
||
Hw |
bool
|
Флажок, что указывает на тип НКИ(программный/аппаратный) | |
Description |
string
|
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate | |
Label |
string
|
Метка НКИ(имя файла для программных НКИ в CreateCertificate) | |
Serial |
string
|
Серийный номер НКИ (только для аппаратных) |
GetLog
Получение файла с логом (если есть)
Sign
CreateMultipleSignatures
Подписать пакет документов
POST
/sign/multiple
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
MultipleSignaturesRequest
Struct
Структура запроса для пакетной подписи
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
MultipleData
[][]byte
Массив документов для подписи
MultipleCms
[][]byte
Список существующих конвертов подписи для добавления новых подписей
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/json
[][]byte
CreateSignature
Подписание документа (новый или существующий)
POST
/sign
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
SignatureRequest
Struct
Структура запроса на получение ЭЦП
Name
Type
Description
Certificate
[]byte
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks
Cms
[]byte
Существующий конверт, который необходимо подписать (или оставить пустым, если необходимо создать новый)
Data
[]byte
Данные для подписи
Pin
string
Пин-код к НКИ с сертификатом ЭЦП
AsBlob
bool
Флажок, что указывает формат возвращения ответа(octet-stream
если значение true
). Также может быть задан http-заголовком Accept: application/octet-stream
AsResource
bool
Флажок, что указывает на необходимость создания файла с подписью в кэше, ответ должен содержать ссылку на созданный ресурс
SigType
SignatureDescriptor
Дескриптор подписи
DigestAlgOid
string
Идентификатор алгоритма подписи
Response
application/octet-stream
application/json
GetSignatureFile
Загрузить файл с подписью или прикрепленные к конверту данные
GET
/sign/:id
Response
application/octet-stream
application/pdf
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/x-pkcs7-signature
Verify
Verify
Проверка подписанного документа или сертификата
POST
/verify
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
ValidationRequest
Struct
Структура запроса проверки cms-конверта или сертификата
Name
Type
Description
Certificate
[]byte
Сертификат для проверки (указывать, только если необходима проверка только сертификата, а не конверта)
Data
[]byte
Данные, которые подписывались (только если они отсутствуют в конверте)
Cms
[]byte
CMS-конверт для проверки(возможно расширенный до CADES-C(X) Long)
IntendedEku
string
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование.
MustBeTimestamped
bool
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки
ValidateAsCADES
bool
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов
ValidateContentTimeStamp
bool
Флажок, что указывает на необходимость проверки метки времени на данных
PreferOCSP
bool
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке
Policy
string
Политика проверки сертификатов
Возможные значение в запросе:
default
- политика по умолчанию
stdua
- политика STDUA
qcua
- политика QCUA
czoua
- политика совместимости с ЦУО
AttachedDataAsResource
bool
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание
GenerateValidationReport
bool
Флажок, что указывает на необходимость формирования отчета проверки подписи
Response
application/json
ValidationResponse
Struct
Name
Type
Description
Status
string
Общий статус проверки:
Ok если конверт или сертификат прошли валидацию полностью
Nok если конверт прошел валидацию частично, то есть существуют проблемы с валидацией отдельных сертификатов подписчиков или меток времени
текcт ошибки если конверт не прошел базовый этап валидации(испорченный формат, отсутствие данных и т.д.), если проверялся только сертификат - ошибка при валидации сертификата
Signers
[]SignerInfo
Массив с информацией про подписчиков (только при проверке CMS)
AttachedData
AttachedData
Прикрепленные к конверту данные(байтовый массив или url)
ValidationReportURL
string
ссылка на отчет о проверке подписи
CreateMultipleSignatures
Подписать пакет документов
MultipleSignaturesRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks | |
MultipleData |
[][]byte
|
Массив документов для подписи | |
MultipleCms |
[][]byte
|
Список существующих конвертов подписи для добавления новых подписей | |
Pin |
string
|
Пин-код к НКИ с сертификатом ЭЦП | |
SigType |
SignatureDescriptor
|
Дескриптор подписи | |
DigestAlgOid |
string
|
Идентификатор алгоритма подписи |
[][]byte
CreateSignature
Подписание документа (новый или существующий)
SignatureRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
Сертификат, что отвечает ключу для ЭЦП или файл с ключом в формате pfx, dat, zs2, jks | |
Cms |
[]byte
|
Существующий конверт, который необходимо подписать (или оставить пустым, если необходимо создать новый) | |
Data |
[]byte
|
Данные для подписи | |
Pin |
string
|
Пин-код к НКИ с сертификатом ЭЦП | |
AsBlob |
bool
|
Флажок, что указывает формат возвращения ответа(octet-stream если значение true ). Также может быть задан http-заголовком Accept: application/octet-stream |
|
AsResource |
bool
|
Флажок, что указывает на необходимость создания файла с подписью в кэше, ответ должен содержать ссылку на созданный ресурс | |
SigType |
SignatureDescriptor
|
Дескриптор подписи | |
DigestAlgOid |
string
|
Идентификатор алгоритма подписи |
GetSignatureFile
Загрузить файл с подписью или прикрепленные к конверту данные
Verify
Проверка подписанного документа или сертификата
ValidationRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
Сертификат для проверки (указывать, только если необходима проверка только сертификата, а не конверта) | |
Data |
[]byte
|
Данные, которые подписывались (только если они отсутствуют в конверте) | |
Cms |
[]byte
|
CMS-конверт для проверки(возможно расширенный до CADES-C(X) Long) | |
IntendedEku |
string
|
Ожидаемое расширенное использование ключа. "any" - любое расширенное использование. | |
MustBeTimestamped |
bool
|
Флажок, что свидетельствует обязательность наличия метки времени в конверте и ее проверки | |
ValidateAsCADES |
bool
|
Флажок, что указывает на необходимость проверить конверт по процедуре проверки CADES-C(X) Long конвертов | |
ValidateContentTimeStamp |
bool
|
Флажок, что указывает на необходимость проверки метки времени на данных | |
PreferOCSP |
bool
|
Флажок, что указывает на необходимость предоставлять преимущество сервису OCSP вместо CRL при проверке | |
Policy |
string
|
Политика проверки сертификатов Возможные значение в запросе: default - политика по умолчаниюstdua - политика STDUAqcua - политика QCUAczoua - политика совместимости с ЦУО |
|
AttachedDataAsResource |
bool
|
Флажок, что указывает на необходимость выдачи прикрепленных данных в виде url-ссылки на скачивание | |
GenerateValidationReport |
bool
|
Флажок, что указывает на необходимость формирования отчета проверки подписи |
ValidationResponse
Struct
Name | Type | Description | |
---|---|---|---|
Status |
string
|
Общий статус проверки: Ok если конверт или сертификат прошли валидацию полностью Nok если конверт прошел валидацию частично, то есть существуют проблемы с валидацией отдельных сертификатов подписчиков или меток времени текcт ошибки если конверт не прошел базовый этап валидации(испорченный формат, отсутствие данных и т.д.), если проверялся только сертификат - ошибка при валидации сертификата |
|
Signers |
[]SignerInfo
|
Массив с информацией про подписчиков (только при проверке CMS) | |
AttachedData |
AttachedData
|
Прикрепленные к конверту данные(байтовый массив или url) | |
ValidationReportURL |
string
|
ссылка на отчет о проверке подписи |
Data Structures
KeyRequest
Struct
Запрос на ключ и сертификат
Name
Type
Description
Subject
map[string]string
Словарь, который отвечает структуре SubjectDN
DirectoryAttributes
map[string]string
Словарь, который отвечает расширению 'атрибуты директории'
Email
string
KeyUsage
KU
Использование ключа
CriticalEkus
[]string
Список критичных расширенных использований ключа (устаревшее, используйте ExtendedKeyUsage)
ValidityDays
int
Количество дней, в течении которых сертификат считается действительным
ExtendedKeyUsage
ExtendedKeyUsage
SSCDLabels
SSCDLabels
Метки генерации ключа на защищенный носитель ключевой информации
KeyParams
KeyParams
Параметры для генерации ключа
ExtendedKeyUsage
Struct
Name
Type
Description
Critical
bool
KeyPurposeIDs
[]string
note: 'Oids' replaced by 'KeyPurposeIDs' in 3.8.1
SSCDLabels
Struct
Метки генерации ключа на защищенный носитель ключевой информации
Name
Type
Description
ExtendedKeyUsageIITStyle
bool
Extended Key Usage 1.3.6.1.4.1.19398.1.1.8.23 (Avtor Secure Token)
QcStatementSSCDUkraine
bool
qcStatement id-etsi-qcs-QcSSCD
DirectoryAttributeDeviceSerialNumber
bool
Directory Attribute 1.2.804.2.1.1.1.11.1.4.7.1
KeyParams
Struct
Структура параметров ключа
Name
Type
Description
AlgOid
string
Алгоритм открытого ключа (его объектный идентификатор или сокращение), поддерживаемые на данный момент алгоритмы:
'rsa'
- 1.2.840.113549.1.1.1 (PKCS#1 RSA)
'dstu4145'
- 1.2.804.2.1.1.1.1.3.1.1 (ДСТУ 4145/2002)
'ecdsa'
- 1.2.840.10045.2.1 (X9.62 ECDSA)
KeyLen
int
Длинна ключа, выбирается автоматически, если значение пустое
Params
[]byte
Опциональные параметры, обычно значение пустое
SlotInfo
Struct
Общая информация про носитель ключевой информации
Name
Type
Description
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
QcStatement
Struct
Name
Type
Description
StatementID
string
StatementInfo
[]byte
Timestamp
Typedef
Real Type
Description
Time
Timestamp - время UTC
KU
Typedef
Real Type
Description
uint8
KU - использование ключа. В запросе может быть закодировано как символами: s, e, c
, так и 1-байтным числом
's'
- цифровая подпись [0xCO]
'e'
- шифрование/ключевой обмен [0x30/0x08]
'c'
- подпись сертификатов (ЦСК) [0x06]
KsType
Typedef
Real Type
Description
uint8
KsType - - тип ключевого хранилища
0
- все хранилища
1
- программные хранилища
2
- аппаратные хранилища
CertificateDescriptorWide
Struct
Расширенный дескриптор сертификата
Name
Type
Description
Base64
string
Subject
map[string]string
Словарь полей subjectRDN
Issuer
map[string]string
Словарь полей issuerRDN
DirectoryAttributes
map[string]string
Словарь расширения "атрибуты директории"
NotBefore
Timestamp
Начало действия сертификата
NotAfter
Timestamp
Окончание действия сертификата
Email
string
Email согласно RFC 822
CertificateSerialNumber
string
Серийный номер сертификата
KeyUsage
KU
Использование ключа
PublicKey
string
Открытый ключ
PublicKeyAlg
string
Алгоритм открытого ключа
KeyLength
int
Длинна ключа
CriticalEkus
[]string
Критические расширенные использования ключа
CertificatePolicies
[]string
Расширение "политики сертификата"
SubjectKeyIdentifier
string
Расширение "идентификатор ключа"
AuthorityKeyIdentifier
string
Расширение "идентификатор ключа издателя"
SubjectFingerprint
string
Хеш-сумма структуры subjectRDN
SelfSigned
bool
Определение, самоподписанный ли сертификат
AlternativeName
map[string][]string
Словарь расширения "альтернативное имя субъекта", возможные ключи словаря: "IPs", "DNSNames", "URIs", "EmailAddresses" или произвольные объектные идентификаторы
ExtendedKeyUsage
ExtendedKeyUsage
extended key usage extension
QcStatements
QcStatements
qcStatements extension
ProxySettings
Struct
Name
Type
Description
Host
string
Port
int
User
string
Password
string
UseSystemProxy
bool
SignatureDescriptor
Typedef
Real Type
Description
int
SignatureDescriptor - дескриптор параметров ЭЦП
Кроме числа, дескриптор подписи удобно можно задать строкой в формате: $type[-attached][-ts][-signtime][-ocsp][-$policy]
$type - [raw/cms/cades-c/cades-x/crypto-kdc]
- тип ЭЦП: raw - чистая подпись, pdf - внутренняя цифровая подпись pdf-файла, docx - подпись документа openxml office(.docx), cms - конверт в формате CmsSigned согласно PKCS#7, cades - конверт в формате CADES C(X) Long, crypto-kdc - эЦП в формате CryptoKDC
attached
- определяет прикреплены ли данные к конверту
ts
- указывает на необходимость накладывания метки времени
ts-content
- указывает на необходимость накладывания метки времени на данные(обычно не требуется, если ставится обычная метка времени)
signtime
- указывает на необходимость включения в конверт времени подписи
ocsp
- указывает на необходимость использовать ответы OCSP при формировании CAdES Long C/X - конвертов
$policy - [default/stdua/qcua/czoua]
политика валидации сертификатов(указывать при формировании CAdES Long C/X - конвертов)
(* [...]
- опциональный параметр, $a
- обозначение строчной переменной)
Примеры:
- формирование конверта с прикрепленными данными в формате CAdES Long X с политикой валидации STDUA и включением статусов OCSP с включением времени подписи: cades-x-attached-ts-signtime-ocsp-stdua
;
- обычный CAdES BES-конверт с не прикрепленными данными: cms
.
KeyStoreSlotDescriptor
Struct
Дескриптор НКИ
Name
Type
Description
Certs
[]CertificateDescriptorWide
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate
Label
string
Метка НКИ(имя файла для программных НКИ в CreateCertificate)
Serial
string
Серийный номер НКИ (только для аппаратных)
KeyStoreSelector
Struct
Селектор носителя ключевой информации: для выбора НКИ необходимо задать сертификат или cms-конверт (зашифрованный или подписанный) или некоторые из полей дескриптора НКИ
Name
Type
Description
Certificate
[]byte
Сертификат для поиска НКИ, которому он принадлежит
Cms
[]byte
Зашифрованный или подписанный конверт в формате CMS для поиска НКИ, который содержит сертификат получателя или подписчика соответственно
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
SlotInfoRequest
Struct
Фильтр для поиска НКИ
Name
Type
Description
Hw
bool
Флажок, что указывает на тип НКИ(программный/аппаратный)
Description
string
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных)
Label
string
Метка НКИ
Serial
string
Серийный номер НКИ (только для аппаратных)
SignerInfo
Struct
Информации про валидацию подписчика
Name
Type
Description
Certificate
CertificateDescriptorWide
Дескриптор сертификата подписчика
SigningTime
Timestamp
Метка времени на подпись
ContentTimeStamp
Timestamp
Метка времени на данные
ValidationStatus
string
Статус валидации подписчика:
Ok если все хорошо.
текст ошибки если что-то пошло не так (не валидная метка времени, сертификат или падение метеорита на сервер OCSP и т.д.). Детальнее про статусы валидации можно узнать из словаряValidationStatusesMap
KeyRequest
Struct
Name | Type | Description | |
---|---|---|---|
Subject |
map[string]string
|
Словарь, который отвечает структуре SubjectDN | |
DirectoryAttributes |
map[string]string
|
Словарь, который отвечает расширению 'атрибуты директории' | |
Email |
string
|
||
KeyUsage |
KU
|
Использование ключа | |
CriticalEkus |
[]string
|
Список критичных расширенных использований ключа (устаревшее, используйте ExtendedKeyUsage) | |
ValidityDays |
int
|
Количество дней, в течении которых сертификат считается действительным | |
ExtendedKeyUsage |
ExtendedKeyUsage
|
||
SSCDLabels |
SSCDLabels
|
Метки генерации ключа на защищенный носитель ключевой информации | |
KeyParams |
KeyParams
|
Параметры для генерации ключа |
ExtendedKeyUsage
Struct
Name | Type | Description | |
---|---|---|---|
Critical |
bool
|
||
KeyPurposeIDs |
[]string
|
note: 'Oids' replaced by 'KeyPurposeIDs' in 3.8.1 |
SSCDLabels
Struct
Name | Type | Description | |
---|---|---|---|
ExtendedKeyUsageIITStyle |
bool
|
Extended Key Usage 1.3.6.1.4.1.19398.1.1.8.23 (Avtor Secure Token) | |
QcStatementSSCDUkraine |
bool
|
qcStatement id-etsi-qcs-QcSSCD | |
DirectoryAttributeDeviceSerialNumber |
bool
|
Directory Attribute 1.2.804.2.1.1.1.11.1.4.7.1 |
KeyParams
Struct
Name | Type | Description | |
---|---|---|---|
AlgOid |
string
|
Алгоритм открытого ключа (его объектный идентификатор или сокращение), поддерживаемые на данный момент алгоритмы:'rsa' - 1.2.840.113549.1.1.1 (PKCS#1 RSA)'dstu4145' - 1.2.804.2.1.1.1.1.3.1.1 (ДСТУ 4145/2002)'ecdsa' - 1.2.840.10045.2.1 (X9.62 ECDSA) |
|
KeyLen |
int
|
Длинна ключа, выбирается автоматически, если значение пустое | |
Params |
[]byte
|
Опциональные параметры, обычно значение пустое |
SlotInfo
Struct
Name | Type | Description | |
---|---|---|---|
Hw |
bool
|
Флажок, что указывает на тип НКИ(программный/аппаратный) | |
Description |
string
|
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate | |
Label |
string
|
Метка НКИ(имя файла для программных НКИ в CreateCertificate) | |
Serial |
string
|
Серийный номер НКИ (только для аппаратных) |
QcStatement
Struct
Name | Type | Description | |
---|---|---|---|
StatementID |
string
|
||
StatementInfo |
[]byte
|
Timestamp
Typedef
Real Type | Description |
---|---|
Time |
Timestamp - время UTC |
KU
Typedef
Real Type | Description |
---|---|
uint8 |
KU - использование ключа. В запросе может быть закодировано как символами: s, e, c , так и 1-байтным числом's' - цифровая подпись [0xCO]'e' - шифрование/ключевой обмен [0x30/0x08]'c' - подпись сертификатов (ЦСК) [0x06] |
KsType
Typedef
Real Type | Description |
---|---|
uint8 |
KsType - - тип ключевого хранилища0 - все хранилища1 - программные хранилища2 - аппаратные хранилища |
CertificateDescriptorWide
Struct
Name | Type | Description | |
---|---|---|---|
Base64 |
string
|
||
Subject |
map[string]string
|
Словарь полей subjectRDN | |
Issuer |
map[string]string
|
Словарь полей issuerRDN | |
DirectoryAttributes |
map[string]string
|
Словарь расширения "атрибуты директории" | |
NotBefore |
Timestamp
|
Начало действия сертификата | |
NotAfter |
Timestamp
|
Окончание действия сертификата | |
Email |
string
|
Email согласно RFC 822 | |
CertificateSerialNumber |
string
|
Серийный номер сертификата | |
KeyUsage |
KU
|
Использование ключа | |
PublicKey |
string
|
Открытый ключ | |
PublicKeyAlg |
string
|
Алгоритм открытого ключа | |
KeyLength |
int
|
Длинна ключа | |
CriticalEkus |
[]string
|
Критические расширенные использования ключа | |
CertificatePolicies |
[]string
|
Расширение "политики сертификата" | |
SubjectKeyIdentifier |
string
|
Расширение "идентификатор ключа" | |
AuthorityKeyIdentifier |
string
|
Расширение "идентификатор ключа издателя" | |
SubjectFingerprint |
string
|
Хеш-сумма структуры subjectRDN | |
SelfSigned |
bool
|
Определение, самоподписанный ли сертификат | |
AlternativeName |
map[string][]string
|
Словарь расширения "альтернативное имя субъекта", возможные ключи словаря: "IPs", "DNSNames", "URIs", "EmailAddresses" или произвольные объектные идентификаторы | |
ExtendedKeyUsage |
ExtendedKeyUsage
|
extended key usage extension | |
QcStatements |
QcStatements
|
qcStatements extension |
ProxySettings
Struct
Name | Type | Description | |
---|---|---|---|
Host |
string
|
||
Port |
int
|
||
User |
string
|
||
Password |
string
|
||
UseSystemProxy |
bool
|
SignatureDescriptor
Typedef
Real Type | Description |
---|---|
int |
SignatureDescriptor - дескриптор параметров ЭЦП Кроме числа, дескриптор подписи удобно можно задать строкой в формате: $type[-attached][-ts][-signtime][-ocsp][-$policy] $type - [raw/cms/cades-c/cades-x/crypto-kdc] - тип ЭЦП: raw - чистая подпись, pdf - внутренняя цифровая подпись pdf-файла, docx - подпись документа openxml office(.docx), cms - конверт в формате CmsSigned согласно PKCS#7, cades - конверт в формате CADES C(X) Long, crypto-kdc - эЦП в формате CryptoKDCattached - определяет прикреплены ли данные к конвертуts - указывает на необходимость накладывания метки времениts-content - указывает на необходимость накладывания метки времени на данные(обычно не требуется, если ставится обычная метка времени)signtime - указывает на необходимость включения в конверт времени подписиocsp - указывает на необходимость использовать ответы OCSP при формировании CAdES Long C/X - конвертов$policy - [default/stdua/qcua/czoua] политика валидации сертификатов(указывать при формировании CAdES Long C/X - конвертов)(* [...] - опциональный параметр, $a - обозначение строчной переменной)Примеры: - формирование конверта с прикрепленными данными в формате CAdES Long X с политикой валидации STDUA и включением статусов OCSP с включением времени подписи: cades-x-attached-ts-signtime-ocsp-stdua ;- обычный CAdES BES-конверт с не прикрепленными данными: cms . |
KeyStoreSlotDescriptor
Struct
Name | Type | Description | |
---|---|---|---|
Certs |
[]CertificateDescriptorWide
|
||
Hw |
bool
|
Флажок, что указывает на тип НКИ(программный/аппаратный) | |
Description |
string
|
Описание НКИ: имя носителя для аппаратных; путь к файлу для программных в структуре KeyStoreSlotDescriptor или путь к директории с ключами в контроллере CreateCertificate | |
Label |
string
|
Метка НКИ(имя файла для программных НКИ в CreateCertificate) | |
Serial |
string
|
Серийный номер НКИ (только для аппаратных) |
KeyStoreSelector
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
Сертификат для поиска НКИ, которому он принадлежит | |
Cms |
[]byte
|
Зашифрованный или подписанный конверт в формате CMS для поиска НКИ, который содержит сертификат получателя или подписчика соответственно | |
Hw |
bool
|
Флажок, что указывает на тип НКИ(программный/аппаратный) | |
Description |
string
|
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных) | |
Label |
string
|
Метка НКИ | |
Serial |
string
|
Серийный номер НКИ (только для аппаратных) |
SlotInfoRequest
Struct
Name | Type | Description | |
---|---|---|---|
Hw |
bool
|
Флажок, что указывает на тип НКИ(программный/аппаратный) | |
Description |
string
|
Описание НКИ (имя носителя для аппаратных, путь к файлу для программных) | |
Label |
string
|
Метка НКИ | |
Serial |
string
|
Серийный номер НКИ (только для аппаратных) |
SignerInfo
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
CertificateDescriptorWide
|
Дескриптор сертификата подписчика | |
SigningTime |
Timestamp
|
Метка времени на подпись | |
ContentTimeStamp |
Timestamp
|
Метка времени на данные | |
ValidationStatus |
string
|
Статус валидации подписчика: Ok если все хорошо. текст ошибки если что-то пошло не так (не валидная метка времени, сертификат или падение метеорита на сервер OCSP и т.д.). Детальнее про статусы валидации можно узнать из словаряValidationStatusesMap |
Error Handling
В ходе запросов к API сервис может реагировать рядом ситуаций. Список http-кодов ответа и примеров JSON-структур ответа сервиса при ошибках:
200
(Ok) - запрос был успешно обработан, ответ сервиса успешно сформирован согласно структуре ответа.400
(Bad Request) - запрос был сформирован некорректно, например поврежден формат какого-то поля, или оно не задано. Обычно свидетельствует про ошибку программиста.Bad Request{
"Message": "Data is required", // текстовое уведомление про ошибку, в данном случае оно говорит про отсутствие поля 'Data'
"Reason": "Request" // причина ошибки, 'Request' говорит про поврежденный запрос
}403
(Forbidden) - сервис не смог обработать запрос, поскольку запрос нарушает политику безопасности сервиса(отсутствие веб-ресурса в белом списке, отсутствие директории для генерации ключа, что указана в запросе в файле конфигурации). При нормальном сценарии использования сервиса - не появляется.500
(Internal Server Error) - произошла ошибка прикладного уровня пользователя, к примеру при работе с библиотекойCryptoLib
. Детальнее про коды ошибок можно узнать из словарей DsExceptionsMap, KeyStoreExceptionsMap, ValidationStatusesMapInternal Server Error{
"CryptoLibError": {
"Kind": 2, // тип исключения: 1 - DsException, 2 - KeyStoreException, 3 - ValidationError, -1 - UnknownException
"Code": 1880096772, // код ошибки
"InnerCode": 0 // внутренний код ошибки, обычно 0
},
"Message": "KeyStoreException: KSE_INVALID_PASSWORD ", // текстовое сообщение про ошибку, в примере оно говорит про неизвестный пин-код
"Reason": "CryptoLib" // причина ошибки, 'CryptoLib' говорит об исключении уровня библиотеки CryptoLib
}
Constants
map[string]int{
// ECDSA Brainpool
"1.3.36.3.3.2.8.1.1.3": 192,
"1.3.36.3.3.2.8.1.1.5": 224,
"1.3.36.3.3.2.8.1.1.7": 256,
"1.3.36.3.3.2.8.1.1.9": 320,
"1.3.36.3.3.2.8.1.1.11": 384,
"1.3.36.3.3.2.8.1.1.13": 512,
// ECDSA Ansip
"1.3.132.0.30": 160,
"1.3.132.0.33": 224,
"1.3.132.0.34": 384,
"1.3.132.0.35": 521,
// ECDSA Prime
"1.2.840.10045.3.1.1": 192,
"1.2.840.10045.3.1.4": 239,
"1.2.840.10045.3.1.7": 256,
// Dstu4145WithGost
"1.2.804.2.1.1.1.1.3.1.1.2.0": 163,
"1.2.804.2.1.1.1.1.3.1.1.2.1": 167,
"1.2.804.2.1.1.1.1.3.1.1.2.2": 173,
"1.2.804.2.1.1.1.1.3.1.1.2.3": 179,
"1.2.804.2.1.1.1.1.3.1.1.2.4": 191,
"1.2.804.2.1.1.1.1.3.1.1.2.5": 233,
"1.2.804.2.1.1.1.1.3.1.1.2.6": 257,
"1.2.804.2.1.1.1.1.3.1.1.2.7": 307,
"1.2.804.2.1.1.1.1.3.1.1.2.8": 367,
"1.2.804.2.1.1.1.1.3.1.1.2.9": 431,
"1.2.804.2.1.1.1.1.3.1.2.2.0": 173,
"1.2.804.2.1.1.1.1.3.1.2.2.1": 179,
"1.2.804.2.1.1.1.1.3.1.2.2.2": 191,
"1.2.804.2.1.1.1.1.3.1.2.2.3": 233,
"1.2.804.2.1.1.1.1.3.1.2.2.4": 431,
// Dstu4145WithDstu7564
"1.2.804.2.1.1.1.1.3.6.1.1.2.0": 163,
"1.2.804.2.1.1.1.1.3.6.1.1.2.1": 167,
"1.2.804.2.1.1.1.1.3.6.1.1.2.2": 173,
"1.2.804.2.1.1.1.1.3.6.1.1.2.3": 179,
"1.2.804.2.1.1.1.1.3.6.1.1.2.4": 191,
"1.2.804.2.1.1.1.1.3.6.1.1.2.5": 233,
"1.2.804.2.1.1.1.1.3.6.1.1.2.6": 257,
"1.2.804.2.1.1.1.1.3.6.1.1.2.7": 307,
"1.2.804.2.1.1.1.1.3.6.1.1.2.8": 367,
"1.2.804.2.1.1.1.1.3.6.1.1.2.9": 431,
"1.2.804.2.1.1.1.1.3.6.1.2.2.0": 173,
"1.2.804.2.1.1.1.1.3.6.1.2.2.1": 179,
"1.2.804.2.1.1.1.1.3.6.1.2.2.2": 191,
"1.2.804.2.1.1.1.1.3.6.1.2.2.3": 233,
"1.2.804.2.1.1.1.1.3.6.1.2.2.4": 431,
}
map[string]string{
// National algorithms
"Gost34311": "1.2.804.2.1.1.1.1.2.1",
"Dstu7564(256)": "1.2.804.2.1.1.1.1.2.2.1",
"Dstu7564(384)": "1.2.804.2.1.1.1.1.2.2.2",
"Dstu7564(512)": "1.2.804.2.1.1.1.1.2.2.3",
// International algorithms
"SHA-1": "1.3.14.3.2.26",
"SHA-256": "2.16.840.1.101.3.4.2.1",
"SHA-384": "2.16.840.1.101.3.4.2.2",
"SHA-512": "2.16.840.1.101.3.4.2.3",
"SHA-224": "2.16.840.1.101.3.4.2.4",
"SHA-3(224)": "2.16.840.1.101.3.4.2.7",
"SHA-3(256)": "2.16.840.1.101.3.4.2.8",
"SHA-3(384)": "2.16.840.1.101.3.4.2.9",
"SHA-3(512)": "2.16.840.1.101.3.4.2.10",
}
map[int]string{
0x70000001: "ERR_INVALID_FUNCTION", // invalid function
0x70000002: "ERR_INVALID_OPERATION", // invalid operation
0x70000003: "ERR_INVALID_PARAM", // invalid parameter
0x70000004: "ERR_DATA_NOT_FOUND", // data not found
0x70000005: "ERR_DATA_CORRUPTED", // data is corrupted
0x70000006: "ERR_ALG_NOT_FOUND", // the algorithm is not supported
0x70000100: "ERR_TRANSPORT_STATUS", // code base for network error, error coding: ERR_TRANSPORT_STATUS + HTTP_STATUS
0x70000800: "ERR_TSP_STATUS", // code base for TSP service error, error coding: ERR_TSP_STATUS + TSP_STATUS
-3: "ERR_IN_OUT", // input/output error
-9: "ERR_CORRUPTED", // data is corrupted
}
map[string]string{
// National algorithms
"Gost28147cfb": "1.2.804.2.1.1.1.1.1.1.3",
"Dstu7624cfb(256)": "1.2.804.2.1.1.1.1.1.3.3.2",
"Dstu7624cfb(512)": "1.2.804.2.1.1.1.1.1.3.3.3",
"Dstu7624cfb(128)": "1.2.804.2.1.1.1.1.1.3.3.1",
"Dstu7624cbc(128)": "1.2.804.2.1.1.1.1.1.3.5.1",
"Dstu7624cbc(256)": "1.2.804.2.1.1.1.1.1.3.5.2",
"Dstu7624cbc(512)": "1.2.804.2.1.1.1.1.1.3.5.3",
"Dstu7624ofb(128)": "1.2.804.2.1.1.1.1.1.3.6.1",
"Dstu7624ofb(256)": "1.2.804.2.1.1.1.1.1.3.6.2",
"Dstu7624ofb(512)": "1.2.804.2.1.1.1.1.1.3.6.3",
// International algorithms
"aes128-CBC": "2.16.840.1.101.3.4.1.2",
"aes128-CFB": "2.16.840.1.101.3.4.1.4",
"aes192-CBC": "2.16.840.1.101.3.4.1.22",
"aes192-CFB": "2.16.840.1.101.3.4.1.24",
"aes256-CBC": "2.16.840.1.101.3.4.1.42",
"aes256-CFB": "2.16.840.1.101.3.4.1.44",
"desCBC": "1.3.14.3.2.7",
"DES-EDE3-CBC": "1.2.840.113549.3.7",
}
map[int]string{
0x70100001: "KSE_NOT_IMPLEMENTED", // the function is not implemented
0x70100002: "KSE_DATA_NOT_FOUND", // keystore not found
0x70100003: "KSE_STORE_GENERAL", // general keystores error, more detailed Cryptoki library level error returns in InnerCode
0x70100004: "KSE_INVALID_PASSWORD", // wrong PIN
0x70100005: "KSE_LOGIN_REQUIRED", // login required
0x70100006: "KSE_STORE_LOCKED", // keystore is blocked
0x70100007: "KSE_STORE_NOMEMORY", // not enough memory on keystore
}
map[string]string{
"edrpou": "1.2.804.2.1.1.1.11.1.4.2.1",
"drfo": "1.2.804.2.1.1.1.11.1.4.1.1",
"hwDeviceSN": "1.3.6.1.4.1.27990.2.3.3",
"grDeviceSN": "1.3.6.1.4.1.27990.2.3.5",
"CARequestId": "1.3.6.1.4.1.27990.2.6.4",
}
map[string]string{
"CN": "2.5.4.3",
"SN": "2.5.4.4",
"C": "2.5.4.6",
"L": "2.5.4.7",
"ST": "2.5.4.8",
"O": "2.5.4.10",
"OU": "2.5.4.11",
"T": "2.5.4.12",
"G": "2.5.4.42",
"I": "2.5.4.43",
"DC": "0.9.2342.19200300.100.1.25",
"E": "1.2.840.113549.1.9.1",
"STREET": "2.5.4.9",
"SERIALNUMBER": "2.5.4.5",
"uid": "2.5.4.45",
"description": "2.5.4.13",
}
map[int]string{
1: "VFS_INPROGRESS", // check in process
2: "VFS_CERT_NOT_FOUND", // certificate not found
3: "VFS_CERT_USAGE", // misuse of certificate
4: "VFS_ALG_NOT_FOUND", // unknown algorithm
5: "VFS_INVALID", // signature is invalid
6: "VFS_BAD_FORMAT", // damaged envelope format
0: "CVS_VALID", // certificate is valid
-1: "CVS_REVOKED", // certificate is revoked
-2: "CVS_NOT_EFFECTIVE", // certificate is expired
-3: "CVS_CRL_NOT_EFFECTIVE", // certificate revocation list is expired
-4: "CVS_BROKEN", // the certificate is damaged
-5: "CVS_CRL_BROKEN", // certificate revocation list is damaged
-6: "CVS_VIOLATE_POLICY", // the certificate violates the application policy
-7: "CVS_CRL_VIOLATE_POLICY", // certificate revocation list violates the application policy
-8: "CVS_UNKNOWN_CA", // unknown CA
-9: "CVS_UNKNOWN_CRL", // unknown certificate revocation list
-10: "CVS_UNREFERENCED_CA", // a missing link to the certificate from chain during checking the envelope in CADES(C)X Long format
-12: "CVS_VIOLATE_USAGE", // certificate violates the application
-13: "CVS_STORAGE_ERROR", // storage error
-14: "CVS_OCSP_TRANSPORT_ERROR", // network error during working with OCSP
-15: "CVS_OCSP_CERT_ERROR", // OCSP certificate has not been validated
-16: "CVS_OCSP_BROKEN", // OCSP response is corrupted
-17: "CVS_OCSP_DIFFERENT_TIME", // OCSP response is outdated
-18: "CVS_ALG_NOT_SUPPORTED", // the algorithm is not supported
-19: "CVS_OCSP_CERT_CA_ERROR", // certificate validation error that is parent to the OCSP certificate
}