Customizing the SSL connection between IBM i agents and a master domain manager or a dynamic domain manager using your own certificates

Customizing the SSL connection between a master domain manager or a dynamic domain manager and IBM i agents connected to it using your own certificates.

About this task

By default the communication between IBM i agents and a master domain manager or a dynamic domain manager to which they are registered uses the https protocol.

The SSL communication uses the default certificates provided by HCL Workload Automation.

The master domain manager uses two keystores in .jks format: a private key keystore and a trusted key keystore:
On Windows systems
Private keys keystore
TWA_home>\usr\servers\engineServer\resources\security\TWSServerKeyFile.jks
Trusted keys keystore
TWA_home>\usr\servers\engineServer\resources\security\TWSServerTrustFile.jks
On UNIX systems
Private keys keystore
TWA_DATA_DIR>/usr/servers/engineServer/resources/security/TWSServerKeyFile.jks
Trusted keys keystore
TWA_DATA_DIR>/usr/servers/engineServer/resources/security/TWSServerTrustFile.jks

If you want to use your own customized certificates for this communication because you customized the master domain manager or the dynamic domain manager certificates, you must customize the agent certificates and the agent configuration file.

To enable communication between a master domain manager or a dynamic domain manager and an IBM i agent, you must first create your own certificates for IBM i agent and then trust the agents certificates in the master domain manager or the dynamic domain manager keystore.

Perform the following steps:
  1. Log on as Administrator on Windows operating systems or as root on UNIX and Linux operating systems, on the machine where you installed a HCL Workload Automation instance that contains the openssl utility, for example, the master domain manager or the dynamic domain manager.
  2. Go to the TWS_INST_DIR/TWS/ssl directory, where TWS_INST_DIR is the HCL Workload Automation installation directory and copy there the following files:
    • TWS_INST_DIR/TWS/bin/openssl(.exe)
    • TWS_INST_DIR/TWS/bin/openssl.cnf
  3. Generate a random file for the IBM i agent, by using the following command:
    openssl rand 
-out suffix.rnd 
-rand ./openssl 8192
    where suffix is a generic word. For example, you can use the IBM i agent workstation name to easily find the files generated for this workstation.
  4. Generate the suffix.key private key, by running the following command:
    openssl genrsa -des3 
-out suffix.key 2048
    and save the password that you entered in the previous command in the suffix.pwd file.
    Note: Ensure that you take note of the password you insert because you need it in the following steps.
  5. Generate the ita_prvsuffix.pem PEM file containing the agent private key, by renaming the suffix.key in ita_prvsuffix.pem.
  6. Save the agent private key password in a suffix.sth stash file by using the following command:
    openssl base64 
-in suffix.pwd 
-out suffix.sth
  7. Generate the suffix.csr certificate signature request by running the following command:
    openssl req -new 
-key suffix.key 
-out suffix.csr
-config ./openssl.cnf
  8. Generate the suffix.crt certificate that contains the private key suffix.key by running the following command:
    openssl x509 -req
-CA TWSca.crt 
-CAkey TWSca.key
-days 365
-in suffix.csr
-out suffix.crt
-CAcreateserial
  9. Generate the suffix.pem PEM file containing the agent private key certificate by creating a copy of the suffix.crt certificate, and name the copied file suffix.pem.
  10. Generate the ita_pubsuffix.pem PEM file containing the agent private key certificate by creating a copy of the suffix.crt certificate, and name the copied file ita_pubsuffix.pem.
  11. Create a copy of the ita_pubsuffix.pem file created in step 10 and name the copied file ita_certsuffix.pem.
  12. On the master domain manager or the dynamic domain manager machine to which the IBM i agent is to be connected, generate the server.pem certificate by running the command:
    keytool -export -rfc
