Customizing the SSL connection with the Z controller when using your certificates (SAF)

The management of security certificates is different between product versions. Depending on the z-centric agent version you are using, customize the SSL connection between the agent and Z controller by either using your SAF certificates or the default certificates.

Depending on the agent version that you are using:

For an agent version 10.2.1, or later: Customize the Z controller by using the SAF (System authorization facility) interface, the agent certificates and the configuration file. For more information, see Customizing the SSL connection between the agents and Z controller when using your certificates.
For an agent version 10.2.0, or earlier: You can either use default certificates or create your own. For more information, see Setting SSL-secure connections for communication using the default certificates.

Customizing the SSL connection between the agents and Z controller when using your certificates

To communicate, the IBM Z Workload Scheduler Agents (z-centric agents) and the Z controller use the HTTPS protocol. The communication process uses the certificates obtained by customizing the Z controller using the SAF (System authorization facility) interface. In addition to customizing those certificates, you need to customize the agent certificates and the configuration file. To enable SSL communication, perform the following steps.

Generate the distributed certificates for the agent as follows:
If the certification authority (CA) does not exist
Run the following commands:
- openssl genrsa -out ca.key 4096
- openssl req -x509 -new -nodes –key ca.key -subj "/CN=<common_name>" -days 3650 -out ca.crt
- openssl genrsa -des3 -out tls.key 4096
- openssl req -new -key tls.key -out tls.csr
- openssl x509 -req -in tls.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out tls.crt -extfile /etc/pki/tls/openssl.cnf -extensions v3_req
If the certification authority (CA) already exists
1. Run the following command to generate the private key and unsigned certificate:
  
  openssl genrsa -des3 -out tls.key 4096
  
  openssl req -new –key tls.key -out tls.csr
2. Send the tls.csr file to your certificate administrator to have it signed with your CA and be resent to you.
The ca.crt, tls.crt, and tls.key files are now ready for use.
Store ca.crt, tls.crt, and tls.key on the agent in a folder of your choice. When running the twsinst script to install the agent, specify that folder with the sslkeysfolder parameter.
Generate a z/OS certificate as follows:
1. Create a z/OS certificate and save it with the .crt extension.
2. Export the certificate in ASCII mode to the distributed environment.
3. On the workstation where you plan to install the agent, create a folder named additionalCAs nested in the folder where you previously stored the distributed certificates created in step 2.
4. Store the certificate in the additionalCAs folder. The additionalCAs folder must also contain the public key certificate or public certificate chain of the Z controller SSL key ring.
Import the distributed certificates (ca.crt and tls.crt) in the z/OS environment in ASCII mode.
Install the agent by running the twsinst script and specifying the sslkeysfolder and sslpassword parameters. Consider the following example:
```
./twsinst  -new -uname <agent_name> -acceptlicense yes 
-addjruntime true -inst_dir <inst_dir> -jmport xxxxx -jmportssl true -sslkeysfolder <path_to_distr_cert> 
-sslpassword <keystore_password>
```
where:
new

A fresh installation of the agent.

uname

Name of the user for which the agent is being installed.

acceptlicense

Whether to accept the License Agreement.

addjruntime

Adds the Java™ run time to run job types with advanced options, both those types that are supplied with the product and the additional types that are implemented through the custom plug-ins.

inst_dir

Folder of the agent installation.

jmport

JobManager port number used by the Z controller to connect to the agent.

jmportssl

JobManager port used by the Z controller to connect to the agent. Supported values are true and false.

sslkeysfolder
Name and path of the folder on the agent containing certificates. The folder must contain the following items:
- ca.crt
- tls.crt
- tls.key
- additionalCAs folder
sslpassword

Password to access the certificates.

The agent is now completely configured.

Setting SSL-secure connections for communication using the default certificates

To provide SSL security for an HTTP connection between the Z controller and HCL Workload Automation Agent, set the HTTPS keyword in the ROUTOPTS statement.

At installation time, the default security certificates are automatically stored in the SEQQDATA library:

EQQCERCL: The security certificate for the client.
EQQCERSR: The security certificate for the server.

You can decide to use these default certificates or create your own. However, in a production environment, it is recommended that you customize SSL communication with your own certificates.

In both cases, you need to import them into your security system. If you are using RACF, you are provided with the EQQRCERT sample job that you can run to import the certificates. To run this job, ensure that you use the same user ID that RACF associates with the controller started task.

The EQQRCERT job:

Copies the EQQCERCL certificate to a temporary sequential data set
Copies the EQQCERSR certificate to a temporary sequential data set
Imports EQQCERCL to RACF
Imports EQQCERSR to RACF
Deletes the temporary sequential data sets
Creates the SAF key ring that is used to connect the imported certificates
Updates the RACF database with the new certificates and key ring