en ua ru

umcaservice / documentation

umcaservice - is a cross-platform cryptographic REST API service based on a certified by State Service of Special Communication and Information Protection of Ukraine library CryptoLib. The main purpose of the service is an integration of ukrainian and national cryptography into web applications.
Two editions of the service are currently available:

  • basic - free edition of the service for non-commercial use. The main functional includes creation of advanced/qualified electronic signatures.
  • full - edition of the service for commercial use. The main functional includes creation and verification of advanced/qualified electronic signatures, management of certificates and key-stores, asymmetric encryption and decryption of data(e.g. creation of cryptographic envelopes).

Operating systems supported:
  • Windows 7 (with Service Pack 1), 8, 10, Windows Server 2012, 2016, 2019
  • GNU/Linux (Debian-based distros, CentOS/RHEL server builds are also available)
  • Mac OS X 10.13+
  • iOS 13+
  • Android 7+
Main tasks:
  • Electronic signatures creation(raw signature or envelopes in CAdES BES, CAdES TS, CAdES Long C, CAdES Long X formats)
  • Electronic signatures, timestamps and certificates validation
  • Key-stores management(generation and removal of keys with certificates, updating certificates on the keystores, change of pin code)
  • Asymmetric encryption and decryption.
Key-store types supported:
  • Hardware: devices supporting PKCS#11 interface(for example Avtor ST337 or Avtor ST338)
  • Software: Pfx(PKCS#12), JKS (Java Key Store), .DAT(IIT), .ZS2(Accredited Certification Authority “Ukraine”)

Usage

By default, the service has a standard set of settings and doesn't require additional configuration, but there is a possibility of additional configuration of the utility.

The main utility settings are stored in configuration file, if configuration file doesn't exist - the utility creates it by path %APPDATA%/Avtor/UmCAService/umcago.conf on Windows and $HOME/.umcad/umcago.conf on Linux and Mac OS X. Service web-configurator is available as well(the "Configuration" menu item in the utility menu).

Together with umcaservice package two PKCS#11 libraries are available for tokens/smart cards by AVTOR LLC, CC337 and CC338. To support other smart cards or tokens, you must add PKCS#11 paths for these devices to the list Pkcs11Modules.

API examples are available as a Postman collection.
A demo web application is available as well UmCADemo, using the API umcaservice.

The command line options of the utility:

  • --text-mode, -t - run the command line utility instead of an icon in the system tray(only on Linux, Mac OS X)
  • --config path_to_config, -c path_to_config, - specify your own configuration file
  • --send-crashes, -s - send service crash dumps to our processing server so that we can resolve the issue
  • --language lang_code, -l lang_code - override service interface language(available values: uk, en, de, ru, el)
  • --doc, -d - run in developer mode(there will be an item in the context menu that opens the documentation)

In case the service terminates incorrectly, the monitoring system creates an error report when the service will start next time. All reports are stored in a folder %APPDATA%/Avtor/UmCAService/ on Windows OS or $HOME/.umcad/ on Unix-based systems with such names as umcago_{creation time}.crash. The service supports the option of sending bug reports to our crash dump server, so that we have information to resolve the issue. This feature is disabled by default. To activate this feature you should run the service with a --send-crashes flag. In this case the traffic between client and crash dump server is protected by TLS. Important: no personal data other than the version of the service, the OS, the architecture and the crash dump are collected and transmitted to the server.

API

The service interacts with the HTTP API described on this page. The root API URI by default: https://localhost:25989. If necessary, it can be overridden via the configuration file. The following are API schemes for revision of basic and full editions

notation used in the documentation:
- indicates that the method is present in full service edition
- indicates that the method uses cookies to increase productivity
- indicates that the method is available only in local mode(Referer=localhost)
- indicates the required field
- indicates that the field must be a base64-string when passed by multipart/form-data or application/x-www-form-urlencoded

About

About
Get information about the service
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
    Create a new key and self-signed certificate on keystore
    POST /certificates
    Request
  • application/json
  • GenerateCertificateRequest Struct
    a structure of the request for a new key generation
    Name Type Description
    Pin string
    KeyRequest KeyRequest a key request
    KeyStore SlotInfo keystore for a key generation
    Response
  • application/json
  • CertificateDescriptorWide Struct
    advanced certificate descriptor
    Name Type Description
    Base64 string
    Subject map[string]string subjectRDN dictionary
    Issuer map[string]string issuerRDN dictionary
    DirectoryAttributes map[string]string directory attributes extension dictionary
    NotBefore Timestamp not valid before
    NotAfter Timestamp not valid after
    Email string Email according to RFC 822
    CertificateSerialNumber string certificate serial number
    KeyUsage KU key usage
    PublicKey string public key
    PublicKeyAlg string public key algorithm
    KeyLength int key length
    CriticalEkus []string critical extended key usage
    CertificatePolicies []string certificate policy extension
    SubjectKeyIdentifier string key identifier extension
    AuthorityKeyIdentifier string publisher key identifier extension
    SubjectFingerprint string checksum of structure subjectRDN
    SelfSigned bool self-signed flag
    AlternativeName map[string][]string subject alternative name extension dictionary, possible dictionary keys: "IPs", "DNSNames", "URIs", "EmailAddresses" or arbitrary object identifiers
    ExtendedKeyUsage ExtendedKeyUsage extended key usage extension
    QcStatements QcStatements qcStatements extension
    DeleteCertificate
    Delete certificate with a key on keystore
    DELETE /certificates
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • DeleteCertificateRequest Struct
    a structure of the certificate removal request
    Name Type Description
    Certificate []byte
    Pin string
    Response
  • application/json
  • GetCertificateStructure
    get a certificate structure
    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
    certificate descriptor
    Name Type Description
    Subject map[string]string subjectRDN dictionary
    Issuer map[string]string issuerRDN dictionary
    DirectoryAttributes map[string]string directory attributes extension dictionary
    NotBefore Timestamp not valid before
    NotAfter Timestamp not valid after
    Email string Email according to RFC 822
    CertificateSerialNumber string certificate serial number
    KeyUsage KU key usage
    PublicKey string public key
    PublicKeyAlg string public key algorithm
    KeyLength int key length
    CriticalEkus []string critical extended key usage
    CertificatePolicies []string certificate policy extension
    SubjectKeyIdentifier string key identifier extension
    AuthorityKeyIdentifier string publisher key identifier extension
    SubjectFingerprint string checksum of structure subjectRDN
    SelfSigned bool self-signed flag
    AlternativeName map[string][]string subject alternative name extension dictionary, possible dictionary keys: "IPs", "DNSNames", "URIs", "EmailAddresses" or arbitrary object identifiers
    ExtendedKeyUsage ExtendedKeyUsage extended key usage extension
    QcStatements QcStatements qcStatements extension
    GetCertificates
    Get a list of certificates according to the filter
    GET /certificates
    GetCertificatesRequest Struct
    a filter for certificates search in KeyStores
    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
    Update the certificate on the keystore or write request ID CA to certificate directory attributes
    PATCH /certificates
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • UpdateCertificateRequest Struct
    a structure of the request for a certificate update
    Name Type Description
    Certificate []byte
    Pin string
    CaRequestID string certificate request ID in CA
    Response
  • application/json
  • Config

    DeleteConfig
    Delete the configuration file and restore the default configuration
    DELETE /config
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • Response
  • application/json
  • GetConfig
    Get the configuration file
    GET /config
    Response
  • application/json
  • UmCAConfig Struct
    UmCAService configuration structure
    Name Type Description
    Port int the port on which the service is started
    TLSKeyFile string path to the file with TLS key PKCS#8(PEM format)
    TLSCertFile string path to the file with TLS certificate(PEM format)
    IsLocal bool flag indicating whether the service should be started locally
    WhiteList []string whitelist of allowed services(asterisk '*' - means not checking Referer)
    CmpServices []string CMP services list
    TspServices []string TSP services list
    FileKeyStores []string a list of paths to directories with program keys('%/' - abbreviated designation for removable media, such as Flash media)
    ProxySettings ProxySettings proxy settings
    CertificateCacheDir string path to directory with certificate cache and certificate revocation list
    Pkcs11Modules []string list of PKCS#11 modules
    TrustedCertificatesDir string path to directory with trusted certificates
    IntermediateCertificatesDir string path to directory with intermediate certificates
    IntermediateCertificatesCmsURL string URL Cms - container with intermediate certificates
    TrustedCertificatesCmsURL string URL Cms - container with trusted certificates
    Log string path to the log file, or empty value if it's needed to write log to STDOUT
    LogLevel int logging level: 1 - DEBUG - maximum level(requests are logged), 4 - ERRORS - error level, 5 - OFF - without logging
    SimplifiedMode bool flag indicating to run the service in a simplified mode
    UpdateConfig
    Update the configuration file
    POST /config
    Request
  • application/json
  • UmCAConfig Struct
    UmCAService configuration structure
    Name Type Description
    Port int the port on which the service is started
    TLSKeyFile string path to the file with TLS key PKCS#8(PEM format)
    TLSCertFile string path to the file with TLS certificate(PEM format)
    IsLocal bool flag indicating whether the service should be started locally
    WhiteList []string whitelist of allowed services(asterisk '*' - means not checking Referer)
    CmpServices []string CMP services list
    TspServices []string TSP services list
    FileKeyStores []string a list of paths to directories with program keys('%/' - abbreviated designation for removable media, such as Flash media)
    ProxySettings ProxySettings proxy settings
    CertificateCacheDir string path to directory with certificate cache and certificate revocation list
    Pkcs11Modules []string list of PKCS#11 modules
    TrustedCertificatesDir string path to directory with trusted certificates
    IntermediateCertificatesDir string path to directory with intermediate certificates
    IntermediateCertificatesCmsURL string URL Cms - container with intermediate certificates
    TrustedCertificatesCmsURL string URL Cms - container with trusted certificates
    Log string path to the log file, or empty value if it's needed to write log to STDOUT
    LogLevel int logging level: 1 - DEBUG - maximum level(requests are logged), 4 - ERRORS - error level, 5 - OFF - without logging
    SimplifiedMode bool flag indicating to run the service in a simplified mode
    Response
  • application/json
  • UpdateConfigPartial
    Partially update the service configuration
    PATCH /config
    Request
  • application/json
  • UpdateConfRequest Struct
    request structure for a partial update of the current service configuration
    Name Type Description
    CmpServices []string
    TspServices []string
    Response
  • application/json
  • Decrypt

    Decrypt
    Decrypt data
    POST /decrypt
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • DecryptRequest Struct
    a request for an envelope decryption
    Name Type Description
    Data []byte Encrypted data, if it doesn't attached to CMS or concatenation of CMS Detached and encrypted data(.enc format)
    Cms []byte CMS Enveloped
    Pin string pin code to the keystore where the recipient key is stored
    Response
  • application/octet-stream
  • Encrypt

    Encrypt
    Encrypt data on recipients
    POST /encrypt
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • EncryptRequest Struct
    a structure of encryption request
    Name Type Description
    Certificates [][]byte recipients' certificates
    Data []byte data for encryption
    AsBlob bool flag indicating the response return format(octet-stream if value true). It can also be specified by an HTTP header Accept: application/octet-stream
    EncSchema int key encryption output scheme for encryption DSTU4145, usually 0 or 256 for compatibility
    IDByIssuerSN bool certificate identification by certificate serial number and its issuer
    AttachedData bool flag indicating whether or not to attach encrypted data to CMS Enveloped
    EncryptionAlgOid string encryption algorithm identifier
    Response
  • application/octet-stream
  • application/json
  • EncryptedResponse Struct
    a structure of the encryption result; during serialization in 'application/octet-stream' 'Cms' value and 'EncryptedContent' value are concatenated (.enc format)
    Name Type Description
    Cms []byte
    EncryptedContent []byte

    Envelope

    MakeEnvelope
    Create a signed/encrypted envelope
    POST /envelope/make
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • MakeEnvelopeRequest Struct
    Name Type Description
    Files [][]byte a list of files that should be attached to the envelope
    Certificate []byte signer certificate (leave it blank if a signature is not required)
    Pin string keystore pin code
    Recipients [][]byte a list of recipient encryption certificates (leave it blank if encryption is not required)
    EncryptionAlgOid string content encryption algorithm identifier
    SigType SignatureDescriptor signature descriptor
    DigestAlgOid string signature algorithm identifier
    Response
  • application/octet-stream
  • OpenEnvelope
    Open a signed/encrypted envelope
    POST /envelope/open
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • OpenEnvelopeRequest Struct
    Name Type Description
    Data []byte an envelope in AvtorEnvelope format that should be opened
    Pin string keystore pin code with a decryption key
    Certificate []byte an encryption certificate (or empty value for its automatic search in the user's key stores)
    IntendedEku string expected extended key usage. "any" - any extended usage.
    MustBeTimestamped bool flag indicating that the timestamp in the envelope is required and should be checked
    ValidateAsCADES bool flag indicating that envelope should be validate using the CADES-C (X) Long envelope verification procedure
    ValidateContentTimeStamp bool flag indicating that content time stamp should be present and verified
    PreferOCSP bool flag indicating that OCSP should be preferred over CRL validation
    Policy string certificate validation policy
      Possible values in the request:
      default - default policy
      stdua -STDUA policy
      qcua - QCUA policy
      czoua - CZOUA policy for compability with CZO
    AttachedDataAsResource bool flag indicating that attached data should be provided by the link for download instead of data itself
    GenerateValidationReport bool flag indicating that verification report should be gererated and provided by the link for download
    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 type of envelope: 1 - signed, 2 - encrypted, 3 - encrypted+signed
    RecieverKeyStore KeyStoreSlotDescriptor reciever key store descriptor

    Keystores

    ChangePin
    Change pin code on keystore
    PATCH /keystores
    Request
  • application/json
  • ChangePinRequest Struct
    a structure of the request for changing pin code
    Name Type Description
    OldPin string old pin code
    NewPin string new pin code
    KeyStore KeyStoreSelector keystores selector
    Response
  • application/json
  • CheckPin
    Check pin-code of the keystore
    POST /keystores/checkpin
    Request
  • application/json
  • CheckPinRequest Struct
    a structure of request for check a pin-code to the keystore
    Name Type Description
    Pin string
    KeyStore KeyStoreSelector
    Response
  • application/json
  • GetKeyStores
    get list of key stores
    GET /keystores
    GetKeyStoresRequest Struct
    a structure of request for receiving keystores list
    Name Type Description
    ReadCertificates bool flag indicating whether certificates should be read
    EnfoldFileKeyStores bool flag indicating whether to read the directories for saving software keystore (setting FileKeyStores in the configuration) instead of software KeyStores
    Hw bool flag indicating keystore type(software/hardware)
    Description string keystore description (device name for hardware, file path for software)
    Label string keystore label
    Serial string serial number (present only for hardware keystores)
    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
    Import file key store to UmCAService
    POST /keystores/import
    Request
  • application/json
  • ImportKeyStoreRequest Struct
    Name Type Description
    Data []byte File to be imported
    KeyStore SlotInfo Descriptor of the keystore. Currently, the only supported keystores are file-based, so that KeyStore.Description must be a path to the one of FileKeyStores folder and KeyStore.Hw=true, optionally one might set KeyStore.Label in order to give a name to the keystore file.
    Response
  • application/json
  • KeyStoreSlotDescriptor Struct
    keystore descriptor
    Name Type Description
    Certs []CertificateDescriptorWide
    Hw bool flag indicating keystore type(software/hardware)
    Description string keystores description: device name for hardware keystores; file path in KeyStoreSlotDescriptor or folder path in CreateCertificate controller for software keystores
    Label string keystore label (filename for software keystore in CreateCertificate)
    Serial string serial number (present only for hardware keystores)
    LoadAssociatedCertificates
    Load associated certificates (create key11.dat for key6.dat if needed)
    POST /keystores/loadcerts
    Request
  • application/json
  • LoadAssociatedCertificatesRequest Struct
    a structure of request for loading needed certificates
    Name Type Description
    Pin string
    KeyStore SlotInfoRequest
    Response
  • application/json
  • []CertificateDescriptorWide Array of CertificateDescriptorWide
    SelectKeyStore
    find keystore by selector
    POST /keystores/select
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • KeyStoreSelector Struct
    KeyStore selector: you should specify a certificate or CMS envelope (encrypted or signed) or some of the KeyStore descriptor fields to select the KeyStore
    Name Type Description
    Certificate []byte a certificate for the search of the KeyStore which it belongs to
    Cms []byte encrypted or signed envelope in CMS format for KeyStores search which contains certificate of recipient or signer respectively
    Hw bool flag indicating keystore type(software/hardware)
    Description string keystore description (device name for hardware, file path for software)
    Label string keystore label
    Serial string serial number (present only for hardware keystores)
    Response
  • application/json
  • KeyStoreSlotDescriptor Struct
    keystore descriptor
    Name Type Description
    Certs []CertificateDescriptorWide
    Hw bool flag indicating keystore type(software/hardware)
    Description string keystores description: device name for hardware keystores; file path in KeyStoreSlotDescriptor or folder path in CreateCertificate controller for software keystores
    Label string keystore label (filename for software keystore in CreateCertificate)
    Serial string serial number (present only for hardware keystores)

    Log

    GetLog
    Get log file (if exist)
    GET /log
    Response
  • application/json
  • Sign

    CreateMultipleSignatures
    Sign multiple documents
    POST /sign/multiple
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • MultipleSignaturesRequest Struct
    a structure of request for multiple electronic signatures
    Name Type Description
    Certificate []byte a certificate corresponding to the key for the electronic signature or a file with key in a pfx, dat, zs2 or jks formats
    MultipleData [][]byte array of documents for signature
    MultipleCms [][]byte list of existing cmss; only for adding signatures to existing envelopes
    Pin string pin code to keystore with electronic signature certificate
    SigType SignatureDescriptor signature descriptor
    DigestAlgOid string signature algorithm identifier
    Response
  • application/json
  • [][]byte
    CreateSignature
    Sign the document(new or existing)
    POST /sign
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • SignatureRequest Struct
    a structure of request for electronic signature
    Name Type Description
    Certificate []byte a certificate corresponding to the key for the electronic signature or a file with key in a pfx, dat, zs2 or jks formats
    Cms []byte an existing envelope to be signed (or left blank if you need to create a new one)
    Data []byte data for signature
    Pin string pin code to keystore with electronic signature certificate
    AsBlob bool flag indicating response return format(octet-stream if value true). It can also be specified by http headerAccept: application/octet-stream
    AsResource bool flag indicating signature should be cached to a file and response should contain a link to the newly created resource.
    SigType SignatureDescriptor signature descriptor
    DigestAlgOid string signature algorithm identifier
    Response
  • application/octet-stream
  • application/json
  • GetSignatureFile
    Download signature or attached data file
    GET /sign/:id
    Response
  • application/octet-stream
  • application/pdf
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/x-pkcs7-signature
  • Verify

    Verify
    Verify signed document or certificate
    POST /verify
    Request
  • application/json
  • multipart/form-data
  • application/x-www-form-urlencoded
  • ValidationRequest Struct
    a structure of cms or certificate validation request
    Name Type Description
    Certificate []byte certificate for validation (specify only if a certificate validation, not envelope, is required)
    Data []byte signed data (only if data detached)
    Cms []byte CMS-envelope for validation (maybe extended to CADES-C(X) Long)
    IntendedEku string expected extended key usage. "any" - any extended usage.
    MustBeTimestamped bool flag indicating that the timestamp in the envelope is required and should be checked
    ValidateAsCADES bool flag indicating that envelope should be validate using the CADES-C (X) Long envelope verification procedure
    ValidateContentTimeStamp bool flag indicating that content time stamp should be present and verified
    PreferOCSP bool flag indicating that OCSP should be preferred over CRL validation
    Policy string certificate validation policy
      Possible values in the request:
      default - default policy
      stdua -STDUA policy
      qcua - QCUA policy
      czoua - CZOUA policy for compability with CZO
    AttachedDataAsResource bool flag indicating that attached data should be provided by the link for download instead of data itself
    GenerateValidationReport bool flag indicating that verification report should be gererated and provided by the link for download
    Response
  • application/json
  • ValidationResponse Struct
    Name Type Description
    Status string overall check status:
      Ok if an envelope or certificate has been validated completely
      Nok if an envelope has been partially validated, there are problems with the validation of certain signer certificates or timestamps
      error text if an envelope has not passed the basic validation (broken format, lack of data, etc.), if only a certificate was checked - error in a certificate validation
    Signers []SignerInfo array of signers information (only during CMS verification)
    AttachedData AttachedData data attached to envelope (byte array or url with string)
    ValidationReportURL string URL to the signature verification report

    Data Structures

    KeyRequest Struct
    key and certificate request
    Name Type Description
    Subject map[string]string a dictionary corresponding to the SubjectDN structure
    DirectoryAttributes map[string]string a dictionary corresponding to directory attributes
    Email string
    KeyUsage KU key usage
    CriticalEkus []string a list of critical extended key usages - obsolated (insead use ExtendedKeyUsage)
    ValidityDays int a number of days when the certificate is valid
    ExtendedKeyUsage ExtendedKeyUsage
    SSCDLabels SSCDLabels Secure Signature Creation Device labels
    KeyParams KeyParams key generation parameters
    ExtendedKeyUsage Struct
    Name Type Description
    Critical bool
    KeyPurposeIDs []string note: 'Oids' replaced by 'KeyPurposeIDs' in 3.8.1
    SSCDLabels Struct
    Secure Signature Creation Device labels
    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
    a structure of key parameters
    Name Type Description
    AlgOid string public key algorithm(its object identifier or abbreviation), currently supported algorithms:
      'rsa' - 1.2.840.113549.1.1.1 (PKCS#1 RSA)
      'dstu4145' - 1.2.804.2.1.1.1.1.3.1.1 (DSTU(National Standard of Ukraine) 4145/2002)
      'ecdsa' - 1.2.840.10045.2.1 (X9.62 ECDSA)
    KeyLen int key length, automatically selected if the value is empty
    Params []byte optional parameters, usually with empty value
    SlotInfo Struct
    general information about keystore
    Name Type Description
    Hw bool flag indicating keystore type(software/hardware)
    Description string keystores description: device name for hardware keystores; file path in KeyStoreSlotDescriptor or folder path in CreateCertificate controller for software keystores
    Label string keystore label (filename for software keystore in CreateCertificate)
    Serial string serial number (present only for hardware keystores)
    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 time
    KU Typedef
    Real Type Description
    uint8 KU - key usage. In the request can be encoded as characters: s, e, c or a 1-byte number as well
    's' - electronic signature [0xCO]
    'e' - encryption / key exchange [0x30/0x08]
    'c' - signature of certificates(CA) [0x06]
    KsType Typedef
    Real Type Description
    uint8 KsType - keystore type
    0 - all the stores
    1 - software stores
    2 - hardware stores
    CertificateDescriptorWide Struct
    advanced certificate descriptor
    Name Type Description
    Base64 string
    Subject map[string]string subjectRDN dictionary
    Issuer map[string]string issuerRDN dictionary
    DirectoryAttributes map[string]string directory attributes extension dictionary
    NotBefore Timestamp not valid before
    NotAfter Timestamp not valid after
    Email string Email according to RFC 822
    CertificateSerialNumber string certificate serial number
    KeyUsage KU key usage
    PublicKey string public key
    PublicKeyAlg string public key algorithm
    KeyLength int key length
    CriticalEkus []string critical extended key usage
    CertificatePolicies []string certificate policy extension
    SubjectKeyIdentifier string key identifier extension
    AuthorityKeyIdentifier string publisher key identifier extension
    SubjectFingerprint string checksum of structure subjectRDN
    SelfSigned bool self-signed flag
    AlternativeName map[string][]string subject alternative name extension dictionary, possible dictionary keys: "IPs", "DNSNames", "URIs", "EmailAddresses" or arbitrary object identifiers
    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 - descriptor of electronic signature parameters
      In addition to the number, the signature descriptor can be specified in such format: $type[-attached][-ts][-signtime][-ocsp][-$policy]
      $type - [raw/pdf/docx/cms/cades-c/cades-x/crypto-kdc] - electronic signature type: raw - raw signature, pdf - pdf document digital signature, docx - openxml office document signature, cms - CmsSigned according to PKCS#7, cades - CmsSigned in CADES C(X) Long format, crypto-kdc - digital signature in CryptoKDC format
      attached - determines whether to attach data to the envelope
      ts - indicates the need for a timestamp
      ts-content - indicates the need to add a timestamp on the data (usually not required if a regular timestamp is set)
      signtime - indicates the need to include a signature time in the envelope
      ocsp - indicates the need to use responses OCSP when forming CAdES Long C/X - envelopes
      $policy - [default/stdua/qcua/czoua] certificate validation policy (specify when forming CAdES Long C/X - envelopes)
      (* [...] - optional parameter, $a - designation of a string variable)
      Examples:
      - envelope formation with attached data in CAdES Long X format with STDUA validation policy and inclusion of OCSP statuses with signature time enabled: cades-x-attached-ts-signtime-ocsp-stdua;
      - ordinary CAdES BES envelope with unattached data: cms.
    KeyStoreSlotDescriptor Struct
    keystore descriptor
    Name Type Description
    Certs []CertificateDescriptorWide
    Hw bool flag indicating keystore type(software/hardware)
    Description string keystores description: device name for hardware keystores; file path in KeyStoreSlotDescriptor or folder path in CreateCertificate controller for software keystores
    Label string keystore label (filename for software keystore in CreateCertificate)
    Serial string serial number (present only for hardware keystores)
    KeyStoreSelector Struct
    KeyStore selector: you should specify a certificate or CMS envelope (encrypted or signed) or some of the KeyStore descriptor fields to select the KeyStore
    Name Type Description
    Certificate []byte a certificate for the search of the KeyStore which it belongs to
    Cms []byte encrypted or signed envelope in CMS format for KeyStores search which contains certificate of recipient or signer respectively
    Hw bool flag indicating keystore type(software/hardware)
    Description string keystore description (device name for hardware, file path for software)
    Label string keystore label
    Serial string serial number (present only for hardware keystores)
    SlotInfoRequest Struct
    a filter for keystores search
    Name Type Description
    Hw bool flag indicating keystore type(software/hardware)
    Description string keystore description (device name for hardware, file path for software)
    Label string keystore label
    Serial string serial number (present only for hardware keystores)
    SignerInfo Struct
    information about signer validation
    Name Type Description
    Certificate CertificateDescriptorWide Certificate descriptor of signer
    SigningTime Timestamp Time from signature timestamp
    ContentTimeStamp Timestamp Time from content timestamp
    ValidationStatus string Signer validation status:
     Ok if everything is ok.
     error text if something was wrong(not a valid timestamp, certificate, or meteorite crash on an OCSP server, etc.). You can learn more about validation statuses from the dictionaryValidationStatusesMap

    Error Handling

    During API requests, the service may respond to a number of situations. List of http response codes and examples of JSON error response service structures:
    • 200 (Ok) - the request was successfully processed, the service response was generated according to the response structure.
    • 400 (Bad Request) - the request was incorrectly formatted, for example, the format of a field was damaged or it was not specified. Usually indicates a developer error.
      Bad Request {
       "Message": "Data is required", // text error message, in this case it indicates that 'Data' field is absent
       "Reason": "Request" // the cause of the error, 'Request' indicates a corrupted request
      }
    • 403 (Forbidden) - the service was unable to process the request because the request violates the security policy of the service(no web resource in the whitelist, no directory to generate the key specified in the request in the configuration file). This error doesn’t occur during the normal use of service.
    • 500(Internal Server Error) - an application level error occurred, for example when working with a library CryptoLib. You can learn more about error codes from dictionaries DsExceptionsMap, KeyStoreExceptionsMap, ValidationStatusesMap
      Internal Server Error {
       "CryptoLibError": {
         "Kind": 2, // exception type: 1 - DsException, 2 - KeyStoreException, 3 - ValidationError, -1 - UnknownException
         "Code": 1880096772, // error code
         "InnerCode": 0 // an internal error code, usually 0
       },
       "Message": "KeyStoreException: KSE_INVALID_PASSWORD ", // an error message, this example refers to the incorrect pin code
       "Reason": "CryptoLib" // cause of error, 'CryptoLib' refers to the exception of CryptoLib library
      }

    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 - dictionary of hashing algorithms
    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 hierarchy dictionary
    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 - dictionary of encryption algorithms
    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 hierarchy dictionary
    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
    NameDirAttrToOidMap - dictionary of mnemonics(aliases) for the most common object identifiers in DirectoryAttributes. The mnemonics are applied while getting certificate descriptor and generating new certificate
    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 - dictionary of mnemonics(aliases) for the most common object identifiers in SubjectRDN. The mnemonics are applied while getting certificate descriptor and generating new certificate
    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 - signature and certificate validation status dictionary
    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
    }