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).
- 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+
- 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.
- 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
- 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
Cdn
GetResourceFile
Download a created resource file
GET
/cdn/:id
Response
application/octet-stream
application/pdf
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/x-pkcs7-signature
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
UploadCertificate
upload a certificate to the cdn
POST
/certificates/upload
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
CertificateStructRequest
Struct
Name
Type
Description
Certificate
[]byte
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
AsResource
bool
flag indicating decrypted file should be cached to a file and response should contain a link to the newly created file
Response
application/octet-stream
application/json
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
AsResource
bool
flag indicating enrypted file should be cached to a file and response should contain a link to the newly created file
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
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
About
Get information about the service
AboutResponse
Struct
Name | Type | Description | |
---|---|---|---|
Name |
string
|
||
Version |
string
|
||
Edition |
string
|
||
Author |
string
|
||
Email |
string
|
||
AppID |
string
|
||
OS |
string
|
||
Arch |
string
|
GetResourceFile
Download a created resource file
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
UploadCertificate
upload a certificate to the cdn
POST
/certificates/upload
Request
application/json
multipart/form-data
application/x-www-form-urlencoded
CertificateStructRequest
Struct
Name
Type
Description
Certificate
[]byte
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
AsResource
bool
flag indicating decrypted file should be cached to a file and response should contain a link to the newly created file
Response
application/octet-stream
application/json
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
AsResource
bool
flag indicating enrypted file should be cached to a file and response should contain a link to the newly created file
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
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
CreateCertificate
Create a new key and self-signed certificate on keystore
GenerateCertificateRequest
Struct
Name | Type | Description | |
---|---|---|---|
Pin |
string
|
||
KeyRequest |
KeyRequest
|
a key request |
|
KeyStore |
SlotInfo
|
keystore for a key generation |
CertificateDescriptorWide
Struct
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
DeleteCertificateRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
||
Pin |
string
|
GetCertificateStructure
get a certificate structure
CertificateStructRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
CertificateDescriptor
Struct
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
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
Update the certificate on the keystore or write request ID CA to certificate directory attributes
UpdateCertificateRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
||
Pin |
string
|
||
CaRequestID |
string
|
certificate request ID in CA |
UploadCertificate
upload a certificate to the cdn
CertificateStructRequest
Struct
Name | Type | Description | |
---|---|---|---|
Certificate |
[]byte
|
DeleteConfig
Delete the configuration file and restore the default configuration
GetConfig
Get the configuration file
UmCAConfig
Struct
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
UmCAConfig
Struct
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 |
UpdateConfigPartial
Partially update the service configuration
UpdateConfRequest
Struct
Name | Type | Description | |
---|---|---|---|
CmpServices |
[]string
|
||
TspServices |
[]string
|
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
AsResource
bool
flag indicating decrypted file should be cached to a file and response should contain a link to the newly created file
Response
application/octet-stream
application/json
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
AsResource
bool
flag indicating enrypted file should be cached to a file and response should contain a link to the newly created file
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
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
Decrypt
Decrypt data
DecryptRequest
Struct
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 |
|
AsResource |
bool
|
flag indicating decrypted file should be cached to a file and response should contain a link to the newly created file |
Encrypt
Encrypt data on recipients
EncryptRequest
Struct
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 |
|
AsResource |
bool
|
flag indicating enrypted file should be cached to a file and response should contain a link to the newly created file |
|
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 |
EncryptedResponse
Struct
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
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
MakeEnvelope
Create a signed/encrypted envelope
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 |
OpenEnvelope
Open a signed/encrypted envelope
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 policystdua -STDUA policyqcua - QCUA policyczoua - 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 |
PreOpenEnvelope
preopen a signed/ecnrypted envelope
PreOpenEnvelopeRequest
Struct
Name | Type | Description | |
---|---|---|---|
Data |
[]byte
|
PreOpenEnvelopeResponse
Struct
Name | Type | Description | |
---|---|---|---|
EnvelopeType |
int
|
type of envelope: 1 - signed, 2 - encrypted, 3 - encrypted+signed |
|
RecieverKeyStore |
KeyStoreSlotDescriptor
|
reciever key store descriptor |
ChangePin
Change pin code on keystore
ChangePinRequest
Struct
Name | Type | Description | |
---|---|---|---|
OldPin |
string
|
old pin code |
|
NewPin |
string
|
new pin code |
|
KeyStore |
KeyStoreSelector
|
keystores selector |
CheckPin
Check pin-code of the keystore
CheckPinRequest
Struct
Name | Type | Description | |
---|---|---|---|
Pin |
string
|
||
KeyStore |
KeyStoreSelector
|
GetKeyStores
get list of key stores
GetKeyStoresRequest
Struct
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
|
[]KeyStoreSlotDescriptor
Array of KeyStoreSlotDescriptor
ImportKeyStore
Import file key store to UmCAService
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. |
KeyStoreSlotDescriptor
Struct
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)
LoadAssociatedCertificatesRequest
Struct
Name | Type | Description | |
---|---|---|---|
Pin |
string
|
||
KeyStore |
SlotInfoRequest
|
[]CertificateDescriptorWide
Array of CertificateDescriptorWide
SelectKeyStore
find keystore by selector
KeyStoreSelector
Struct
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) |
KeyStoreSlotDescriptor
Struct
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
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
GetLog
Get log file (if exist)
CreateMultipleSignatures
Sign multiple documents
MultipleSignaturesRequest
Struct
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 |
[][]byte
CreateSignature
Sign the document(new or existing)
SignatureRequest
Struct
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 |
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
Verify
Verify signed document or certificate
ValidationRequest
Struct
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 policystdua -STDUA policyqcua - QCUA policyczoua - 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 |
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)
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
KeyRequest
Struct
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
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
|
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
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) |
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 type0 - all the stores1 - software stores2 - hardware stores |
CertificateDescriptorWide
Struct
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 formatattached - determines whether to attach data to the envelopets - indicates the need for a timestampts-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 envelopeocsp - 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
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
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
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
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 libraryCryptoLib
. You can learn more about error codes from dictionaries DsExceptionsMap, KeyStoreExceptionsMap, ValidationStatusesMapInternal 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
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
}