IBM Support

Specifying the userid in the SSL certificate label for an MQ client

Technote (FAQ)


Question

Does the standard WebSphere MQ SSL configuration require the personal certificates' label name with a special format as below?

WebSphere MQ Client: ibmwebspheremq + <User ID>
WebSphere MQ Server (queue manager): ibmwebspheremq + <QM Name>

Where the User ID or queue manager name must be folded to lower case in the label. For example, for a queue manager named QM1, the label is ibmwebspheremqqm1.

You want to know if you must comply with the rule for all of your MQ Clients, because you have many clients and it will be a big job to create and maintain unique certificates.

Cause

The original design and intent of the WebSphere MQ product to this question is YES. For MQ versions 5.3, 6, 7.0, 7.1 and 7.5 a personal certificate with a label of 'ibmwebspheremq<username>' for each client connection is necessary. However, depending on the MQ version and maintenance level installed, you have the option to use an alternative method to ease the administration and maintenance burden.

Answer

The gskXcmd or gskXcapicmd command from GSKit provides the command options -getdefault and -setdefault to display or set the default personal certificate in a key repository. The behavior of this area of code has changed a few times, so below is a description of the expected behavior designated by the MQ version and maintenance level.

Note: The 'X' in the GSKit commands above represents the version of GSKit. For example, MQ V5.3 used GSKit V6, therefore the commands would be called gsk6cmd or gsk6capicmd. With the release of MQ V7.1 and later versions, GSKit was further integrated into the MQ product and as such the GSKit commands were changed to runmqckm and runmqakm respectively.


WebSphere MQ V5.3

  • WebSphere MQ 5.3 CSD09 or earlier
    The default certificate will be used if: a default certificate is present, and there is no ibmwebspheremq certificate.
    This behavior was a defect which was corrected by APAR IC43762.
  • WebSphere MQ 5.3 CSD10 through CSD12
    The default certificate will never be used. If you are at this level and require default certificate functionality, then you will need the fix for APAR IC50156 and you must set the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable, as described in IC50156 APAR text.
  • WebSphere MQ 5.3 CSD13 and later
    The default certificate will only be used if the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable is set, and the following conditions are both met: default certificate is present, and there is no ibmwebspheremq certificate


WebSphere MQ V6

  • WebSphere MQ 6.0.0.0 through 6.0.1.1
    The default certificate will never be used. If you are at this level and require default certificate functionality, then you will need the fix for APAR IC50156 and must set the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable.
  • WebSphere MQ 6.0.2.0 and later
    The default certificate will only be used if the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable is set, and the following conditions are both met: default certificate is present, and there is no ibmwebspheremq certificate.


WebSphere MQ 7.x
  • WebSphere MQ 7.0.x, 7.1.0.x, and 7.5.0.x Versions
    The default certificate will only be used if the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable is set, and the following conditions are both met: default certificate is present, and there is no ibmwebspheremq certificate.

IBM MQ V8

  • IBM MQ 8.0.0.0 through 8.0.0.6
The default certificate will never be used. If your MQ client is at these code levels and require default certificate functionality, then you will need the fix for APAR IT15978 and must set the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable.
  • IBM MQ 8.0.0.7

The default certificate will only be used if the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable is set, and the following two conditions are met:
1. A default certificate is present in the key repository.
2. The key repository does not contain a personal certificate with the prefix ibmwebspheremq certificate.


IBM MQ V9 LTS (Long Term Support)
  • IBM MQ 9.0.0.0
The default certificate will never be used. If your MQ client is at this code level and require default certificate functionality, then you will need the fix for APAR IT15978 and must set the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable.
  • IBM MQ 9.0.0.1 and later

The default certificate will only be used if the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable is set, and the following two conditions are met:
1. A default certificate is present in the key repository.
2. The key repository does not contain a personal certificate with the prefix ibmwebspheremq certificate.


IBM MQ V9 CD (Continuous Delivery)
  • IBM MQ 9.0.1
The default certificate will never be used. If your MQ client is at this code level and require default certificate functionality, then you will need the fix for APAR IT15978 and must set the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable.
  • IBM MQ 9.0.2 and later

The default certificate will only be used if the AMQ_SSL_ALLOW_DEFAULT_CERT environment variable is set, and the following two conditions are met:
1. A default certificate is present in the key repository.
2. The key repository does not contain a personal certificate with the prefix ibmwebspheremq certificate.



Notes:
1. All of the above holds true if you are using the MQ C client. If you are using MQ Java™ or MQ JMS clients the answer is NO, you do not need a unique certificate for every client userid. In the MQ Java and MQ JMS client environment the label is not used to do the certificate look up. However, a personal certificate for the queue manager end still needs a label of 'ibmwebspheremq<qmgrname>'.

2. The above information does not apply to platforms which do not use GSKit, such as z/OS for example or MQ v5.3 for Windows. MQ v6 for Windows does use GSkit, so the information is applicable on MQ V6 for Windows.

3. With the release of the IBM MQ 8 and 9 product versions, another option was provided to designate a personal certificate with an MQ client. This new option is to use the "certificate label" attribute. The attribute and value can be configured on a client connection channel (CCDT), an environment variable, in the mqclient.ini file or passed programmatically using the MQSCO structure.
For information regarding use and configuration of the "certificate label" attribute, please review the following IBM MQ Knowledge Center article.

Digital certificate labels, understanding the requirements

Warning:
Please note that the decision to remove default certificate support from WebSphere MQ was not made lightly, and was made for a number of security concerns. Although we have restored this in a limited way due to specific unique requests, this was not the functionality which we expected to see widely used. It is certainly not an approach which we recommend.

The administration of an SSL environment is something which we would advise you to consider carefully. Certificates are intended to provide a unique identification of a specific entity. The ability to establish a chain of trust from a trusted signer down to individual certificates allows for some of this administration to be delegated, however the use of default certificates makes it possible for far greater reuse and sharing of certificates to be achieved than is intended. In an extreme case, one default self-signed certificate could be used by every client and queue manager on a network, greatly increasing the risk of exposure to your network if the certificate becomes compromised.


If authentication of clients is not required, then you may find that setting SSLCAUTH to OPTIONAL in your channel definitions is a better solution for your needs. However, if authentication of clients is important, then you should consider whether wide reuse of a default certificate meets that need.


Cross reference information
Segment Product Component Platform Version Edition
Business Integration IBM MQ SSL AIX, HP-UX, Linux, Solaris, Windows 9.0, 8.0, 7.5, 7.1, 7.0, 6.0, 5.3

Product Alias/Synonym

WebSphere MQ WMQ MQSeries

Document information

More support for: WebSphere MQ
SSL

Software version: 5.3, 6.0, 7.0, 7.1, 7.5, 8.0, 9.0

Operating system(s): AIX, HP-UX, Linux, Solaris, Windows

Reference #: 1245474

Modified date: 17 October 2017


Translate this page: