umcaservice / FAQ

Q: umcaservice hasn't started and the white bear icon hasn't appeared in the system tray. What should I do?

Recheck the installation of the application. Check whether the umcaservice TLS certificate - umca_ssl.crt is present and marked as trusted by OS or web-browsers, the one could be found in application resources folder (Usually Program Files\Avtor\UmCAService on Windows, /usr/share/avtor/umcad/ on Linux, /Applications/UmCAService.app/Contents/Resources on Mac OS X). If the certificate is absent reinstall the application. If neither of described situations has happened look for crash logs umcago*.crash of umcaservice in a profile folder of the service(%APPDATA%\Avtor\UmCAService on Windows, ~/.umcad on Mac OS X and Linux) and send in to our support team.

Q: umcaservice has exited unexpectedly. What should I do?

Click "Send crash dump" memu button on the next run or manually find crash logs umcago*.crash of umcaservice in a user profile folder of the service(%APPDATA%\Avtor\UmCAService on Windows, ~/.umcad on Mac OS X and Linux) and send in to our support team.

Q: The application failed to respond to calling web-application in Mozilla Firefox. What should I do?

Probably, the umcaservice root TLS certificate hasn't been installed to Firefox trusted certstore because of outdated version of Firefox, you could try to update Firefox and install the certicate manually or reinstall the application entirely after that. Also you could simply mark the umcaservice certificate as trusted for Firefox.

Q: How can I manually generate or install a new umcaservice TLS certificate?

Consider the web-browser security policies it is prohibited to access external http resources from https resource. To overcome this issue and mitigate potential security issues umcaservice protects all the traffic with TLS protocol. The essential part of TLS protocol is a server certificate: it must be verified on a client side during handshake so that the client(web-browser in most cases) should perform certificate path validation procedure and set up trust to the service certificate. During installation proccess installer generates a needed certificate chain and tries to set the one as trusted for OS and web-browsers. Mentioned certificate chain looks like:

  • O=Avtor LLC Local CA, OU=UmCAService distributive #4bf425d9, CN=UmCAService TLS support root
  • O=Avtor LLC Local CA, OU=UmCAService distributive #4bf425d9, CN=localhost
A distributive number is generated randomly per installation. If you need to manually (re)install or (re)generate certificate you could use umcertutil application.
that could be found in an application binaries directory (Usually Program Files\Avtor\UmCAService on Windows, /usr/bin on Linux, /Applications/UmCAService.app/MacOS on Mac OS X) In order generate and install new certificates execute:
umcertutil install {path to application resources folder}
If you only need to install existing certificate without regeneration provide --no-generate flag for the command above:
umcertutil install --no-generate {path to application resources folder}
After that you need to restart the service. Note that usually you have to have administrator privileges to complete such scenario.

Q: I keep receiving network errors while requesting a TSP or other network service.

Firstly, make sure that you are using service version at least 3.7.7. Another probable reason could be proxy that your OS configured with. Try to set proper proxy settings in configuration in this case.

Q: On Windows I could not change any configuration setting in the configuration webpage because of an error

By default, configuration file is located in Program Files\Avtor\UmCAService directory which is protected for writing for ordinary users. You need to run the service as an administrator in order to change any setting. Also, you could delete configuration file from that directory so that a new configuration file will be created in user profile directory(%APPDATA%\Avtor\UmCAService) of the service and it will be free to modify for an ordinary user.

Q: What is user profile directory, resources directory and application binaries directory?

This 3 main directories contain different application files:

  • user profile directory contains user specific data - an optional configuration, a certificate cache, a local file-based keystore. %APPDATA%\Avtor\UmCAService on Windows, ~/.umcad on Linux and Mac OS X.
  • resources directory contains various resources of the application: TLS certificates, static files, etc. Program Files\Avtor\UmCAService on Windows, /usr/share/avtor/umcad/ on Linux, /Applications/UmCAService.app/Contents/Resources on Mac OS X
  • application binaries directory contains application binaries. Program Files\Avtor\UmCAService on Windows, /usr/bin on Linux, /Applications/UmCAService.app/MacOS on Mac OS X

Q: Why didn't you implement feature 'X'?

Probably umcaservice already has had the one. Try to look for it in official developer documentation. If not - mail us.

Q: Why umcaservice haven't seen my usb-token/smart-card?

umcaservice works only with PKCS#11-compatible devices. The service is shipped along with Avtor ST337/ST338 PKCS#11 library by default. In order to support other devices you should contact your vendor, take an appropriate PKCS#11 library and set the library in umcaservice configuration(Pkcs11Modules setting).

For MacOS users: make sure that you are using official USB adapter by Apple, we couldn't guarantee stable work of usb-tokens with non-certified adapters.

Q: umcaservice have seen my usb-token/smart-card but no certificate was found

umcaservice works only with keys stored in active mode on usb-token/smart-card. IIT-style passive-mode written keys are not supported. You need to re-import such keys in active mode on the device in order to work with PKCS#11. Also, the service works only with hardware keys, which have certificates binded to them. You can bind it manually with special utility or use auto-binding with CMP(In order to do that you have to have umcaservice ver. at least 3.8.0 and have appropriate CMP-service in CMPServices setting).

Q: Do the service work on a terminal server for multiple users

umcaservice supports a multiuser terminal server mode with ver. at least 3.8.0. In order to turn the mode on you must set a default Port(from a configuration file in an installation folder) to zero. Hence, the service will run in per-user configuration file setting and choose an available port for running in range [26000, 27000] per user. In order to tell an external web-application a current port copy the application identifier by clicking "Copy App Id" menu button or copy it from the umcaservice local web-interface, then you shall pass the obtained identifier to the external web-application.

Q: I have faced with an unknown CA error(code -8). What does it mean?

It means that a certificate could not be validated taking only existing trusted certificates list. In order to validate such certificate you need to add a base of certificate chain(root CA) to the list of trusted certificates(TrustedCertificatesDir). By default, umcaservice is configured to use ukrainian CZO certificates as trusted and also could be specifically configured for each customer's trusted certificates.