Solutions

Installing a Secure Version of the ChangeMan ZMF REST API-Jenkins Integration



ID:    S143367
Published:    09 February 2021

Operating System(s)

  • Z/OS

Product(s)

  • ChangeMan ZMF
 

Description

As documented in the ChangeMan ZMF REST Services Getting Started Guide, all secure communication functionality (i.e. SSL) associated with this processing on z/OS must be implemented using IBM's Application Transparent Transport Layer Security (AT-TLS). Some customers may have found and implemented other solutions that address their specific needs (e.g. the implementation of native Apache Tomcat SSL connectors). However, if problems are encountered in such environments AT-TLS will need to be implemented to resolve the issue.

This document explains the steps required and provides an example on how a secure, end-to-end ZMF REST API environment can be configured. That is, from the ZMF REST API Testing Tool running on a user's Windows client machine, to the ZMF Tomcat environment running on z/OS, to a Jenkins environment running on a Windows Server machine, and back again.

Resolution

In the following example:

- The ChangeMan ZMF Server and Tomcat started tasks are running on LPAR s001.microfocus.com.

- The Tomcat task is running with the httpPorts variable in member SERVVARS set to 9992.

- Jenkins is running on jenkins-server.microfocus.com secure port 9070.

- Both the ZMF Server and Tomcat started tasks are running under userid ZMFS.

- The Tomcat started task is running under jobname SERSTCSZ.

1. Leave Connector Definitions as Supplied

As distributed, the ZMF CNTL SERVXML member will state the following:

...                                                                

    <Connector port="&httpPort;" protocol="HTTP/1.1"            

               connectionTimeout="20000" />                      

                                                                

    <Connector port="&httpPorts;" protocol="HTTP/1.1"           

               connectionTimeout="20000" />                     

...                                                              

There is no need to change this to implement a secure connection when using IBM AT-TLS functionality. AT-TLS itself will provide the secure socket functionality.

2. Define Incoming TLS Policy (pagent) Rule for ZMF REST API HTTPS Connector Port

A TCP/IP TLS rule is required to secure communication from all clients connecting to the Tomcat started task. A sample rule follows:

...

TTLSRule                          ChangeMan_Client~4

{

  LocalAddr                       ALL

  RemoteAddr                      ALL

  LocalPortRangeRef               9992

  RemotePortRangeRef              portR2

  Direction                       Inbound

  Priority                        255

  TTLSGroupActionRef              gAct1

  TTLSEnvironmentActionRef        eAct2~ChangeMan

  TTLSConnectionActionRef         cAct2~ChangeMan

}

...

PortRange                         portR2

{

  Port                            1024-65535

}

...

TTLSGroupAction                   gAct1

{

  TTLSEnabled                     On

  Trace                           1

}

...

TTLSEnvironmentAction             eAct2~ChangeMan

{

  HandshakeRole                   Server

  EnvironmentUserInstance         0

  TTLSKeyringParmsRef             keyR2

  TTLSEnvironmentAdvancedParmsRef eAdv2

}

...

TTLSKeyringParms                  keyR2

{

  Keyring                         tlsKeyring

}

...

TTLSEnvironmentAdvancedParms      eAdv2

{

  ClientAuthType                  Full

  TLSv1.2                         On

}

...

TTLSConnectionAction              cAct2~ChangeMan

{

  HandshakeRole                   ServerWithClientAuth

  TTLSCipherParmsRef              cipher2~ALL

  TTLSConnectionAdvancedParmsRef  cAdv1~ChangeMan

  CtraceClearText                 On

  Trace                           3

}

...

TTLSCipherParms                   cipher2~ALL

{

...

  V3CipherSuites                  TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

  V3CipherSuites                  TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

  V3CipherSuites                  TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

  V3CipherSuites                  TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

  V3CipherSuites                  TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

  V3CipherSuites                  TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

  V3CipherSuites                  TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

  V3CipherSuites                  TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

  V3CipherSuites                  TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

  V3CipherSuites                  TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

  V3CipherSuites                  TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

...

}

...

TTLSConnectionAdvancedParms       cAdv1~ChangeMan

{

  ApplicationControlled           Off

  SecondaryMap                    Off

}

3. Define Outgoing TLS Rule for Jenkins Secure Port

Similarly, a TLS rule will also be required for outgoing communication from the Tomcat task to the Jenkins Server.

NOTE: Some of the entries referenced below have already been defined above for the incoming policy and have been omitted to avoid duplication.

...

TTLSRule                          RULE_SERSTCSZ

{

  LocalAddr                       ALL

  RemoteAddr                      ALL

  Jobname                         SERSTCSZ

  LocalPortRangeRef               portR2

  RemotePortRange                 9070

  Direction                       Both

  Priority                        254

  TTLSGroupActionRef              gAct1

  TTLSEnvironmentActionRef        EA_SERDTCS

}

...

PortRange                         portR2

{

  Port                            1024-65535

}

...

TTLSEnvironmentAction             EA_SERDTCS

{

  HandshakeRole                   Client

  TTLSCipherParmsRef              cipher2~ALL

  TTLSEnvironmentAdvancedParmsRef EAP_SERDTCS

  TTLSKeyringParmsRef             keyR2

  CtraceClearText                 On

  Trace                           3

}

...

TTLSEnvironmentAdvancedParms      EAP_SERDTCS

{

  SecondaryMap                    Off

  TLSv1.2                         On

  SSLv2                           Off

  SSLv3                           Off

  TLSv1                           Off

  TLSv1.1                         Off

}

...

4. Generate Certificate for Mainframe Connector

a) Many customers will already have their own Certificate Authority (CA) defined and be able to use the existing certificate associated with it. Just for information, a CA certificate can be generated using the following type of command if one does not already exist:

