en ua ru

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 ссылка на отчет о проверке подписи

    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 Серийный номер НКИ (только для аппаратных)
    QcStatements Struct
    Name Type Description
    Critical bool
    QcStatements []QcStatement
    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

    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, ValidationStatusesMap
      Internal 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

    AlgorithmKeyLengthMap
    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,
    }
    DigestAlgorithmsMap
    DigestAlgorithmsMap - словарь алгоритмов хеширования
    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",
    }
    DsExceptionsMap
    DsExceptionsMap - словарь исключений иерархии DsException
    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
    }
    EncryptionAlgorithmsMap
    EncryptionAlgorithmsMap - словарь алгоритмов шифрования
    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",
    }
    KeyStoreExceptionsMap
    KeyStoreExceptionsMap - словарь исключений иерархии KeyStoreException
    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
    }
    NameDirAttrToOidMap
    NameX500ToOidMap - словарь мнемоник (алиасов) для самых распространенных объектных идентификаторов атрибутов директории. Мнемоники действуют при получении информации в дескрипторе, а также при генерации
    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",
    }
    NameX500ToOidMap
    NameX500ToOidMap - словарь мнемоник (алиасов) для самых распространенных объектных идентификаторов имен субъекта. Мнемоники действуют при получении информации в дескрипторе, а также при генерации
    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",
    }
    ValidationStatusesMap
    ValidationStatusesMap - словарь статусов проверки подписи и сертификата
    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
    }