Digital certificate labels, understanding the requirements
When setting up SSL and TLS to use digital certificates, there might be specific label requirements that you must follow, depending on the platform used and the method you use to connect.
About this task
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?
IBM® 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 IBM 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 IBM 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, see Connecting two queue managers using one-way authentication.
, UNIX, Linux, and Windows systems
About this task
On , 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 IBM WebSphere MQ format. On
these systems, the correct format is ibmwebspheremq, followed by the name of your queue manager changed to lowercase.
QM1, the
certificate label requirement is:ibmwebspheremqqm1IBM WebSphere MQ client
About this task
When connecting from a IBM 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.
wasadmin, the
certificate label requirement is as shown, folded to lowercase: ibmwebspheremqwasadmin
The above label requirement applies to Message Service Clients for C, or C++, and .NET.
IBM WebSphere MQ Java or IBM WebSphere MQ JMS client
About this task
IBM WebSphere MQ Java or IBM 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.
javax.net.debug=sslYou can use -Djavax.net.debug=ssl on the command line, or set the variable within the application,
or through configuration.