The SSL/TLS key repository
A mutually authenticated TLS connection requires a key repository at each end of the connection. The key repository includes digital certificates and private keys.
This information uses the general term key repository to describe the store for digital certificates and their associated private keys. The key repository is referred to by different names on different platforms and environments that support TLS:- On IBM i: certificate store
- On Java and JMS: keystore and truststore
- On UNIX, Linux, and Windows: key database file
- On z/OS : keyring
For more information, see Digital certificates and Transport Layer Security (TLS) concepts. A mutually authenticated TLS connection requires a key repository at each end of the connection. The key repository can contain the following certificates and requests:
- A number of CA certificates from various Certification Authorities that allow the queue manager or client to verify certificates that it receives from its partner at the remote end of the connection. Individual certificates might be in a certificate chain.
- One or more personal certificates received from a Certification Authority. You associate a separate personal certificate with each queue manager or IBM MQ MQI client. Personal certificates are essential on a TLS client if mutual authentication is required. If mutual authentication is not required, personal certificates are not needed on the client. The key repository might also contain the private key corresponding to each personal certificate.
- Certificate requests which are waiting to be signed by a trusted CA certificate.
For more information about protecting your key repository, see Protecting IBM MQ key repositories.
The location of the key repository depends on the platform we are using:
- IBM i
- The key repository is a certificate store. The default system certificate store is located at /QIBM/UserData/ICSS/Cert/Server/Default in the integrated file system (IFS). IBM MQ stores the password for the certificate store in a password stash file. For example, the stash file for queue manager QM1 is /QIBM/UserData/mqm/qmgrs/QM1/ssl/Stash.sth.
Alternatively, we can specify that the IBM i system certificate store is to be used instead. To do this change the value of the queue manager SSLKEYR attribute to *SYSTEM. This value indicates that the queue manager must use the system certificate store, and the queue manager is registered for use as an application with Digital Certificate Manager (DCM).
The certificate store also contains the private key for the queue manager.
- UNIX, Linux, and Windows systems
- The key repository is a key database file. The name of the key database file must have a file extension of .kdb. For example, on UNIX and Linux, the default key database file for queue manager QM1 is /var/mqm/qmgrs/QM1/ssl/key.kdb. If IBM MQ is installed in the default location, the equivalent path on Windows is C:\ProgramData\IBM\MQ\Qmgrs\QM1\ssl\key.kdb.
Each key database file has an associated password stash file. This file holds encoded passwords that allow programs to access the key database. The password stash file must be in the same directory and have the same file stem as the key database, and must end with the suffix .sth, for example /var/mqm/qmgrs/QM1/ssl/key.sth
Note: PKCS #11 cryptographic hardware cards can contain the certificates and keys that are otherwise held in a key database file. When certificates and keys are held on PKCS #11 cards, IBM MQ still requires access to both a key database file and a password stash file.On UNIX and Windows systems, the key database also contains the private key for the personal certificate associated with the queue manager or IBM MQ MQI client.
- z/OS
- Certificates are held in a keyring in z/OS.
Other external security managers (ESMs) also use keyrings for storing certificates.
Private keys are managed by RACF .
- Protecting IBM MQ key repositories
The key repository for IBM MQ is a file. Ensure that only the intended user can access the key repository file. This prevents an intruder or other unauthorized user copying the key repository file to another system, and then setting up an identical user ID on that system to impersonate the intended user. - Digital certificate labels, understanding the requirements
When setting up TLS to use digital certificates, there might be specific label requirements that we must follow, depending on the platform used and the method we use to connect. - Refreshing the queue manager's key repository
When we change the contents of a key repository, the queue manager does not immediately pick up the new contents. For a queue manager to use the new key repository contents, we must issue the REFRESH SECURITY TYPE(SSL) command. - Refreshing a client's view of the SSL/TLS key repository contents and SSl/TLS settings
To update the client application with the refreshed contents of the key repository, we must stop and restart the client application.
Parent topic: TLS security protocols in IBM MQ