CAPKI - Securing the ServiceManager

The CAPKI libraries provide features that are required for information security services, such as the TLS/SSL implementation, and is required for the secure communication of the ServiceManager. CAPKI is available for Windows and all Unix platforms supported by the Automation Engine and can be downloaded from https://downloads.automic.com/.

Important! CAPKI is not supported in the Automic Automation Kubernetes Edition but you can use the ServiceManager without CAPKI to start your agents.

This page includes the following:

Overview

The Automation Engine uses CAPKI to establish TLS 1.2 based secure connections between the ServiceManager and its clients, the ServiceManager Dialog Program, the ServiceManager Command Line and the Automation Engine itself. You have to install CAPKI on all computers on which server processes, the ServiceManager, or any of its clients run.

More information:

Recommendations

It is recommended to carry out the following upgrade steps in the order they are listed here:

  1. Install CAPKI on all computers on which server processes, the ServiceManager, and any of its clients run.

    Important! It is recommended to roll out CAPKI before installing or upgrading components of the Automation Engine that require CAPKI. If, for any reason, you have to install CAPKI after installing or upgrading these components, you must restart the components for CAPKI to take effect.

  2. Upgrade the Automation Engine and all its components either manually or by using the ZDU and the Centralized Agent Upgrade (CAU).

  3. In the UC_SYSTEM_SETTNGS variable, set the SMGR_SUPPORT_LEGACY_SECURITY parameter to N.

    Important! Once this parameter is set to N, the Automation Engine no longer supports communication with legacy ServiceManagers.

    More information:

Following this order guarantees a seamless functioning during the upgrade process. The new ServiceManager Dialog and CLI components, as well as the communication processes of the Automation Engine still can communicate with a legacy ServiceManager but not the other way around. Thus the importance of upgrading the Automation Engine, the ServiceManager Dialog Program and the CLI Program first and the ServiceManagers at the end.

Compatibility

A ServiceManager that supports CAPKI only allows connections of clients (Automation Engine, ServiceManager Dialog Program, and ServiceManager Command Line) that also support CAPKI. However, the ServiceManager Dialog Program and the ServiceManager Command Line can contact legacy ServiceManagers that do not support CAPKI.

Note: The new ServiceManager Dialog Program has an indicator which visualizes whether it is connected to a secure or a legacy (insecure) ServiceManager.

You can configure the compatibility of the Automation Engine using the SMGR_SUPPORT_LEGACY_SECURITY parameter in the UC_SYSTEM SETTINGS variable.

Configuring the CAPKI Environment (UNIX)

To configure the CAPKI environment correctly, you must have the CASHCOMP environment variable pointing to the parent directory of the CAPKI installation directory. If the setting env=all is set during the installation, the CASHCOMP environment variable is added automatically to /etc/profile.CA which is sourced by /etc/profile. If you install the automicsm service daemon start script for the ServiceManager, make sure that the CASHCOMP environment variable is set accordingly in the script.

Example

export CASHCOMP=/opt/CA/SharedComponents

Configurable Cipher

A default cipher suite is used for encryption. As a system administrator, you can define a specific cipher suite using the cipher parameter in the [CAPKI] section of the INI file of the ServiceManager. For more information, see Service Manager Service.

Example

[CAPKI]

;cipher: Cipher suite used for TLS 1.2 communication

cipher=DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256

If an invalid value is defined, the default cipher is used and the corresponding message is written into the log file.

Installing CAPKI

The CAPKI libraries are available for Windows and UNIX platforms supported by the Automation Engine and can be downloaded from the https://downloads.automic.com/.

You can install CAPKI on each computer for various applications and each installation has to be registered with a freely defined name (CallerID). Only the first CAPKI installation installs libraries in the system. All subsequent ones merely register additional applications for use and do not modify existing CAPKI installations. Conversely, you can only uninstall CAPKI (remove the libraries from your system) if no application uses CAPKI anymore. If you try to uninstall CAPKI and there are other applications still using it, the respective application gets unregistered only.

CAPKI keeps and manages a list of the applications that are installed on the system and their respective CAPKI versions. This list must not be modified manually but can be used as a source of information, for example, if you want to uninstall an application and no longer have the relevant CallerID. You can find the list in the following locations:

  • Windows: in the registry in HKLM\SOFTWARE\ComputerAssociates\Shared\CAPKI5\Dependencies
  • UNIX: in the .installdb file in the CAPKI installation directory

Important! Windows installations require administrator privileges. It is recommended to perform UNIX installations with root privileges. However, you can also carry out a UNIX installation under a specific user only. In this case, only a subset of the parameters and settings apply.

