MQ

This is part of a series of small blog posts which will cover some of the smaller, perhaps less likely to be noticed, features of IBM MQ. Read other posts in this series.

If you use client connections, you'll no doubt be aware that there are three different ways to provide the client connection configuration.

• MQSERVER environment variable
• CCDT file
• Information coded in the application

While you may not code applications that do the last one, you undoubtedly use tools that do. Tools that allow you to specify the connection name, and perhaps some SSL/TLS parameters as part of configuring the tool for use, for example MQ Explorer.

The CCDT file contains two different types of records. It contains channel definitions of CHLTYPE(CLNTCONN) but it also contains Authentication Information Records (MQAIR) which hold information about how to do certificate revocation checking, or OCSP checking. The equivalent information to that which you might define on the queue manager in AUTHINFO TYPE(CRLLDAP) and TYPE(OCSP) objects.

What you may not have been aware of is that even when you don't think you are using a CCDT, in fact it may still be utilised.

If you're setting up your SSL/TLS configuration by supplying it to the tool, that means the tool is coding that information in the MQ connection, rather than using a CCDT. You might be forgiven for concluding that this meant you didn't need a CCDT. However, the MQ Client code still needs to find its certificate revocation information from somewhere and it looks for this information in a CCDT. If there are no Authentication Information Records in the CCDT then it continues happily under the premise that you don't need any additional configuration for that - after all many certificates now contain the information encoded within them.

However, a problem arises if it can't find a CCDT. On Windows it will check Active Directory next and if it doesn't find any certificate revocation checking information there either it will again continue happily under the premise that you don't need any. On Linux (and I assume other Unixes although I haven't tested those) there is no Active Directory alternative, and so it reports an error and does not allow the connection to continue.

You can see this happening using the provided sample thus:-

amqssslc -c SSl.SVRCONN -x "localhost(1414)" -s TLS_RSA_WITH_AES_128_CBC_SHA

Replacing the channel name, connection name, and cipherspec with your own.

This will report a reason code 2059, and when you look in the error log you'll see:

AMQ9518: File '/var/mqm/AMQCLCHL.TAB' not found.
EXPLANATION:
The program requires that the file '/var/mqm/AMQCLCHL.TAB' is present and
available.
ACTION:
This may be caused by invalid values for the optional environment variables
MQCHLLIB, MQCHLTAB or MQDATA. If these variables are valid or not set then
record the name of the file and tell the systems administrator who must ensure
that file '/var/mqm/AMQCLCHL.TAB' is available to the program.

One easy way to fix this issue is to create dummy CCDT with a channel that you have no intention of ever using. This means that the CCDT does exist, it satisfies the code that is checking to see if you have any Authentication Information configuration for certificate revocation, and it goes on its merry way.

This behaviour comes about as a result of the ClientRevocationChecks attribute in the mqclient.ini which defaults to a value of REQUIRED (see IBM Knowledge Center) and provides this description:

REQUIRED (default)

Attempts to load certificate revocation configuration from the CCDT and perform revocation checking as configured. If the CCDT file cannot be opened or it is not possible to validate the certificate (because an OCSP or CRL server is not available, for example) the MQCONN call fails. No revocation checking is performed if the CCDT contains no revocation configuration but this does not cause the channel to fail.

On Windows systems, you can also use Active Directory for CRL revocation checking. You cannot use Active Directory for OCSP revocation checking.

If you use one of the other values for ClientRevocationChecks then the problem goes away, but I feel safer providing the dummy CCDT because I won't forget about this setting if at some future time I might want to require the revocation checks.

The other way to avoid this check is to also supply an MQSCO in your program. What does this mean for you if you're not coding it yourself? Well, the Key Repository information is supplied in the MQSCO, so if your tool allows you to specify where the Key Repository resides then you will avoid this check, but if you need to set the MQSSLKEYR environment variable to supply that information, then this check will come into play again. You can see the difference by using the same sample we showed above with an extra parameter.

amqssslc -c SSl.SVRCONN -x "localhost(1414)" -s TLS_RSA_WITH_AES_128_CBC_SHA -k /home/mqgemusr/ssl/key

I highlight this just to ensure that if you ever see an error in your client error log suggesting it was trying to use a CCDT when you didn't expect it to, just remember about this case.