RACDCERT CERTAUTH -                         

         GENCERT -                          

         SUBJECTSDN(OU('COMPANY NAME CA') -

         O('Micro Focus') -                         

         L('SVL') -                         

         SP('CA') -                         

         C('US')) -                         

         NOTAFTER(DATE(2040-12-31)) -       

         WITHLABEL('COMPANY NAME CA') -

         ALTNAME(IP(152.156.152.189)) -     

         KEYUSAGE(CERTSIGN)                 

SETROPTS RACLIST(DIGTCERT,DIGTRING) REFRESH 

b) Similarly many customers will already have a certificate that trusts their mainframe machine. If they do, this can be used to secure ZMF REST API services, too. If not, one can be generated using the following type of command:

RACDCERT GENCERT SITE +

         SUBJECTSDN(CN('s001.microfocus.com') -

         OU('Micro Focus') O('Micro Focus') -

         L('Virtual') SP('CA') C('US')) -

         SIZE(2048) -

         SIGNWITH(CERTAUTH LABEL('COMPANY NAME CA')) -

         NOTAFTER(DATE(2040-12-31) TIME(00:00:00)) -

         WITHLABEL('s001.microfocus.com') -

         ALTNAME(DOMAIN('s001.microfocus.com')) -

         KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN)

SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

5. Upload Certificates for Jenkins Server to Mainframe

The certificates that have been generated for the secure Jenkins Server environment need to be uploaded to the mainframe. Generation and implementation of a secure Jenkins environment falls outside the scope of this document. Questions on that side of the integration must be addressed to the team that supports the Jenkins installation within your company.

6. Attach Certificates to RACF Key rings

A key ring must be defined for the ZMF Server/Tomcat started task userid and the appropriate certificates connected to it.

A new key ring can be defined as follows:

RACDCERT ADDRING(tlsKeyring) ID(ZMFS)

Then connect the mainframe and Jenkins certificates, along with the associated CA certificate(s), to the key ring using the following type of command for the site certificates:

RACDCERT ID(ZMFS) CONNECT(SITE USAGE(PERSONAL) -           

         LABEL('jenkins-server.microfocus.com') RING(tlsKeyring))

And this type of command for the CA(s):

RACDCERT ID(ZMFS) CONNECT(CERTAUTH LABEL('COMPANY NAME CA') –

         RING('tlsKeyring') USAGE(CERTAUTH))

The certificates attached to the key ring can be listed using the following command:

RACDCERT ID(ZMFS) LISTRING(tlsKeyring)

6. Export Certificates for Use on Client Machines

The certificate(s) required for mainframe connections need to be extracted from RACF so that they can be installed on client machines. To extract the required certificate in this sample, the following type of RACF export command can be used:

RACDCERT EXPORT(LABEL('SERENA CA KEY Cert')) + 

         CERTAUTH +                           

         DSN('USER01.CERT.CA.KEY.CER') +      

         FORMAT(CERTDER)                      

It will usually only be necessary to install the CA certificate. However, you should use your own internal standards and processes to decide exactly what is required in your environment.

7.Download Certificates for Use on Client Machines

Once extracted, the mainframe connection certificate resident in 'USER01.CERT.CA.KEY.CER' needs to be downloaded for distribution to and installation on the required client machines. This can be achieved using appropriate FTP client software or native FTP commands. The dataset should be downloaded as a binary file.

8. Import Certificates on Client Machines

Once downloaded, the mainframe connection certificate must be installed to the trust stores on the client machines. This can be achieved in any of the usual manners, e.g. by using Windows Control Panel – Manage Certificates functionality, Chrome (Settings – Privacy and security – Security – Manage certificates), etc. Ensure that the certificate is added to the Trusted Root Certification Authorities on all client machines.

9. Ensure Subscriptions are Defined with HTTP

In this configuration all event or webhook subscriptions MUST be defined with the HTTP protocol, not HTTPS. This is regardless of whether the external URL requires use of https. For example:


Changes will be made in the 8.2 Patch 5 release which will automatically convert http to https if the subscription is defined as an AT-TLS connection.

10. Verify Installation

After taking all of the steps documented above, ensure that you can access the REST API services in a secure manner. For example, as we have configured a secure set of 8.2 Patch 4 REST services to run on s001.microfocus.com port 9992, using the Chrome browser, navigate to the following address:

https://s001.microfocus.com:9992/zmfrest/home

Ensure that no warning or error messages are issued. Also check that the secure connection 'padlock' symbol is displayed:


From here, logon to the ZMF Server, use either an existing subscription or create a new subscription, and then execute a test in the ZMF Rest/Event Services test tool. Verify that you receive an Event Response Code 201 that indicates successful communication between all components in this processing.

10. Troubleshooting

If problems occur whilst configuring such a secure environment, the initial point of contact should be your internal, Network Systems Programming team. This will be the team that will ultimately need to resolve the issue.

When diagnosing problems we recommend that customers:

a) check the ZMF Server and Tomcat started task output for error messages related to this processing.

b) also check the SYSLOG and/or TCP/IP started task output for any error messages that are issued when the failing transactions are executed.

c) if the response or error codes/messages suggest a problem connecting to any of the entities in the communication chain, you may also want to increase the trace levels on the pagent entities described above. This will increase the number of EZD1286I and EZD1287I diagnostic messages that are issued by TCP/IP and should help to diagnose the problem in your environment.

Applies To

ChangeMan ZMF 8.2 Patch 3+

Rate this Solution

Find Answers

Type a question or describe what you are looking for below

My Recent Searches

Welcome kb sso

Additional Assistance

  • Submit a Case Online
  • FAQs