To install CAPKI, use the setup.exe (Windows) or setup (UNIX) installer respectively. They support the following parameters:

  • install: Installs CAPKI 

  • remove: Uninstalls CAPKI

  • discover: Searches for all CAPKI installations in the system and logs the results.

    On Windows, it logs information in the file %TEMP%/CAPKI_install.log. On UNIX, it logs information in the file /tmp/CAPKI_install.log and prints the information to the console.

  • CallerID: An arbitrary, freely define name, such as Automic, or AE210 for Automation Engine version 21.0

You can also apply the following settings:

  • veryverbose (Mandatory)

    Enables detailed diagnostic output. If this setting is not defined, the installer operates in silent mode without any diagnostic output.

    This setting forces the installer to log the installation steps. On Windows, the steps are logged in the file %TEMP%/CAPKI_install.log. On UNIX, the steps are logged in the file /tmp/CAPKI_install.log and printed to the console.

  • env=<none|user|all> (UNIX only)

    Enables the setting of the CASHCOMP environment variable for a specific user.

    Values allowed:

    none: (default - login must be root) do not set environment variables

    user: set environment variables for the current user only ($HOME/.profile)

    all: (login must be root) set the environment variable for all users

Important! Make sure the installation user has the necessary permissions for the installation directory.

Examples

To install CAPKI, use the setup.exe (Windows) or setup (UNIX) installer in the CAPKI library that you downloaded from https://downloads.automic.com/.

UNIX (root)

Important! It is recommended to carry out UNIX installations with root privileges.

When you install CAPKI in UNIX as root, the following parameters and settings are supported:

./setup install caller=automic veryverbose env=all

Installs CAPKI and sets environment variables for all users (/etc/profile).

./setup install caller=automic veryverbose env=none

Installs CAPKI but it does not set any environment variables.

./setup remove caller=automic veryverbose

Uninstalls CAPKI.

./setup discover

Searches for CAPKI installations in the system.

UNIX (non-root)

Important! It is recommended to carry out UNIX installations with root privileges. However, you can also carry out a UNIX installation for the current user only.

When you install CAPKI in UNIX without root privileges, only the following parameters and settings are supported:

./setup install caller=automic veryverbose env=user

Installs CAPKI locally and sets the environment variables for the current user only ($HOME/.profile)

./setup remove caller=automic veryverbose env=user

Uninstalls CAPKI but it does not delete the environment variables from $HOME/.profile

./setup discover

Searches for CAPKI installations in the system (root), not installations in the current user's $HOME directory.

Windows

Important! Windows installations require administrator privileges.

setup.exe install caller=automic veryverbose

Installs CAPKI.

setup.exe remove caller=automic veryverbose

Uninstalls CAPKI.

setup.exe discover

Searches for CAPKI installations in the system.

Setup Return Codes

The setup return codes indicate if the installation was successful or if it failed and are written to the log. You can retrieve the setup return code with the following commands:

  • Windows: echo %errorlevel%
  • UNIX: echo $?

The possible return codes are:

  • 0 Success

  • 1 (Windows) Success, reboot required to cleanup temporary files

  • 2 (Windows) Success, reboot required to complete installation (*)

  • 3 Failure (Details are written into the log file)

(*) CAPKI may not be available for use until a reboot has been performed.

Logging and Diagnostics

The installation log file capki_install.log is generated upon installation and contains error, warning, and information messages. You can find the log file in the temp directory:

  • Windows: %TEMP%
  • UNIX: /tmp

Notes:

  • If CAPKI is not installed (correctly) on a computer on which a new ServiceManager is installed, the ServiceManager behaves like a legacy one (insecure communication). A corresponding warning is printed to the ServiceManager log.

  • If CAPKI is not installed (correctly) on a computer on which a new ServiceManager Dialog Program or CLI Program is installed, the program can only connect to ServiceManagers that do not use CAPKI.

Configuring the Automation Engine and the ServiceManager

Certificate Handling

The ServiceManager uses cryptographic keys and a certificate to establish a TLS-secured connection. At startup, the Automation Engine and the ServiceManager automatically create their own self-signed certificates and key files and write the path information in the [CAPKI] section of their configuration (.INI) files. You must use the .pem format for own certificates.

Example for Windows

[CAPKI]

certificate=C:\Automic\Automation.Platform\AutomationEngine\bin\ucsrv_certificate.pem

key=C:\Automic\Automation.Platform\AutomationEngine\bin\ucsrv_key.pem

;chain=

trusted_cert_folder=.\trusted

Important! It is recommended to replace the certificates generated automatically with certificates that are issued by a certification authority (CA). You have to define the path to your own certificate and key file in the corresponding configuration (.INI) file.

Certificate Validation

The Automation Engine, ServiceManager Service, ServiceManager Dialog Program, and ServiceManager CLI do not validate any certificate by default. This means that, by default, all certificates are trusted. The ServiceManager, Dialog Program, and CLI can handle their own certificate trust stores, which contain all trusted certificates.

