Managing Secure Sockets Layer certificates with WebSphere MQ on z/OS

For SSL certificates there are four areas that you need to plan for:

1. Setting up your internal certificates - for internal communications
2. Obtaining certificates from the external systems you want to connect
3. Configuring the queue manager
4. Ongoing review and maintenance

Each of these requires planning to manage these successfully.

Overview of SSL certificates.
A certificate is issued to a user by a Certification Authority (CA). If you are only dealing with connections within your organization, you can create your own Certification Authorities (Example: one for production and one for test). If you need to use SSL for connections outside of your organization, then both parties require a certificate from the same trusted external Certification Authority. You can use non-trusted CAs for external communications, but you probably would not want to do that.

The certificates an application can use are defined as part of a Key Ring (If you think of a certificate as the key to access a resource, then keys are stored on a key ring). A queue manager can share a key ring, or have its own key ring. Authorized users can create and manipulate certificates and rings for other users.

If you are using your own CA, you can create individual certificates for your queue managers and clients, and sign them using the CA. If you are using an external CA, you cannot create certificates yourself; instead you create a certificate request, which you send to the external CA, who then returns the actual certificates. Using an external CA is more secure, but is also a more complicated and drawn out process than using your own CA to sign certificates. You can combine these two approaches, to take advantage of the security of external CAs with the ease of using your own CAs, by using certificate chains. The chain, or path, begins with the certificate of the queue manger or client, and each certificate in the chain is signed by the entity identified by the next certificate in the chain. The chain terminates with a root CA certificate. The signatures of all certificates in the chain must be verified until the root CA certificate is reached. See figure below (based on one in the Security manual).




Using this approach you can create and sign your own certificates and take advantage of the fact that those certificates are indirectly signed by the external CA.

To allow your queue managers to connect to queue managers outside of your organization, you need to ensure that the remote key ring holds the public certificate of the CA that signed your certificate; and vice versa. The CA certificates can be used to authenticate any certificates which have been signed by them.

In the discussions below, the term SSL client refers to the application trying to connect to the SSL Server. In MQ terms the SSL client could be an MQ client, a Sender or Requestor channel, and the SSL Server would be a Server Receiver or Responder channel.


Within an organization you can create your own certificates and sign them with your own CA. If you want to use an external Certification Authority, you will have to create a certificate request and send it to the CA with payment. The CA will then provide you with the certificate. This process may take a few days (or weeks), as the CA may need to check your identity and perform other background checks. You should allow for this possible extended time when setting up or renewing certificates from an external Certification Authority.

Being your own CA, or using an external CA is a trade-off of many variables. If you have an administration team willing to handle the tasks involved with certificate management, then it is much quicker to revoke, renew and create your own certificates. However, they can only be used for internal communications. Using an external CA for your internal communications relieves some of the administration burden! There is still much administration to be done even with an external CA. You will need to ensure that certificate requests are generated and submitted to the external CA at least a week before the expiry date of existing certificates; then you will need to wait for the external CA to respond with the new certificates; then you will need to import them into RACF. If a certificate expires when you were not expecting it, you may have to wait perhaps 24-48 hours for the external CA to respond, so that you can restart your channels.

The userid owning the key ring should be the userid of the CHINIT, unless you override this, by specifying userid/ring on the qmgr parameter SSLKEYR.

More than one queue manager can share a key ring. You can provide a default certificate to use if there is no queue manager specific certificate. This can be specified at the time the certificate is connected to the key ring. If you do not provide a default, then the certificate needs to be provided with a queue manager specific label of the form ibmWebSphereMQ, appended with the z/OS queue manager name. We recommend that you always use a specifically labelled certificate, and not to use the default.

Changing channels to use SSL.

For channels to use SSL you need the following:

1. A key ring for the CHINIT
2. The key ring needs to have
   • A certificate for the queue manager (or a default certificate)
   • Certificates from external Certification Authorities
3. Queue manager attributes set
4. Channel attributes set.

Use the REFRESH SECURITY TYPE(SSL) command.


Setting up SSL for two queue managers on the same image
You usually need to be authorized to use the commands to issue certificates. If you are using RACF then you need to be authorized to use the RACDCERT command.

SupportPac MO04 (WITHDRAWN) can help you generate the RACDCERT request and the queue manager changes that you may need.

