Scenario: configuring TLS with custom self-signed certificates

About this task

The SSL connection between HCL Workload Automation for Z and other components is established by using certificates. With TLS v1.2 you can use either default or custom certificates; with TLS v1.3 you can use only custom certificates, which are more adequate to the security standards of this version. The following scenario describes the steps to set up TLS with custom self-signed certificates to connect HCL Workload Automation for Z with the Dynamic Workload Console, tracker, or dynamic domain manager for z/OS.

On the z/OS system where the Z controller runs, create the database and custom self-signed certificates by performing the following steps:
1. From the directory where you want to store your certificates (in this example, /u/tlscertificates) run the gskkyman utility.
2. From the Database Menu, select option 1 Create new database and follow the prompts to create the database (in this example, tlscontroller.kdb).
  The following files are created: tlscontroller.kdb and tlscontroller.rdb
3. From the Database Menu, select option 2 Open database and provides the database name and related password.
4. From the Key Management Menu, select option 10 Store database password to save the password in a stash file.
5. Create your own Certificate Authority (CA) for the Z controller (in this example, cacontroller) by selecting the following options:
  1. 6 - Create a self-signed certificate
  2. 1 - CA Certificate
  3. 1 - Certificate with an RSA key
  4. 3 - 4096-bit key
  5. 5 - SHA-512
6. Create the certificate for the Z controller (in this example, certcontroller) by selecting the following options:
  1. 6 - Create a self-signed certificate
  2. 2 - User or server specifications
  3. 1 - Certificate with an RSA key
  4. 3 - 4096-bit key
  5. 5 - SHA-512
  Take note of the Common Name that you specify because it will be required if you are configuring the dynamic domain manager for z/OS.
7. Export the CA and certificate of the Z controller (in this example, cacontroller.crt and certcontroller.crt) by selecting the following options from the Database Menu:
  1. 1 - Manage keys and certificates (select the certificate to be exported)
  2. 6 - Export certificate to a file
  3. 2 - BASE64 – ASN.1 DER
8. Repeat this same procedure to create the database (for example, tlstracker.kdb) and certificates (catracker.crt e certtracker.crt) for the tracker, and export them to a stash file.
9. From the Database Menu of the Z controller database (tlscontroller.kdb), import the tracker certificates (catracker.crt and certtracker.crt) by selecting Option 7 - Import a certificate.
10. From the Database Menu of the tracker database (tlstracker.kdb), import the Z controller certificates (cacontroller.crt and certcontroller.crt) by selecting Option 7 - Import a certificate.
11. From the Database Menu of the Z controller database (tlscontroller.kdb), trust the CA of the tracker by selecting the following options:
  1. 2 - Manage certificates, then press Enter to show the list of labels and select the tracker CA (in this example, catracker)
  2. 2 - Set certificate trust status, then select 1 to mark the tracker CA as trusted.
12. From the Database Menu of the tracker database (tlstracker.kdb), trust the CA of the Z controller by selecting the following options:
  1. 2 - Manage certificates, then press Enter to show the list of labels and select the controller CA (in this example, cacontroller)
  2. 2 - Set certificate trust status, then select 1 to mark the controller CA as trusted.
13. Open each database that you created (tlscontroller.kdb and tlstracker.kdb) and set the default certificate. From the Database Menu select the following options:
  1. 1 - Manage keys and certificates and select the certificate to be used as default (that is, certificate certcontroller in tlstracker.kdb and certificate certtracker in tlscontroller.kdb
  2. 3 - Set key as default
14. On the Z controller, set the following parameters in the TCPOPTS statement:
```
SSLKEYSTORE(/u/tlscertificates/tlscontroller.kdb) 
SSLKEYSTOREPSW(/u/tlscertificates/tlscontroller.sth)
```
15. On the tracker, set the following parameters in the TCPOPTS statement:
```
SSLKEYSTORE(/u/tlscertificates/tlstracker.kdb) 
SSLKEYSTOREPSW(/u/tlscertificates/tlstracker.sth)
```
For more details about how to configure the TCP/IP connection, see Security for TCP/IP connections. For more details about how to configure the HTTP connection, see Security for HTTP connections.
To configure the TLS connection with the Dynamic Workload Console or DDM for z/OS, perform the following steps:
1. From the directory where you have stored your certificates (in this example, /u/tlscertificates) run the gskkyman utility.
2. From the Database Menu select option 2 - Open database and open the tracker database (tlstracker.kdb).
3. Export the keys and certificates to a file (catracker.p12 and certtracker.p12, respectively) by selecting the following options:
  1. 1 - Manage keys and certificates, then select the certificate labels to be exported (catracker and certtracker)
  2. 7 - Export certificate and key to a file
  3. 3 - Binary PKCS #12 Version 3
4. Transfer the keys and certificates (catracker.p12 and certtracker.p12) to the workstation where the component to be connected is installed, by using the FTP protocol in binary mode. Transfer also the CA of the controller (cacontroller.crt) by using FTP in ASCII mode.
5. From the workstation where the Dynamic Workload Console or dynamic domain manager for z/OS is installed, import the catracker.p12 and certtracker.p12 files into TWSServerKeyFile.jks by using the keytool utility:
```
keytool -importkeystore -deststorepass <password> -destkeypass <password> 
-destkeystore "<complete_path>\TWSServerKeyFile.jks" -srckeystore "<complete_path>\<filename>.p12" 
-srcstoretype PKCS12 -srcstorepass <password>
```
6. Trust the Z controller certificate cacontroller.crt in TWSServerTrustFile.jks:
```
keytool -importcert -trustcacerts -keystore "<complete_path>\TWSServerTrustFile.jks" 
-storepass <password> -file "<complete_path>\cacontroller.crt" -alias cacontroller 
```
  When prompted Trust this certificate?, click Y.
According to the component whose connection you are configuring, perform the following step:
For the Dynamic Workload Console v10.1
1. Transfer the tracker certificate certtracker.crt by using FTP in ASCII mode to the workstation where the Dynamic Workload Console is installed.
2. From the workstation where the Dynamic Workload Console is installed, import certtracker.crt into the trust store TWSServerTrustFile.jks by issuing the following command:
```
keytool -importcert -trustcacerts -keystore "<complete_path>\TWSServerTrustFile.jks" 
-storepass <password> -file "<complete_path>\certtracker.crt " -alias certtracker 
```
3. In the connectionFactory.xml file set useSsl="true", then restart the Dynamic Workload Console. For example:
```
<connectionFactory id="EngineZ"
       jndiName="eis/tws/zconn/EngineZ">
       <properties.ZConnectorAdapter hostName="10.999.49.333"
       portNumber="9919"
       useSsl="true">
```
For the dynamic domain manager for z/OS
1. On your z/OS system, run gskkyman and from Database Menu select the following options:
  1. 2 - Open database, then select tlscontroller.kdb
  2. 9 - Show the default key
  In the file C:\Program Files\IBM\DDM101\TWS\broker\config\BrokerWorkstation.properties file, set the following property with the Common Name that you have defined earlier in this procedure:
```
Broker.AuthorizedCNs= Server;ServerNew;<CommonName>
```
2. Restart the dynamic domain manager for z/OS.