(Docker) Security enablement example

Edit online

The following example shows how to enable secure communications between Z APM Connect DG machine and MVS host, using RACF as the Security Server.

Procedure

  1. Use the ./zapmctl configure security command to import certificates on the Z APM Connect Distributed Gateway machine. For more information, see 1. Importing certificates on the Z APM Connect Distributed Gateway machine.
  2. Transfer certificates from Z APM Connect DG machine to z/OS components machine, create a key ring and certificate on z/OS components, and export personal certificate of the z/OS components.
    1. Use the ASCII transfer mode to transfer the CA certificate used to sign the Z APM Connect DG certificates from your DG machine to your MVS system into a Variable-Blocked (VB) dataset.
      Important: You should be able to browse the certificate, and it should look the same as if you were to “cat” the CA certificate on the Z APM Connect DG machine.

      The zapm.crt file is a root CA certificate. It is recommended to use your company's approved certificate.

    2. Use the following command example to create a key ring and certificate on z/OS components, and export personal certificate of the z/OS components.
    For this example below, you need to change all of these values to match your environment:
    • The VB dataset is 'ROOT.SADG.CAROOT'.
    • The UserId under which the z/OS Connect EE server runs is IBMUSER.
    • The UserId under which the Z APM Connect Base address space (AGMAPROC by default) runs is USER1.

    Example

    RACDCERT CERTAUTH ADD('ROOT.SADG.CAROOT') HIGHTRUST WITHLABEL('IBM.SADG.LABEL')

SETROPTS RACLIST(DIGTCERT) REFRESH 

RACDCERT CERTAUTH GENCERT SUBJECTSDN(O('ZOS APM Inc.') OU('ZOS APM Certificate Authority SADG') C('US')) KEYUSAGE(CERTSIGN) WITHLABEL('ZOS_APM_Internal_CA_SADG')

SETROPTS RACLIST(DIGTCERT) REFRESH

RACDCERT ID(IBMUSER) GENCERT SUBJECTSDN(CN('ZOS.APM.TEST.SADG') O('ZOS APM Test SADG') OU('ZOS APM Test Client SADG') C('US')) WITHLABEL('Personal_Cert_SADG') SIGNWITH(CERTAUTH LABEL('ZOS_APM_Internal_CA_SADG')) 

SETROPTS RACLIST(DIGTCERT) REFRESH

RACDCERT ID(IBMUSER) ADDRING(SADG-RING)

RACDCERT ID(IBMUSER) CONNECT(CERTAUTH LABEL('ZOS_APM_Internal_CA_SADG') RING(SADG-RING) USAGE(CERTAUTH))

RACDCERT ID(IBMUSER) CONNECT(ID(IBMUSER) LABEL('Personal_Cert_SADG') RING(SADG-RING) DEFAULT USAGE(PERSONAL))

RACDCERT ID(IBMUSER) CONNECT(CERTAUTH LABEL('IBM.SADG.LABEL') RING(SADG-RING) USAGE(CERTAUTH))

SETROPTS RACLIST(DIGTRING) REFRESH
SETROPTS RACLIST(DIGTCERT) REFRESH

PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(IBMUSER) ACCESS(READ)
PERMIT IRR.DIGTCERT.GENCERT CLASS(FACILITY) ID(IBMUSER) ACCESS(CONTROL)

SETROPTS RACLIST(FACILITY) REFRESH

RACDCERT CERTAUTH EXPORT(LABEL('ZOS_APM_Internal_CA_SADG')) DSN('ROOT.SADG.CACERT.EXPORT')
    To give other users access to the key ring, (for instance, if the Z APM Connect Base address space is running under a userid other than IBMUSER, in this example USER1): 
    PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(USER1) ACCESS(UPDATE) 

RACDCERT ID(USER1) GENCERT SUBJECTSDN(CN('ZOS.APM.TEST.SADG') O('ZOS APM Test SADG') OU('ZOS APM Test Client SADG') C('US')) WITHLABEL('Personal_Cert_USER1_SADG') SIGNWITH(CERTAUTH LABEL('ZOS_APM_Internal_CA_SADG')) 

RACDCERT ID(IBMUSER) CONNECT(ID(USER1) LABEL('Personal_Cert_USER1_SADG') RING(SADG-RING) USAGE(PERSONAL))
  3. Update the policy agent (PAGENT) AT-TLS policy on the MVS system.
    In the following command example:
    • The z/OS Connect EE server proc is ZCEESRVR.
    • The Z APM Connect Base proc is AGMAPROC.
    • If you also have a CICS TG server, configure its connection to the Z APM Connect DG machine the same as you do for the z/OS Connect EE server.
    Note: The Z APM Connect Base address space connects to the 30455 port of the Z APM Connect DG machine, and the z/OS Connect EE and CICS TG servers (if applicable) connect to the 30090 port of the Z APM Connect DG machine.

    Example

    TTLSRule                      CLIP_Probe-Client-IBMUSER-SADG
{
    RemotePortRange          30090
    RemoteAddr               9.xx.xx.xx	# Addr of the DG
    Jobname                  ZCEESRVR   # Jobname of zOS Connect server
    Direction                Outbound
    TTLSGroupActionRef       grp_Production
    TTLSEnvironmentActionRef act_CLIP_Probe-IBMUSER-SADG
}

TTLSRule                     CLIP_Probe-Client-USER1-SADG
{
    RemotePortRange          30455
    RemoteAddr               9.xx.xx.xx	# Addr of the DG
    Jobname                  AGMAPROC   # Jobname of Base proc
    Direction                Outbound
    TTLSGroupActionRef       grp_Production
    TTLSEnvironmentActionRef act_CLIP_Probe-USER1-SADG
}

TTLSEnvironmentAction    	act_CLIP_Probe-IBMUSER-SADG
{
    HandshakeRole            Client
    Trace                    255
    EnvironmentUserInstance  3
    TTLSKeyRingParms
    {
        Keyring IBMUSER/SADG-RING
     }
    TTLSEnvironmentAdvancedParms
    {
        SecondaryMap  		On
        HandshakeTimeout  	60
        TLSV1.2 			On  
        SSLv3 			On
    }
}

TTLSEnvironmentAction        act_CLIP_Probe-USER1-SADG
{
    HandshakeRole 		Client
    Trace   			255
    EnvironmentUserInstance 	3
    TTLSKeyRingParms
    {
        Keyring IBMUSER/SADG-RING
     }
    TTLSEnvironmentAdvancedParms
    {
        SecondaryMap		On
        HandshakeTimeout  	60
        TLSV1.2 			On         
        CertificateLabel  	Personal_Cert_USER1_SADG
    }
}
  4. Transfer over FTP using the ASCII mode the exported certificate, ROOT.SADG.CACERT.EXPORT in this example, to the existing truststore on the Z APM Connect DG machine and place it in the same directory as the truststore file. The .cert file must be added to the truststore. In the following command example, host.cert is used as the exported certificate:
    Example
    keytool -import -keystore k8s.truststore.jks -deststoretype jks -alias customcert -file host.crt -storepass <pw> -keypass <pw> -noprompt
  5. 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.html.
  6. 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.