You are planning to implement SSL or TLS to secure communications for your WebSphere MQ environment, however, you are unsure what label you will need to assign to your certificate during generation of the CSR or self-signed certificate. The answer to that question depends on who this certificate will represent as well as other factors, such as the platform you are running your queue manager on, and the type of WebSphere MQ messaging client being used.
For example, if the certificate you are creating will be used to represent your queue manager's identify that runs on a Unix platform, the label requirements are different than those for a certificate that will be used to represent a queue manager's identify that runs on a z/OS platform.
Here are some things you need to know before you decide what label you will assign to your certificate, followed by the specific requirements for different platforms and WebSphere MQ messaging clients.
What is the certificate label?
A certificate label is a unique identifier representing a digital certificate stored in a key repository, and provides a convenient human-readable name with which to refer to a particular certificate when performing key management functions. You assign the certificate label when adding a certificate to a key repository for the first time.
The certificate label is separate from the certificate's Subject Distinguished Name or Subject Common Name fields. Note that the Subject Distinguished Name and Subject Common Name are fields within the certificate itself. These are defined when the certificate is created and cannot be changed. However, you can change the label associated with a digital certificate if necessary.
How is the certificate label used?
WebSphere® MQ uses certificate labels to locate a personal certificate that is sent during the SSL handshake. This eliminates ambiguity when more than one personal certificate exists in the key repository.
Certificate labels follow a naming convention; you need to ensure that you use the correct label naming convention corresponding to the platform that you are using.
In this context, an SSL or TLS client refers to the connection partner initiating the handshake, which might be a WebSphere MQ client or another queue manager.
During the SSL or TLS handshake, the SSL or TLS client always obtains and validates a digital certificate from the server. With the WebSphere MQ implementation, the SSL or TLS server always requests a certificate from the client and the client always provide a certificate to the server if a one is found. If the client is unable to locate a personal certificate, the client sends a "no certificate" response to the server.
The SSL or TLS server always validates the client certificate if one is sent. If the client does not send a certificate, authentication fails if the end of the channel that is acting as the SSL or TLS server is defined with either the SSLCAUTH parameter set to REQUIRED or an SSLPEER parameter value set.
For more information about connecting a queue manager using one-way authentication, that is, when the SSL or TLS client does not send a certificate, review the topic "Connecting two queue managers using one-way authentication" located in the WebSphere MQ version 7.1 infocenter.
WebSphere MQ Java or WebSphere MQ JMS clients use the facilities of their Java Secure Socket Extension (JSSE) provider to select a personal certificate during the SSL or TLS handshake and therefore are not subject to certificate label requirements.
The default behavior, is that the JSSE client iterates through the certificates in the key repository, selecting the first acceptable personal certificate found. However, this behavior is only a default, and is dependent on the implementation of the JSSE provider.
In addition, the JSSE interface is highly customizable through configuration and direct access at runtime by the application. Consult the documentation supplied by your JSSE provider for specific details.
For troubleshooting, or to better understand the handshake performed by the WebSphere MQ Java client application in combination with your specific JSSE provider, you can enable debugging by setting
in the JVM environment.
You can use -Djavax.net.debug=ssl on the command line, or set the variable within the application, or through configuration.