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

About

Certificates

Config

Decrypt

Encrypt

Envelope

Keystores

Log

Sign

Verify

Data Structures

Error Handling

During API requests, the service may respond to a number of situations. List of http response codes and examples of JSON error response service structures:

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