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.

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:
  • Distributed[IBMi]The certificate label can contain up to 64 characters.
  • [z/OS]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, you 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 SSL 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 SSL or 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, an SSL or TLS client refers to the connection partner initiating the handshake, which might be an IBM 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 MQ implementation, the SSL or 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 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.

Note that inbound channels (including receiver, 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.

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

You 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 SSL or TLS control flows intact, including the SNI name.

Note that multiple certificates across MQIPT work only if you are using SSL or TLS proxy mode.

See the SSL/TLS support section of the IBM MQ Internet Pass-Thru documentation for more information.

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.

IBM i, UNIX, Linux®, and Windows systems

[IBMi][Windows][UNIX][Linux] The SSL or 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 SSL or 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

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

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

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 an SSL 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 you are using the CERTLABL attribute on the channel to tell the queue manager to use a different certificate for the channel.