-alias server 
-file TWS_INST_DIR/TWS/ssl/server.pem
-keypass password>
-keystore path/TWSServerKeyFile.jks
-storepass default
    where password> is the value you entered in step 4 and path is the path listed at the beginning of this topic.
  13. Generate the ita_ca_certsuffix.pem file which is the concatenation of the ita_pubsuffix.pem and of the server.pem files, by performing the following actions:
    1. Create a copy of the ita_pubsuffix.pem file and name it ita_ca_certsuffix.pem.
    2. Edit the ita_ca_certsuffix.pem file.
    3. Append at the end of the ita_ca_certsuffix.pem file content the server.pem file content.
    4. Save the final version of the ita_ca_certsuffix.pem file.
    Note: The ita_ca_certsuffix.pem file contains the certificates of the IBM i agent and the master domain manager or the dynamic domain manager to which the agent is connected.
  14. Log on as TWS_IBMi_USER user on the IBM i agent machine and locate the TWS_IBMI_INSTDIR/TWS/ITA/cpa/ita/cert/ directory where TWS_IBMI_INSTDIR is the directory where you installed the HCL Workload Automation IBM i agent for the TWS_IBMi_USER user.
  15. From the TWS_INST_DIR/TWS/ssl directory of the machine where you generated the PEM files, copy into the TWS_IBMI_INSTDIR/TWS/ITA/cpa/ita/cert/ directory of the IBM i agent installation directory the following files:
    • ita_prvsuffix.pem.
    • ita_pubsuffix.pem.
    • ita_certsuffix.pem.
    • ita_ca_certsuffix.pem.
    • suffix.sth.
    • suffix.rnd.
    Note: Ensure that the files you copied have TWS_IBMi_USER ownership.
  16. On the machine where you installed the IBM i agent, open the ita.ini configuration agent file and set the values appropriate for your environment in the following properties: Where:
    stash_file_fullpath
    Specify the fully qualified path to the suffix.sth stash file that contains the agent private key password. This is the file you created in step 6. The default value is TWS_IBMI_INSTDIR/TWS/ITA/cpa/ita/cert/password.sth.
    random_file_fullpath
    Specify the fully qualified path to the suffix.rnd random file. This is the file that you created in step 3. The default is TWS_IBMI_INSTDIR/TWS/ITA/cpa/ita/cert/TWS.rnd.
    label_agent_private_key
    Specify the label of the agent private key.
    suffix
    Specify the suffix that you used in the names of all the files that you generated. The default value is tws.
    directory_ita_*suffix.pem>
    Specify the directory that contains the following .pem files that you generated:
    Truststore
    ita_ca_certsuffix.pem that you generate in step 13
    Keystore
    • ita_prvsuffix.pem that you generated in step 5.
    • ita_pubsuffix.pem that you generated in step 10.
    • ita_certsuffix.pemthat you generated in step 11.
    The default directory is TWS_IBMI_INSTDIR/TWS/ITA/cpa/ita/cert.
  17. Stop the IBM i agent by using the following command:
    ShutDownLwa
  18. Start the IBM i agent by using the following command:
    StartUpLwa
  19. On the master domain manager or the dynamic domain manager machine which the IBM i agent is to be connected to, trust the TWS_INST_DIR/TWS/ssl/suffix.pem IBM i agent certificate that you generated in step 9, in the keystore, by running the following steps:
    keytool -import -trustcacerts
-alias <suffix> 
-file <TWS_INST_DIR>/TWS/ssl/<suffix>.pem
-keypass <password>
-keystore <path>/
    TWSServerTrustFile.jks
-storepass default
    where TWS_INST_DIR is the master domain manager or the dynamic domain manager installation directory and password> is the value you entered in step 4. path is the path listed at the beginning of this topic.

Example

You have the following environment:
  • IBM i agent installed in the opt/hcl/TWS directory of the nc117031 machine for the user twsuserIBMi.
  • Master domain manager installed in the opt/HCL/TWA92 directory of the machine nc060201.
To create the IBM i agent certificates to connect to the master domain manager, perform the following steps:
  1. Log on as root on the nc060201 machine where you installed the master domain manager.
  2. Go to the opt/HCL/TWA92/TWS/ssl directory and copy there the following files:
    • opt/HCL/TWA92/TWS/bin/openssl
    • opt/HCL/TWA92/TWS/bin/openssl.cnf
  3. Generate the nc117031.rnd random file in the opt/HCL/TWA92/TWS/ssl directory by running the following command:
    openssl rand 
-out nc117031.rnd 
-rand ./openssl 8192
  4. Generate the nc117031.key private key in the opt/HCL/TWA92/TWS/ssl directory by running the following command:
    openssl genrsa -des3 
