Configure your z/OS system to use TLS

Use this topic as example of how to configure IBM MQ for z/OS with Transport Layer Security (TLS) using RACF commands.

To use TLS for channel security, there are a number of tasks we need to perform on the system. (For details on using RACF commands for certificates and key repositories (key rings), see Work with TLS on z/OS .)

Create a key ring in RACF to hold all the keys and certificates for the system, using the RACF RACDCERT command. For example:
```
RACDCERT ID(CHINUSER) ADDRING(QM1RING)
```
The ID must be either the channel initiator address space user ID or the user ID we want to own the key ring if it is to be a shared key ring.
Create a digital certificate for each queue manager, using the RACF RACDCERT command.
The label of the certificate must be either the value of the IBM MQ CERTLABL attribute, if it is set, or the default ibmWebSphereMQ with the name of the queue manager or queue sharing group appended. See Digital certificate labels for details. In this example it is ibmWebSphereMQQM1.

For example:
```
RACDCERT ID(USERID) GENCERT
SUBJECTSDN(CN('username') O('IBM') OU('departmentname') C('England'))
WITHLABEL('ibmWebSphereMQQM1')
```
Connect the certificate in RACF to the key ring, using the RACF RACDCERT command. For example:
```
RACDCERT CONNECT(ID(USERID) LABEL('ibmWebSphereMQQM1') RING(QM1RING))
CONNECT ID(CHINUSER)
```
You also need to connect any relevant signer certificates (from a certificate authority) to the key ring. That is, all certificate authorities for the TLS certificate of this queue manager and all certificate authorities for all TLS certificates that this queue manager communicates with. For example:
```
RACDCERT ID(CHINUSER)
CONNECT(CERTAUTH LABEL('My CA') RING(QM1RING) USAGE(CERTAUTH))
```
On each of our queue managers, use the IBM MQ ALTER QMGR command to specify the key repository that the queue manager needs to point to. For example, if the key ring is owned by the channel initiator address space:
```
ALTER QMGR SSLKEYR(QM1RING)
```
or if we are using a shared key ring:
```
ALTER QMGR SSLKEYR(userid/QM1RING)
```
where userid is the user ID that owns the shared key ring.
Certificate Revocation Lists (CRLs) allow the certificate authorities to revoke certificates that can no longer be trusted. CRLs are stored in LDAP servers. To access this list on the LDAP server, you first need to create an AUTHINFO object of AUTHTYPE CRLLDAP, using the IBM MQ DEFINE AUTHINFO command. For example:
```
DEFINE AUTHINFO(LDAP1)
AUTHTYPE(CRLLDAP)
CONNAME(ldap.server(389))
LDAPUSER('')
LDAPPWD('')
```
In this example, the certificate revocation list is stored in a public area of the LDAP server, so the LDAPUSER and LDAPPWD fields are not necessary.

Next, put your AUTHINFO object into a namelist, using the IBM MQ DEFINE NAMELIST command. For example:
```
DEFINE NAMELIST(LDAPNL) NAMES(LDAP1)
```
Finally, associate the namelist with each queue manager, using the IBM MQ ALTER QMGR command. For example:
```
ALTER QMGR SSLCRLNL(LDAPNL)
```
Set up your queue manager to run TLS calls, using the IBM MQ ALTER QMGR command. This defines server subtasks that handle SSL calls only, which leaves the normal dispatchers to continue processing as normal without being affected by any SSL calls. We must have at least two of these subtasks. For example:
```
ALTER QMGR SSLTASKS(8)
```
This change only takes effect when the channel initiator is restarted.
Specify the cipher specification to be used for each channel, using the IBM MQ DEFINE CHANNEL or ALTER CHANNEL command. For example:
```
ALTER CHANNEL(LDAPCHL)
CHLTYPE(SDR)
SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA256)
```
Both ends of the channel must specify the same cipher specification.

Parent topic: Security installation tasks for z/OS