HCL Workload Automation, Version 9.4

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.

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_prv<suffix>.pem PEM file containing the agent private key, by renaming the <suffix>.key in ita_prv<suffix>.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_pub<suffix>.pem PEM file containing the agent private key certificate by creating a copy of the <suffix>.crt certificate, and name the copied file ita_pub<suffix>.pem.
  11. Create a copy of the ita_pub<suffix>.pem file created in step 10 and name the copied file ita_cert<suffix>.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 <TWS_INST_DIR>/TWA/WAS/TWSprofile/etc/TWSServerKeyFile.jks
-storepass default
    where <password> is the value you entered in step 4.
  13. Generate the ita_ca_cert<suffix>.pem file which is the concatenation of the ita_pub<suffix>.pem and of the server.pem files, by performing the following actions:
    1. Create a copy of the ita_pub<suffix>.pem file and name it ita_ca_cert<suffix>.pem.
    2. Edit the ita_ca_cert<suffix>.pem file.
    3. Append at the end of the ita_ca_cert<suffix>.pem file content the server.pem file content.
    4. Save the final version of the ita_ca_cert<suffix>.pem file.
    Note: The ita_ca_cert<suffix>.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_prv<suffix>.pem.
    • ita_pub<suffix>.pem.
    • ita_cert<suffix>.pem.
    • ita_ca_cert<suffix>.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: 
    password_file=<stash_file_fullpath>
random_file=<random_file_fullpath>
cert_label=<label_agent_private_key>
key_db_name=<suffix>
key_repository_dir=<directory_ita_*<suffix>.pem>
    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_cert<suffix>.pem that you generate in step 13
    Keystore
    • ita_prv<suffix>.pem that you generated in step 5.
    • ita_pub<suffix>.pem that you generated in step 10.
    • ita_cert<suffix>.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 <TWS_INST_DIR>/TWA/WAS/TWSprofiles/etc/
    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.

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 opt/HCL/TWA/WAS/TWSprofile/etc/TWSServerKeyFile.jks
-storepass default
  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 opt/HCL/TWA/WAS/TWSprofile/etc/TWSServerTrustFile.jks
-storepass default