Solutions
| 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.
