Digital certificate labels, understanding the requirements

When setting up 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.

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 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. If necessary, however, you can change the label associated with a digital certificate.

Certificate label syntax

A certificate label can contain letters, numbers, and punctuation with the following conditions:
  • [UNIX, Linux, Windows, IBM i]The certificate label can contain up to 64 characters.
  • [z/OS]The certificate label can contain up to 32 characters.
  • The certificate label can contain spaces.
  • Labels are case sensitive.
  • On systems that use EBCDIC katakana, you cannot use lowercase characters.

Additional requirements for certificate label values are specified in the following sections.

How is the certificate label used?

IBM® MQ uses certificate labels to locate a personal certificate that is sent during the TLS handshake. This eliminates ambiguity when more than one personal certificate exists in the key repository.

You can set the certificate label to a value of your choice. If you do not set a value, a default label is used that follows a naming convention depending on the platform that you are using. For details, see the sections that follow, about particular platforms.
Notes:
  1. You cannot set the certificate label yourself on Java or JMS systems.
  2. Auto-defined channels created by a channel automatic definition (CHAD) exit cannot set the certificate label, because the TLS handshake has occurred by the time the channel is created. Setting the certificate label in a CHAD exit for inbound channels has no effect.

In this context, a TLS client refers to the connection partner initiating the handshake, which might be an IBM MQ client or another queue manager.

During the TLS handshake, the TLS client always obtains and validates a digital certificate from the server. With the IBM MQ implementation, the TLS server always requests a certificate from the client and the client always provides a certificate to the server if one is found. If the client is unable to locate a personal certificate, the client sends a no certificate response to the server.

The 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 TLS server is defined with either the SSLCAUTH parameter set to REQUIRED or an SSLPEER parameter value set.

Note that inbound channels (including receiver, requester, cluster-receiver, unqualified server, and server-connection channels) only send the configured certificate if the IBM MQ version of the remote peer fully supports certificate label configuration, and the channel is using a TLS CipherSpec.

An unqualified server channel is one that does not have the CONNAME field set.

In all other cases, the queue manager CERTLABL parameter determines the certificate sent. In particular, the following only ever receive the certificate configured by the CERTLABL parameter of the queue manager, regardless of the channel-specific label setting:
  • Prior to IBM MQ 9.1.1, all current Java and JMS clients.
  • [V9.1.1 Nov 2018]From IBM MQ 9.1.1, Java and JMS clients supporting Server Name Indication (SNI), that is, certificates on a channel by channel basis.
  • Versions of IBM MQ prior to IBM MQ 8.0.
  • Managed .NET clients

Additionally, the certificate used by a channel must be appropriate for the channel CipherSpec - see Digital certificates and CipherSpec compatibility in IBM MQ for further information.

IBM MQ 8.0 and later supports the use of multiple certificates on the same queue manager, using a per-channel certificate label, specified using the CERTLABL attribute on the channel definition. Inbound channels to the queue manager (for example, server connection or receiver) rely on detecting the channel name using TLS Server Name Indication (SNI), in order to present the correct certificate from the queue manager.

If a channel connects to the destination queue manager through IBM MQ Internet Pass-Thru (MQIPT), and the MQIPT route has both SSLServer and SSLClient set, there are two separate TLS sessions between the endpoints, and the SNI data does not flow across the session break. This prevents a per-channel certificate from being used on the destination queue manager, for the TLS connection between MQIPT and the queue manager. To use a per-channel certificate on the destination queue manager, for a TLS connection that passes through MQIPT, the MQIPT route must use TLS proxy mode, which forwards all TLS control flows intact, including the SNI name. For more information about TLS support in MQIPT, see SSL/TLS support.

The certificates that are used for TLS connections that are terminated or initiated by MQIPT can be configured individually for each route, for example by using the SSLServerSiteLabel and SSLClientSiteLabel route properties.

For more information about connecting a queue manager using one-way authentication, that is, when the TLS client does not send a certificate, see Connecting two queue managers using one-way authentication.

[UNIX, Linux, Windows, IBM i]

Multiplatforms systems

On Multiplatforms, the TLS server sends a certificate to the client.

For queue managers and clients respectively, the following sources are searched in sequence for a non-empty value. The first non-empty value determines the certificate label. The certificate label must exist in the key repository. If no matching certificate in the correct case and format is found that matches a label, an error occurs and the TLS handshake fails.

Queue managers
  1. Channel certificate label attribute CERTLABL.
  2. Queue manager certificate label attribute CERTLABL.
  3. A default, which is in the format: ibmwebspheremq with the name of the queue manager appended, all in lowercase. For example, for a queue manager named QM1, the default certificate label is ibmwebspheremqqm1.
IBM MQ clients
  1. Certificate label attribute CERTLABL in the CLNTCONN channel definition.
  2. MQSCO structure CertificateLabel attribute.
  3. Environment variable MQCERTLABL.
  4. Client .ini file (in its SSL section) CertificateLabel attribute
  5. A default, which is in the format: ibmwebspheremq with the user ID that the client application is running as appended, all in lowercase. For example, for a user ID of USER1, the default certificate label is ibmwebspheremquser1.
[z/OS]

z/OS systems

IBM MQ Clients are not supported on z/OS®. However, a z/OS queue manager can act in the role of a TLS client when initiating a connection, or a 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 Multiplatforms.

For queue managers and clients respectively, the following sources are searched in sequence for a non-empty value. The first non-empty value determines the certificate label. The certificate label must exist in the key repository. If no matching certificate in the correct case and format is found that matches a label, an error occurs and the TLS handshake fails.
  1. Channel certificate label attribute, CERTLABL.

  2. If shared, the queue sharing group certificate label attribute, CERTQSGL.

    If not shared, the queue manager certificate label attribute, CERTLABL.

  3. A default, which is in the format: ibmWebSphereMQ with the name of the queue manager or queue sharing group appended. Note that this string is case-sensitive and must be written as shown. For example, for a queue manager named QM1, the default certificate label is ibmWebSphereMQQM1.
  4. If there is not a certificate found with the format in option 3, IBM MQ attempts to use the certificate marked as default in the key ring.
For information on how to display the key repository, see Locating the key repository for a queue manager on z/OS.

IBM MQ Java and IBM MQ JMS clients

IBM MQ Java and IBM MQ JMS clients use the facilities of their Java Secure Socket Extension (JSSE) provider to select a personal certificate during the TLS handshake and are not therefore 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 IBM MQ Java client application in combination with your specific JSSE provider, you can enable debugging by setting javax.net.debug=ssl in the JVM environment.

You can set the variable within the application, through configuration, or by entering -Djavax.net.debug=ssl on the command line.