+

Search Tips | Advanced Search

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.


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, we 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:

  • The certificate label can contain up to 64 characters.
  • The certificate label can contain up to 32 characters.
  • The certificate label cannot contain spaces.
  • Labels are case sensitive.
  • On systems that use EBCDIC katakana, we cannot use lowercase characters.
  • IBM MQ client for HP Integrity NonStop Server certificate labels cannot contain forward-slash (/), back-slash (\), tilde (˜), dollar ($) or more than one consecutive period (.).

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.

We can set the certificate label to a value of our choice. If we do not set a value, a default label is used that follows a naming convention depending on the platform that we are using. For details, see the sections that follow, about particular platforms. Notes:
  1. We 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:

  • All current Java and JMS clients.
  • Versions of IBM MQ prior to Version 8.0.

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 Version 8.0 supports the use of multiple certificates on the same queue manager, using a per-channel certificate label attribute. 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 we use MQIPT with a route that has both SSLServer and SSLClient set, there are two separate TLS sessions between the endpoints, and the SNI data will not flow across the session break.

We can use separate MQIPT routes to get multiple certificate support by selecting the appropriate certificate, for example through the SSLServerSiteLabel and SSLClientSiteLabel route properties. Alternatively, use MQIPT SSLProxyMode which forwards all TLS control flows intact, including the SNI name.

Note that multiple certificates across MQIPT work only if we are using TLS proxy mode. See SSL/TLS support for more information.

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


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 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.

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, we can enable debugging by setting javax.net.debug=ssl in the JVM environment.

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


IBM MQ client for HP Integrity NonStop Server

IBM MQ client for HP Integrity NonStop Server uses the channel CERTLABL attribute (or the value of the MQCERTLABL environment variable) to choose a certificate to be used for a TLS connection.

The certificate label, whether derived from the channel's CERTLABL attribute or from the value of the MQCERTLABL environment variable, is used to construct the name of the cert*.pem file and the corresponding Stash*.sth file. 
cert_CERTLABL.pem
Stash_CERTLABL.sth
If the channel does not have a CERTLABL attribute and the MQCERTLABL environment variable is not present, then IBM MQ uses the following certificate and stash files: 
cert_default_userid.pem
Stash_default_userid.sth
where userid is the name of the user that is executing the IBM MQ client program. If the cert_default_userid.pem file or the Stash_default_userid.sth file does not exist, then IBM MQ uses the following certificate and stash files: 
cert.pem
Stash.sth
Notes:
  1. The fallback to the cert_default_userid.pem and Stash_default_userid.sth files or the unqualified cert.pem and Stash.sth files only occurs if a certificate label is available from neither the channel's CERTLABL attribute nor the MQCERTLABL environment variable. If a CERTLABL is specified, then the associated cert_label.pem and Stash_label.sth files must exist and be accessible for the connection to proceed.
  2. IBM MQ rejects certificate labels containing any of the following characters:

    • /
    • \
    • ~
    • $

    and also rejects certificate labels containing more than one consecutive dot (.)

  3. The receiving channel program needs to access a certificate with the label name used for the queue manager, that is the QMGR CERTLABL setting.

    The default value for the QMGR CERTLABL setting is ibmwebspheremq, appended with the name of the queue manager, all in lowercase. For example, with a queue manager named QM1, the default certificate label is ibmwebspheremqqm1

    This rule applies even when we are using the CERTLABL attribute on the channel to tell the queue manager to use a different certificate for the channel.

Parent topic: The SSL/TLS key repository

Last updated: 2020-10-04