Configuring secure communications between z/OS components and Z APM Connect Distributed Gateway Linux machine

Edit online

If you install the Z APM Connect DG with Docker standalone, you can secure connection between the Z APM Connect Distributed Gateway (Z APM Connect DG) Machine on Linux® and the various components on z/OS® that communicate to it by using the Transport Layer Security (TLS, sometimes called SSL) protocol.

1. Creating a key ring and certificate on z/OS components

2. Transferring certificates from Z APM Connect Distributed Gateway machine to z/OS components machine

3. Updating the policy agent (PAGENT) AT-TLS policy

4. Updating the Linux truststore

5. Recycle the Z APM Connect DG

6. Refresh or recycle the PAGENT address space

1. Creating a key ring and certificate on z/OS components

Edit online

About this task

The z/OS components machine serves as the TLS client. For each started task that generates transactional tracking information, additional security setup is needed.

The started tasks include the Z APM Connect Base proc (AGMAPROC by default), and may include the z/OS Connect EE server or CICS® TG server, depending on the type of transactions to be tracked. The user ID under which each started task runs must have a key ring that contains its personal certificate and private key, its own trust chain, and, if the server certificate is signed by a different authority, the server's CA certificate.

Procedure

In the following command examples:

  • RACF® commands are used to create a key ring. For more information about RACF command, see RACF command syntax.
  • IBMUSER owns the proc.
  • Commands use a key ring owned by IBMUSER. For more information about creating a key ring, see RACDCERT ADDRING.
  • - is the continuation character.

  1. Create an internal certificate-authority (CA) certificate and refresh. 
    RACDCERT CERTAUTH GENCERT                              -
   SUBJECTSDN(O('<organization name>')                 -
              OU('<organizational unit name>')         -
               C('<country>'))                         -
               KEYUSAGE(CERTSIGN)                      -
               WITHLABEL('<Internal CA Name>'))

SETROPTS RACLIST(DIGTCERT) REFRESH
  2. Create a personal certificate for the proc owner. 
    RACDCERT ID(IBMUSER) GENCERT SUBJECTSDN(CN('<common name>')                                                   -
								      O('<organization name>')                -
									  OU('<organizational unit name>')    -
									  C('<country>'))                     -
					WITHLABEL('<IBMUSER Personal Certificate name>')                      -
					SIGNWITH(CERTAUTH LABEL('<Internal CA Name>'))
SETROPTS RACLIST(DIGTCERT) REFRESH
  3. Create a key ring and add the new certificates. 
    RACDCERT ID(IBMUSER) ADDRING(<keyring name>)
RACDCERT ID(IBMUSER) CONNECT(CERTAUTH                                   -
                           LABEL('<Internal CA Name>')                  -
                           RING(<keyring name>)                         -
                           USAGE(CERTAUTH))
RACDCERT ID(IBMUSER) CONNECT(ID(IBMUSER)                                -
                           LABEL('<IBMUSER Personal Certificate name>') -
                           RING(<keyring name>)                         -
                           DEFAULT                                      -
                           USAGE(PERSONAL))

2. Transferring certificates from Z APM Connect Distributed Gateway machine to z/OS components machine

Edit online

Procedure

  1. Use the ASCII transfer mode to FTP the zapm.crt certificate to the client.
    The zapm.crt file is a root CA certificate. It is recommended to use your company's approved certificate.
  2. Add the zapm.crt certificate to z/OS components machine and connect the zapm.crt certificate to a key ring.
    In the following command examples:
    • - is the continuation character.
    • dsn_name is the data set name that contains the root CA certificate.
    • WITHLABEL('<label>') is optional. The label should be unique, if used.
    • IBMUSER owns the proc. This following command example uses a <keyring name> owned by IBMUSER. For more information about creating a key ring, see RACDCERT ADDRING.
    

RACDCERT CERTAUTH ADD('<dsn_name>') HIGHTRUST WITHLABEL('<label>')

SETROPTS RACLIST(DIGTCERT) REFRESH

RACDCERT ID(IBMUSER) CONNECT(CERTAUTH  LABEL('<label>')        -
                           RING(<keyring name>)                -
                           USAGE(CERTAUTH))

3. Updating the policy agent (PAGENT) AT-TLS policy

Edit online

About this task

In the PAGENT AT-TLS policy, the TTLSEnvironmentAction needs to be updated to reference the key ring.

The TTLSRule needs to reference the IP Address of the Linux machine on which Z APM Connect is installed and the port to be used. The port for the CICS TG and z/OS Connect EE Server is 30090 and the port for the Z APM Connect Base is 30455.

The PAGENT proc needs to be restarted or refreshed to implement these changes.

Example

Policy agent configuration file:

TTLSRule                     <TTLS rule Name>
{
    RemotePortRange          <port>
    RemoteAddr               <ip addr>
    Direction                Outbound
    TTLSGroupActionRef       <Grp Action name>
    TTLSEnvironmentActionRef <Env Action name>
}
TTLSEnvironmentAction        <Env Action name>
{
    HandshakeRole            Client
    TTLSKeyRingParms
    {
        Keyring <user ID>/<keyring name>
     }
    ...

}

TTLSGroupAction               <Grp Action name>                            
{                                                                       
    ...                           
}

4. Updating the Linux truststore

Edit online

Procedure

Export the z/OS personal certificate for the key ring's owning user ID and add it to the Linux truststore.

  1. Export the personal certificate of the z/OS components. 
    RACDCERT CERTAUTH EXPORT(LABEL('<unique name>')) DSN('<dsn_export>')
  2. Add the exported certificate to the existing truststore on the Linux machine where Z APM Connect DG is installed. 
    keytool -import -keystore "<truststore>.jks" -deststoretype jks -alias CustomCert -file "<filename>" -storepass "<password>" -keypass "<password>" -noprompt

5. Recycle the Z APM Connect DG

Edit online

Procedure

Recycle the Z APM Connect DG, if needed, to pick up the truststore addition, by first running the sudo ./zapmctl stop command and then run the sudo ./zapmctl start command from the <install-dir>/ directory. For more information about how to use the commands, see ../configuration/ttg/zapm_dg_command_start.html.

6. Refresh or recycle the PAGENT address space

Edit online

Procedure

Refresh or recycle the PAGENT address space. Recycle Z APM Connect Base address space (AGMAPROC) and if applicable, the CICS TG and z/OS Connect EE servers to pick up the new policy.