Setting up a secure communication between the API and several Collector Server instances

Edit online

If you want to the API to communicate with several Collector Server instances, you must secure all connections.

Before you begin

About this task

To set up secure communication with several Collector Server instances, you use the script file client_key_gen again. In addition, you use the script file that is installed with the add-ons package and has the following fully qualified file name:
InstallHome\api\register_server.bat

For the complete functional scope of this script file, see register_server.

The following procedure shows how to set up secure connections between the API and two Collector Server instances. It is based on the following example situation:
  • The API is installed on a system with two users who are supposed to share a certificate. Therefore, you need only one client keystore. The users are called cuser1 and cuser2 in this example.
  • The API is to communicate with two Collector Server instances, which are called myserverA and myserverB in this example. Therefore, you need two server keystores, one on myserverA and one on myserverB.
  • The server keystores are to be encrypted with the passwords secureA and secureB.

For this example, it is also assumed that you decide to create the required client keystore on myserverA and that you use the default names for the keystores.

Tip: Keep a record of all names and labels that you assign, the location of the keystores, and the number of the client keystores that you already created on each Collector Server instance. Also, document which certificate belongs to which user and which certificates are shared by which users.

Procedure

  1. On myserverA, create a server keystore, a client keystore, and the certificates. Use the client_key_gen script file.
    1. Open a command line and change to the directory where the folder for the server keystore is to be stored.
    2. Enter either of the following commands, depending on your operating system:
      • LinuxUNIX client_key_gen.sh -c -p secureA -n 1
      • Windows client_key_gen.bat -c -p secureA -n 1

      In the directory where you entered the command, the following folders are created: server and client_1. The name of the server keystore is server.kdb. The name of the client keystore is client_1.kdb. The server keystore contains the certificate clientcert_1.crl. The client keystores contain the certificate servercert.crl. The server keystore is encrypted with the password secureA.

  2. Copy the client_1 folder from myserverA to the system where the API is installed.
    You can paste the folder to a directory of your choice.
  3. On myserverB, create a server keystore and the certificate for myserverB. Use the client_key_gen script file.
    1. Open a command line and change to the directory where the folder for the server keystore is to be stored.
    2. Enter either of the following commands, depending on your operating system:
      • LinuxUNIX client_key_gen.sh -c -p secureB
      • Windows client_key_gen.bat -c -p secureB

      In the directory where you entered the command, the following folder is created: server. The name of the server keystore is server.kdb. The server keystore contains the certificate servercert.crl. The server keystore is encrypted with the password secureB.

  4. Copy the server certificate servercert.crl of myserverB to the system where the API is installed.
    You can paste the certificate to a directory of your choice.
  5. Add the server certificate of myserverB to the client keystore. Use the register_server.bat script file from the add-ons package.
    1. Open a command line and change to any directory.
      When you run the script file, you can specify the relative path to the client keystore and to the server certificate.
    2. Enter the following command: 
      register_server.bat -add -cdb relative_path\client_1.kdb
-scert relative_path\servercert.crl -sl new_certificate_label

      relative_path stands for the path that is relative to the directory where you entered the command. new_certificate_label is the new label for the server certificate that is added. A new label is necessary because both server certificates have the same default name servercert.crl.

      Assume, for example, that you copied the client_1 folder and the servercert.crl to the C:\security directory and that you want to issue the command from the C: directory. Also, assume that the server certificate that is to be added should receive the label servercert_B. Your command would then look as follows:
      register_server.bat -add -cdb security\client_1\client_1.kdb
-scert security\servercert.crl -sl servercert_B
  6. Copy the client certificate clientcert_1.crl to myserverB.
    You can paste the certificate to a directory of your choice.
  7. Add the client certificate to the server keystore for myserverB. Use the client_key_gen script file.
    1. Open a command line and change to any directory.
      When you run the script file, you can specify the relative path to the server keystore and to the client certificate. In addition, you can specify a different label for the client certificate.
    2. Enter either of the following commands, depending on your operating system:
      • LinuxUNIX client_key_gen.sh -add -sdb relative_path/server.kdb -p secureB -ccert relative_path/clientcert_1.crl -cl new_certificate_label
      • Windows client_key_gen.gen -add -sdb relative_path\server.kdb -p secureB -ccert relative_path\clientcert_1.crl -cl new_certificate_label
  8. On the system where the API is installed, copy the client_1 folder, which contains the certificate that is to be shared by both users on the system, to either of the following locations:
    • UserHome directory of each user, such as the env_var_appdata\IBM\ICCSAP\security directory
    • A directory that is accessible by both users. Ensure that both users have read access for this directory.
    Important: In any case, strictly control the access to the client folder and to the directory where the client folder is stored. Content Collector for SAP does not protect the client keystore and its contents with a password.
  9. Enable each Collector Server instance to use its server keystore by changing each instance configuration. In Configuration Feature, take these steps:
    1. Open the instance configuration that you want to change.
    2. Go to Basic Configuration > Communication.
    3. Complete the Communication with the API section.
  10. Restarting a Collector Server instance.
    To restart the instances from a command line, you use the archpro command with the following parameters:
    archpro -i profile -f dll_keystore_passwd password
    In a server configuration profile, you find the following specifications that relate to the communication with the API:
    Section in server configuration profile Keyword UI field that supplies the value
    Global section ARCHWINS Client dispatchers
    DLL_KEYSTORE_FILE Server keystore
  11. Update the client configuration profile for each user: open the csclient.ini file in a text editor and set the keystore parameter to the fully qualified file name of the client keystore that contains the certificate for the user.
    Open the csclient.ini file in a text editor and set the keystore parameter to the fully qualified file name of the client keystore that contains the certificate for the user. If you decided to place the client_1 folder into a directory that is accessible by both users, your specification might look as in the following example:
    keystore=C:\Users\security\client_1\client_1.kdb