In order to ease the deployment of custom TLS (SSL) certificates to secure the communication between each component of an IBM/HCL Workload Automation (WA) deployment, certificates in PEM (Privacy Enhanced Mail) can be made available in a folder. During the installation, they are used to create and share the KeyStores and TrustStores required for the deployment.
The same certificate can be used to deploy the Master Domain Manager (MDM), Dynamic Workload Console (DWC), and Agents.
1 Issuing TLS Certificates in PEM Format
The following sections describe the procedure to generate the certificates.
1.1 Create a Certificate for the ServerFollow the steps below to create a certificate for the server where the MDM, DWC, or agent will be deployed.
1.Create a Private Key with AES 256 Encryption and 4096 bits long:
iwadmin@glowfish::/home/iwadmin> mkdir certs
iwadmin@glowfish::/home/iwadmin> cd certs
iwadmin@glowfish::/home/iwadmin/certs> openssl genrsa -aes256 -out tls.key 4096
Generating RSA private key, 4096 bit long modulus (2 primes)
.....................................................................................+++++
.....................................................................................+++++
e is 65537 (0x010001)
Enter pass phrase for tls.key:
Verifying - Enter pass phrase for tls.key:
2.Save the passphrase in a file, tls.pwd for future references.
1.2 Create a Certificate Signing Request (CSR) for the ServerFollow the steps below to create a CSR.
1.Create a Certificate Signing Request (CSR) with SAN (Subject Alternate Name), if required:
openssl req -new -key tls.key -out tls.csr -subj "/C=US/ST=North Carolina/L=Raleigh/O=Kics Inc./OU=Automation/CN=glowfish" -addext "subjectAltName=DNS:glowfish.raleigh.ibm.com,DNS:glowfish.ibm.com,DNS:glowfish,IP:192.168.86.209" -config /usr/Tivoli/TWS/OpenSSL64/1.1/bin/openssl.cnf
Enter pass phrase for tls.key:
2.Send the CSR to a commercially recognized Certificate Authority (CA) to be signed.
1.3 Create a Root Certificate Authority (CA)A Root CA can be created for signing certificates instead of sending them to commercial CA for signature. While this may be acceptable for a Dev/Test environment, it is strongly recommended to have the certificates signed by a commercially recognized CA.
Follow the steps below to create a Root CA.
1.Due to a bug in OpenSSL, SANs are not transferred from CSR to CRT when being signed. As a workaround, create a configuration file with the Subject Alternate Names (SAN) information that can be included when signing the certificate.
vi san.ext
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
subjectAltName = @alt_names
[alt_names]
DNS.1=glowfish.raleigh.ibm.com
DNS.2=glowfish.ibm.com
DNS.3=glowfish
IP.1=192.168.86.209
IP.2=192.168.86.210
2.Create a Self-Signed Root CA to sign the certificates
openssl req -x509 -sha256 -days 3610 -newkey rsa:2048 -keyout ca.key -out ca.crt -subj "/C=US/ST=North Carolina/L=Raleigh/O=Kics Inc./OU=Automation/CN=RootCA" -config /usr/Tivoli/TWS/OpenSSL64/1.1/bin/openssl.cnf
Generating a RSA private key
.....................................................................................................+++++
..................................................................................................................+++++
writing new private key to 'ca.key'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
Note: Make sure that the pass phrase entered is the same as the pass phrase entered earlier to create the server certificate.
1.4 Sign the Server Certificate with the Root CAFollow the steps below to sign the server certificate with the Root CA created in the previous step.
1.Sign the CSR generated in a previous step.
iwadmin@glowfish::/home/iwadmin/certs> openssl x509 -req -CA ca.crt -CAkey ca.key -in tls.csr -out tls.crt -days 3650 -CAcreateserial -extfile san.ext
Signature ok
subject=C = US, ST = North Carolina, L = Raleigh, O = Kics Inc., OU = Automation, CN = glowfish
Getting CA Private Key
Enter pass phrase for ca.key:
1.5 Create a Stash File for the Pass PhraseFollow the steps below to create a stash file for the Pass Phrase:
echo -n <pass_phrase> | base 64 > tls.sth
Where, pass_phrase is the pass phrase used earlier while creating the server and Root CA certificates.
1.6 Contents of the Dir Where the Certs Were GeneratedThe following is a list of file created in the directory:
iwadmin@glowfish::/home/iwadmin/certs> ls -lart
total 36
drwx------. 15 iwadmin iwadmin 4096 May 5 15:23 ..
-rw------- 1 iwadmin iwadmin 3326 May 5 15:56 tls.key
-rw-rw-r-- 1 iwadmin iwadmin 1834 May 5 16:06 tls.csr
-rw-rw-r-- 1 iwadmin iwadmin 6 May 5 16:16 tls.pwd
-rw-rw-r-- 1 iwadmin iwadmin 9 May 5 16:16 tls.sth
-rw------- 1 iwadmin iwadmin 1854 May 5 16:30 ca.key
-rw-rw-r-- 1 iwadmin iwadmin 1375 May 5 16:30 ca.crt
-rw-rw-r-- 1 iwadmin iwadmin 41 May 5 16:36 ca.srl
drwxrwxr-x 3 iwadmin iwadmin 134 May 5 16:36 .
-rw-rw-r-- 1 iwadmin iwadmin 1598 May 5 16:36 tls.crt
1.7 Use the Certificates in an On-Prem DeploymentFollow the steps below to use the certificates in an on-prem deployment.
1.Specify the following two parameters during the deployment of the MDM (serverinst), DWC (dwcinst), or an Agent (twsinst):
sslkeysfolder The name and path of the folder containing the certificates in PEM format
sslpassword The pass phrase for the certificates
1.8 Use the Certificates in a Containerized DeploymentFollow the steps below to use the certificates in a containerized deployment.
1.In a docker-compose deployment, make the certificates available in the wa-certificates folder. This folder is mounted to /opt/wautils/certs in the container.
2.Specify the pass phrase in the parameter, SSL_PASSWORD, for each service in the docker-compose.yml file.
3.In a Kubernetes deployment, a Cert Manager is used to issue certificates, but it needs a CA certificate to be created with a pass phrase. This pass phrase can be saved in a configuration file, mysecret.yaml, with the parameter, SSL_PASSWORD.
1.9 Renewing the CertificatesThe certificates in PEM format are used to create the KeyStores and TrustStores during the deployment. When the certificates expire, they have to be updated in the KeyStores and TrustStores. Please follow the instructions in the blog post, Replacing Default SSL Certificates with CA signed Custom Certificates.
The following sections describe the procedure to generate the certificates.
1.1 Create a Certificate for the ServerFollow the steps below to create a certificate for the server where the MDM, DWC, or agent will be deployed.
1.Create a Private Key with AES 256 Encryption and 4096 bits long:
iwadmin@glowfish::/home/iwadmin> mkdir certs
iwadmin@glowfish::/home/iwadmin> cd certs
iwadmin@glowfish::/home/iwadmin/certs> openssl genrsa -aes256 -out tls.key 4096
Generating RSA private key, 4096 bit long modulus (2 primes)
.....................................................................................+++++
.....................................................................................+++++
e is 65537 (0x010001)
Enter pass phrase for tls.key:
Verifying - Enter pass phrase for tls.key:
2.Save the passphrase in a file, tls.pwd for future references.
1.2 Create a Certificate Signing Request (CSR) for the ServerFollow the steps below to create a CSR.
1.Create a Certificate Signing Request (CSR) with SAN (Subject Alternate Name), if required:
openssl req -new -key tls.key -out tls.csr -subj "/C=US/ST=North Carolina/L=Raleigh/O=Kics Inc./OU=Automation/CN=glowfish" -addext "subjectAltName=DNS:glowfish.raleigh.ibm.com,DNS:glowfish.ibm.com,DNS:glowfish,IP:192.168.86.209" -config /usr/Tivoli/TWS/OpenSSL64/1.1/bin/openssl.cnf
Enter pass phrase for tls.key:
2.Send the CSR to a commercially recognized Certificate Authority (CA) to be signed.
1.3 Create a Root Certificate Authority (CA)A Root CA can be created for signing certificates instead of sending them to commercial CA for signature. While this may be acceptable for a Dev/Test environment, it is strongly recommended to have the certificates signed by a commercially recognized CA.
Follow the steps below to create a Root CA.
1.Due to a bug in OpenSSL, SANs are not transferred from CSR to CRT when being signed. As a workaround, create a configuration file with the Subject Alternate Names (SAN) information that can be included when signing the certificate.
vi san.ext
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
subjectAltName = @alt_names
[alt_names]
DNS.1=glowfish.raleigh.ibm.com
DNS.2=glowfish.ibm.com
DNS.3=glowfish
IP.1=192.168.86.209
IP.2=192.168.86.210
2.Create a Self-Signed Root CA to sign the certificates
openssl req -x509 -sha256 -days 3610 -newkey rsa:2048 -keyout ca.key -out ca.crt -subj "/C=US/ST=North Carolina/L=Raleigh/O=Kics Inc./OU=Automation/CN=RootCA" -config /usr/Tivoli/TWS/OpenSSL64/1.1/bin/openssl.cnf
Generating a RSA private key
.....................................................................................................+++++
..................................................................................................................+++++
writing new private key to 'ca.key'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
Note: Make sure that the pass phrase entered is the same as the pass phrase entered earlier to create the server certificate.
1.4 Sign the Server Certificate with the Root CAFollow the steps below to sign the server certificate with the Root CA created in the previous step.
1.Sign the CSR generated in a previous step.
iwadmin@glowfish::/home/iwadmin/certs> openssl x509 -req -CA ca.crt -CAkey ca.key -in tls.csr -out tls.crt -days 3650 -CAcreateserial -extfile san.ext
Signature ok
subject=C = US, ST = North Carolina, L = Raleigh, O = Kics Inc., OU = Automation, CN = glowfish
Getting CA Private Key
Enter pass phrase for ca.key:
1.5 Create a Stash File for the Pass PhraseFollow the steps below to create a stash file for the Pass Phrase:
echo -n <pass_phrase> | base 64 > tls.sth
Where, pass_phrase is the pass phrase used earlier while creating the server and Root CA certificates.
1.6 Contents of the Dir Where the Certs Were GeneratedThe following is a list of file created in the directory:
iwadmin@glowfish::/home/iwadmin/certs> ls -lart
total 36
drwx------. 15 iwadmin iwadmin 4096 May 5 15:23 ..
-rw------- 1 iwadmin iwadmin 3326 May 5 15:56 tls.key
-rw-rw-r-- 1 iwadmin iwadmin 1834 May 5 16:06 tls.csr
-rw-rw-r-- 1 iwadmin iwadmin 6 May 5 16:16 tls.pwd
-rw-rw-r-- 1 iwadmin iwadmin 9 May 5 16:16 tls.sth
-rw------- 1 iwadmin iwadmin 1854 May 5 16:30 ca.key
-rw-rw-r-- 1 iwadmin iwadmin 1375 May 5 16:30 ca.crt
-rw-rw-r-- 1 iwadmin iwadmin 41 May 5 16:36 ca.srl
drwxrwxr-x 3 iwadmin iwadmin 134 May 5 16:36 .
-rw-rw-r-- 1 iwadmin iwadmin 1598 May 5 16:36 tls.crt
1.7 Use the Certificates in an On-Prem DeploymentFollow the steps below to use the certificates in an on-prem deployment.
1.Specify the following two parameters during the deployment of the MDM (serverinst), DWC (dwcinst), or an Agent (twsinst):
sslkeysfolder The name and path of the folder containing the certificates in PEM format
sslpassword The pass phrase for the certificates
1.8 Use the Certificates in a Containerized DeploymentFollow the steps below to use the certificates in a containerized deployment.
1.In a docker-compose deployment, make the certificates available in the wa-certificates folder. This folder is mounted to /opt/wautils/certs in the container.
2.Specify the pass phrase in the parameter, SSL_PASSWORD, for each service in the docker-compose.yml file.
3.In a Kubernetes deployment, a Cert Manager is used to issue certificates, but it needs a CA certificate to be created with a pass phrase. This pass phrase can be saved in a configuration file, mysecret.yaml, with the parameter, SSL_PASSWORD.
1.9 Renewing the CertificatesThe certificates in PEM format are used to create the KeyStores and TrustStores during the deployment. When the certificates expire, they have to be updated in the KeyStores and TrustStores. Please follow the instructions in the blog post, Replacing Default SSL Certificates with CA signed Custom Certificates.
Author
Sajjad M. Kabir
Solutions Architect
IBM Lab Services