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.
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.
IBM i, UNIX, Linux, and Windows systems
On IBM i, UNIX, Linux, and Windows systems, the SSL or TLS server sends a certificate to the client, only if the server finds one labeled in the correct WebSphere MQ format. On these systems, the correct format is ibmwebspheremq, followed by the name of your queue manager changed to lower case.
If no certificate is found in the queue manager's key repository, matching the required label in the correct case and format, an error occurs and the SSL or TLS handshake fails.
WebSphere MQ Clients are not supported on IBM z/OS systems. However, the z/OS queue manager can act in the role of the SSL or TLS client when initiating a connection, or the SSL or TLS server when accepting a connection request. Certificate label requirements for z/OS queue managers apply in both of these roles, and differ from the requirements on distributed platforms.
On z/OS systems, the correct format for labels is ibmWebSphereMQ in mixed case, followed by the name of the queue manager or queue sharing group in upper case as described below.
- For a shared channel only, a certificate with a label in the format ibmWebSphereMQ, followed by the name of your queue-sharing group, for example, ibmWebSphereMQQSG1
- A certificate with a label in the format ibmWebSphereMQ followed by the name of your queue manager, for example ibmWebSphereMQQM1
- The default certificate, if one is specified and no match has been found, based on the label.
WebSphere MQ client
When connecting from a WebSphere MQ client application, the SSL or TLS client sends a certificate only if it has one a certificate with a label in the format ibmwebspheremq, followed by the username of the user running the client application process.
The above label requirement applies to WebSphere MQ Message Service Clients for C, or C++, and .NET.
WebSphere MQ Java or WebSphere MQ JMS client
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.
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.