Example job to define your internal Certificate Authority certificate
//PAICERA JOB 24800,'PAICE',MSGCLASS=H,REGION=32M,MSGLEVEL=(0,0)
//DOIT EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT CERTAUTH -
GENCERT -
SUBJECTSDN( -
CN('Hursley CA)-
T('Hursleys example system') -
OU('Development', 'Labs')-
O ('IBM') -
L ('Hursley') -
SP ('Hampshire') -
C ('UK') ) -
WITHLABEL('Hursley PLEX3 CA') -
NOTBEFORE ( DATE (2017-05-03) TIME (23:59:59)) -
NOTAFTER ( DATE(2019-05-03) TIME (23:59:59)) -
KEYUSAGE ( CERTSIGN )
/*
//

This defines a certificate called Hursley PLEX3 CA which can be used to sign other certificates

Example statements to define a certificate for the queue manager
RACDCERT ID(MQTASK)-
GENCERT -
SUBJECTSDN( -
CN('VCP1')-
T('WMQ Queue Manager') OU('WINMVS25')-
O('IBM') -
L('Hursley') -
SP('Hampshire') -
C('UK') ) -
WITHLABEL('ibmWebSphereMQVCP1') -
SIGNWITH(CERTAUTH LABEL('Hursley PLEX3 CA') ) -
NOTBEFORE ( DATE (2016-12-31) TIME (23:59:59)) -
NOTAFTER ( DATE(2019-09-23) TIME (14:00:00)) -
KEYUSAGE(HANDSHAKE)

This defines a certificate with label ibmWebSphereMQVCP1 for Queue manager VCP1.

1. The ID(MQTASK) defines the certificate for the CHINIT with userid MQTASK
2. CN is the Common Name for the queue manager
3. T is used as the description
4. OU is the MVS image name
5. The value in the WITHLABEL has the string with the queue manager name at the end. Note that the spelling and case of the string has to match the above.
6. The NOTAFTER defines the date and time when the certificate is no longer valid.
7. The Keyusage (handshake) indicates that digital Signature and key Encipherment are used.
8. The SIGNWITH specifies the local CA certificate defined above.

A certificate called Hursley Remote CA Cert was created on a remote system and used to sign certificates for the queue managers at the remote site. This certificate needs to be added to the key ring.

The following statements defines a key ring, and adds the above certificates to it
RACDCERT ID(MQTASK) ADDRING(VCP1)
RACDCERT CERTAUTH ADD('data-set-containing-remote-ca-cert') WITHLABEL('Hursley Remote CA Cert')
RACDCERT ID(MQTASK) CONNECT(CERTAUTH -
LABEL('Hursley Remote CA Cert') -
RING(VCP1) -
USAGE(CERTAUTH) -
)
RACDCERT ID(MQTASK) CONNECT(CERTAUTH -
LABEL('Hursley PLEX3 CA') -
RING(VCP1) -
USAGE(CERTAUTH) -
)

RACDCERT ID(MQTASK) CONNECT( -
ID(MQTASK) -
LABEL('ibmWebSphereMQVCP1') -
RING(VCP1) -
USAGE(PERSONAL) -
)

These commands create a ring for user MQTASK, add a certificate for the remote CA, and add the certificate defined above. If a certificate had been created for a different userid, then the ID(...) within the CONNECT above would be replaced with the different id.

When a channel starts, the sending queue manager checks that the responding queue manager (that is the receiver or requestor channel) has a valid certificate. If the initiating system provides a certificate, it will be authenticated by the responding queue manager, and rejected if the certificate is invalid. If the receiving channel has SSLCAUTH(REQUIRED) specified, then the initiating channel is also required to provide a certificate. The key ring used by the receiver will also need to have the CA certificate used to sign the sender queue manager.

Change the queue manager to use SSL
You need tell the queue manager which key ring should be used, and to specify the number of tasks to handle SSL work.
ALTER QMGR SSLKEYR(VCP1) SSLTASKS(5)
You then need to shut down and restart the CHINIT.

Define channels to use SSL
Define a receiver channel, for example:
DEFINE CHL(VCP1SSL) CHLTYPE(RCVR)TRPTYPE(TCP) SSLCIPH(DES_SHA_EXPORT)

Define a sender channel (and its transmission queue)
DEFINE CHL(VCP2SSL) CHLTYPE(Sdr)TRPTYPE(TCP) CONNAME('9.xx.yy.zz(2182)') -
XMITQ(VCP2SSL) SSLCIPH(DES_SHA_EXPORT);

DEFINE QL(VCP2SSL) USAGE(XMITQ)


Starting the channel
When the channel starts successfully, you will see the following message:
+CSQX500I @VCP1 CSQXRCTL Channel VCP2SSL started

When the certificate has expired, if you attempt to start the channel, you will receive the following message:
+CSQX658E @VCP1 CSQXRCTL SSL certificate has expired channel VCP2SSL, connection (9.xx.yy.zz)

What to do when you have received new or updated certificates.
If you have received new certificates from your CA, install them into your External Security Manager (ESM), and update the key ring.

Issue the REFRESH SECURITY TYPE(SSL) command.
This will cause existing SSL channels to be stopped and those initiated by the queue manager to be restarted, using the latest information.
Responding type channels should be restarted to this queue manager on the next retry from the partner system.



Maintaining the security of your data.
During an SSL handshake a secret key is generated to encrypt data between the SSL client and SSL server . The secret key is used in a mathematical formula that is applied to the data to transform plaintext into unreadable ciphertext. The ciphertext is then sent across the wire where the receiving queue manager will convert the ciphertext back into plaintext.

If the secret key is discovered, the plaintext of a message could be deciphered from the ciphertext, or the message digest could be calculated, allowing messages to be altered without detection. Even for a complex algorithm, with enough data the plaintext may eventually be discovered by applying every possible mathematical transformation to the ciphertext. To minimize the amount of data that can be deciphered or altered if the secret key is broken, the secret key can be renegotiated periodically.

The SSLRKEYC queue manager option is the number of bytes that will be sent and received on the channel before the secret key is renegotiated. This renegotiation occurs during normal data flows. This only applies to channels that the queue manager has initiated, and the remote end supports the function. Renegotiation of the key requires a processing overhead (similar to starting a channel), so this value should not be set too low. Data transferred during heart beats count towards the number of bytes before renegotiating. You should use heart beats on a channel.

For other channels, if you stop and restart the channel, then this will cause the secret key to be renegotiated. You should consider how long you want your client applications to remain connected before they need to stop and restart the connection. Using a disconnect interval in which the channel disconnects after a period of no message flow, will cause a renegotiation when the channel starts up again. If the channel does not have a disconnect interval, then you may want to use automation to stop and restart the channels during a quiet period.



What you need to manage

Expiry of private certificates for individual users
You need to review which of your certificates are due to expire.
Using RACF you can use the RACDCERT LIST command to list the certificates in a ring. For example:

• Label: ibmWebSphereMQVCP1
  Certificate ID: 2QbXwcnDxfGJgpTmhYLil4iFmYXU2OXD1/FA
  Status: TRUST
  Start Date: 2017/12/31 23:59:59
  End Date: 2017/09/23 14:00:00

If you do not have many certificates, then you can use the RACDCERT command in batch; edit the output file, exclude all of the lines, then search for 'Label:', search for 'End Date', then delete all the lines still excluded (DEL ALL X). This will result in a list of certificates and expiry dates. Make a note of the certificates due to expire in the next month.

You need to plan this well in advance, it as may take several weeks to get a replacement certificate if you use an external CA, or a few days if you use an internal CA.


Expiry of a Certificate Authority certificate
You will need to recertify the certificate. This is described in the z/OS Security Server RACF Security Administrator's Guide(SA22-7683) topic Renewing an expiring certificate.
/* Generate a PKCS10 request into a dataset against the expiring CA */
RACDCERT CERTAUTH GENREQ(LABEL("Hursley PLEX3 CA")) DSN(MY.CA.REQ)

/* Renew the CA, good for another 5 years */
RACDCERT CERTAUTH GENCERT(MY.CA.REQ) NOTAFTER(9/28/2015) SIGNWITH(CERTAUTH LABEL("Hursley PLEX3 CA"))

After this you just need to distribute your new CA certificate to where the old CA certificates were located. Any private certificates previously issued will continue to be valid.


Expiry of a personal certificate for a userid
Create a renewal certificate request against your existing (expiring) certificate, and export it to a dataset.

Export the certificate to a dataset
RACDCERT ID(PAICE1) GENREQ(LABEL(’ibmWebSphereMQVCP’)) DSN(’PAICE.VCP1.CERTIFIC')

Import the certificate and override the NOTAFTER parameter:

RACDCERT ID(PAICE1)GENCERT('PAICE.VCP1.CERTIFIC') -

NOTAFTER (DATE(2019-11-24) TIME (11:50:00)) -
SIGNWITH(SITE LABEL('Hursley PLEX3 CA'))

Once you have issued this command, you should use the RACDCERT LIST ID(...) command to make sure the certificate is as you expect.

Repudiation of a certificate for a user (it has been cancelled)
If a user of a certificate leaves your organization, then you will need to invalidate the certificate. This is called repudiating a certificate. For external certificates, you need to set up a process for receiving notification of repudiated certificates. This involves setting up an LDAP server, which is not a trivial piece of work.

To receive notification from a Certification Authority that a Certificate is no longer valid, you must install and configure an LDAP server. Details on how to perform these tasks can be found in WebSphere MQ Security, Chapter 15, Accessing CRLs and ARLs.