-out nc117031.key 2048
    and save the maestro00 password that you entered in the nc117031.pwd file in text format in the optHCL/TWA92/TWS/ssl directory.
  5. Create a copy of the nc117031.key file in the opt/HCL/TWA892/TWS/ssl directory and name it ita_prvnc117031.pem.
  6. Save the maestro00 password in a nc117031.sth stash file in the opt/HCL/TWA92/TWS/ssl directory by running the following command:
    openssl base64 
-in nc117031.pwd 
-out nc117031.sth
  7. Generate the nc117031.csr certificate signature request in the opt/HCL/TWA92/TWS/ssl directory by running the following command:
    openssl req -new 
-key nc117031.key 
-out nc117031.csr
-config ./openssl.cnf
  8. Generate the nc117031.crt certificate in the opt/HCL/TWA92/TWS/ssl directory that contains the private key nc117031.key by running the following command:
    openssl x509 -req
-CA TWSca.crt 
-CAkey TWSca.key
-days 365
-in nc117031.csr
-out nc117031.crt
-CAcreateserial
  9. Create a copy of the nc117031.crt certificate in the opt/HCL/TWA92/TWS/ssl directory and name it nc117031.pem.
  10. Create a copy of the nc117031.crt certificate in the opt/HCL/TWA92/TWS/ssl directory and name it ita_pubnc117031.pem.
  11. Create a copy of the ita_pubnc117031.pem file in the opt/HCL/TWA92/TWS/ssl directory and name it ita_certnc117031.pem.
  12. On the nc060201 machine, generate the server.pem certificate in the opt/HCL/TWA92/TWS/ssl directory by running the following command:
    keytool -export -rfc
-alias server 
-file opt/HCL/TWA/TWS/ssl/server.pem
-keypass maestro00
-keystore path>/TWSServerKeyFile.jks
-storepass default

    where path is the path listed at the beginning of this topic.

  13. Generate the ita_ca_certnc117031.pem file in the opt/HCL/TWA/TWS/ssl directory which is the concatenation of the ita_pubnc117031.pem and the server.pem files, by performing the following actions:
    1. Create a copy of ita_pubnc117031.pem file in the opt/HCL/TWA/TWS/ssl directory and name it ita_ca_certnc117031.pem.
    2. Edit the ita_ca_certnc117031.pem file.
    3. Append at the end of the ita_ca_certnc117031.pem file content the server.pem file content.
    4. Save the final version of the ita_ca_certnc117031.pem file.
  14. Log on as twsuserIBMi user on the nc117031 machine and locate the opt /hcl/TWS/ITA/cpa/ita/cert/directory.
  15. From the opt/HCL/TWA/TWS/ssl directory of the nc060201 machine where you generated the PEM files, copy into the opt/ hcl/TWS/ITA/cpa/ita/cert/directory the following files:
    • ita_prvnc117031.pem.
    • ita_pubnc117031.pem.
    • ita_certnc117031.pem.
    • ita_ca_certnc117031.pem.
    • nc117031.sth.
    • nc117031.rnd.
    Ensure that all the files have twsuserIBMi ownership.
  16. On the nc117031 machine, open the ita.ini configuration agent file and set the following values for the listed properties: 
    password_file=opt/hcl/TWS/ITA/cpa/ita/cert/nc117031.sth
random_file=opt/hcl/TWS/ITA/cpa/ita/cert/nc117031.rnd
cert_label=nc117031
key_db_name=nc117031
key_repository_dir=opt/hcl/TWS/ITA/cpa/ita/cert/*nc117031.pem
  17. Stop the IBM i agent by using the following command:
    ShutDownLwa
  18. Start the IBM i agent by using the following command:
    StartUpLwa
  19. On the nc060201 machine, trust the opt/HCL/TWA92/TWS/ssl/nc117031.pem agent certificate by running the following steps: 
    keytool -import -trustcacerts
-alias nc117031 
-file opt/HCL/TWA/TWS/ssl/ssl/nc117031.pem
-keypass maestro00
-keystore path>/TWSServerTrustFile.jks
-storepass default

    where path is the path listed at the beginning of this topic.