To enable certificate validation, you have to create a folder that contains all certificates that the component should consider as trusted. The default path for this folder is defined in the configuration (.INI) file of the component: trusted_cert_folder=.\trusted.

Example

Automation Engine A has a certificate in its trust store while Automation Engine B does not. If both try to start a non-TLS agent connected directly to a communication process (CP) from the Administration perspective, Automation Engine A is successful, while Automation Engine B gets a message stating that the connection to the ServiceManager was not successful due to a certificate validation error.

Important! If the ServiceManager and one of its clients (such as the CLI Program) are located in the same .\bin folder, you have to separate the two trusted folders. To do so, create a second folder and modify the parameter in the configuration (.INI) file of the ServiceManager. For example, trusted_cert_folder=.\sm_trusted.

If at least one certificate (.pem format) is stored in the defined folder, the component verifies the trust of certificate when establishing a connection. A certificate is trusted if the certificate itself or the Certification Authority (CA) that signed the certificate is present. Otherwise, the certificate is not considered as trusted and the connection is terminated.

Certificate Renewal

Certificates only need to be renewed if they have expired or are about to expire and you are using a trust store. In this case, the ServiceManager Dialog displays the error message Certificate Validation Error: Trusted connection could not be established.

An existing certificate can be renewed automatically (self-signed certificates) or you can provide your own certificate. In both cases, the new certificate must be added to the trust store of all components that will connect to the one with the new certificate:

  • Automatic renewal

    The ServiceManager generates a new certificate if it cannot find an existing one. In this case, you have to delete the UCYBSMgr_certificate.pem and UCYBSMgr_key.pem files from the .\bin directory of the ServiceManager and restart it. During the startup process, the ServiceManager generates a new private key and certificate.

    For the Automation Engine, delete the ucsrv_certificate.pem and ucsrv_key.pem files from the .\bin directory of the Automation Engine and restart all communication processes (CPs)

  • Own certificate

    You can generate your own certificates and keys (.pem format).

    Tip: It is recommended using a key size of at least 4069 bits.

    You can define the path to the certificate, optional intermediate certificates (chain), and the key file location in the configuration (.INI) file of the ServiceManager (see Service Manager Service) and Automation Engine (see Automation Engine) respectively.

Trust Store Update

For security reasons, new certificates are not distributed automatically. Since every component needs the certificate of the components to which it connects to, you have to copy the new certificates to the trust store of all those components. The distribution process can be more efficient if the certificates you supply are signed by a certification authority (CA). In this case, only the signing CA must be added to the trust store and all certificates signed by the authority are trusted automatically.

Client Certification

The ServiceManager Dialog Program and the ServiceManager CLI, by default, do not have to present a certificate when they connect to the ServiceManager because they authenticate with a password. However, you can enable client certification in the [CAPKI] section of the INI file of the ServiceManager using the client_certification=y parameter as an additional security step. In this case, the clients require a certificate for authentication.

More information:

Use a certificate and key pair issued by a certification authority (CA) on the client's side. You have to define the path to the certificate and key files in the INI file. Some certificates may require an intermediate certificate for validation if the signing certificate authority is not trusted directly. If so, you have to point to the location of the intermediate certificate using a command line or INI file parameter, respectively.

  • The certificate and key files for the ServiceManager Dialog Program are assigned in the [CAPKI] section of its INI file, see ServiceManager - Dialog Program.

    Example

    In this example, the certificate and key files are located in the .\bin directory of the ServiceManager - Dialog Program.

    [CAPKI]

    certificate=C:\Automic\Automation.Platform\ ServiceManagerDialog\bin\<certificatefilename>.pem

    key=C:\Automic\Automation.Platform\ ServiceManagerDialog\bin\<keyfilename>.pem

    ;chain=

    trusted_cert_folder=.\trusted

    Use the parameter chain=<chain file name> in the [CAPKI] section of the INI file to point to the location of the intermediate certificate, if needed.

  • The certificate and key files for the ServiceManager CLI have to be provided as additional command line parameters, see ServiceManager - Command Line Program (CLI).

    Example

    In this example, the certificate and key files are located in the .\bin directory of the ServiceManager - CLI.

    ucybsmcl -c GET_PROCESS_LIST -h unixw2k01:8871 -n uc4p -certificate C:\Automic\Automation.Platform\ ServiceManagerDialog\bin\<certificatefilename>.pem -key C:\Automic\Automation.Platform\ ServiceManagerDialog\bin\<keyfilename>.pem

    Use the command line parameter -chain <chain file name> to point to the location of the intermediate certificate, if needed.

If the client certification is enabled and the client does not have a certificate or if the certificate validation fails, the connection is terminated. In this case, the ServiceManager writes a corresponding log entry and returns an error message to the client.