Practical mastering IBM MQ basics

*This series may be revised based on the latest mqpgf/mqpcf. Please always download and use the latest version.

In the previous chapter, I introduced how to configure certificate revocation (revoking) check using OCSP in server-to-server connection as an example. In this chapter, I will show you how to verify the digital certificate of the connection destination by OCSP in the client connection/client application.
This can be easily achieved by setting the Responder URL of the OCSP to OCSPResponderURL of the MQAIR(Authentication Information Record) structure.

In the following, as an example, start the OCSP responder on the CA that has been built on both the client machine and the server machine.

After this, it is assumed that the procedure for performing the client connection using SSL/TLS and the certificate verification by OCSP in the server-to-server connection in the previous chapters has been tested. If it is not executed, please refer to the previous chapters to set up.

Prerequisites and restrictions for OCSP configuration in the client connection

It is basically the same as the server-to-server connection described in "Prerequisites and Restrictions for OCSP Configuration" . For client applications, the connection information to the OCSP responder is set in the MQAIR(Authentication Information Record) referenced by the MQCONNX() API for each connection to the queue manager.

Launch and verify OCSP responder using openssl

The method of starting the OCSP responder on each machine is the same as the case of server-to-server connection. So if it is not implemented, please refer to "Launch and verify OCSP responder using openssl" explained at the time of server-to-server connection verification. And it is the same on the client side and the server side, and there is no difference.

* Client side cd ...\openssl\winca >openssl ocsp -ignore_err -index index.txt -CA cacert.pem -rsigner cacert.pem -rkey private/cakey.pem -port 2560 Enter pass phrase for private/cakey.pem: winca ocsp: waiting for OCSP client connections... * Server side cd .../openssl/nsca >openssl ocsp -ignore_err -index index.txt -CA cacert.pem -rsigner cacert.pem -rkey private/cakey.pem -port 2560 Enter pass phrase for private/cakey.pem: nsca ocsp: waiting for OCSP client connections...

*Option descriptions
ocsp: Runs the Online Certificate Status Protocol utility.
-index indexfile: indexfile is a ca-formatted text index file that contains certificate revocation information.
*If the "index" option is specified, the ocsp utility will be in responder mode. Otherwise it works in client mode.
-CA file: Specify the CA certificate.
-rsigner file: Specifies the certificate to sign the OCSP response.
-rkey file: Specifies the private key to sign the OCSP response.
-port portnum: Specifies the port on which to listen for OCSP requests.

Using OCSP for MQ client connection

If you have not already configured the connection to the OCSP responder in the queue manager, the same applies to the verification with the client connection, so set it up by referring to "Configuring OCSP responder references for server-to-server connections" .

How to refer to OCSP responder in client connection

Set the AuthInfoType of the MQAIR(Authentication Information Record) structure to MQAIT_OCSP (default is MQAIT_CRL_LDAP) and the OCSPResponderURL to the URL of the OCSP responder. Please note that you need to use MQAIR_VERSION_2 or higher at this time. The default is MQAIR_VERSION_1. If MQAIR_VERSION_2 is not specified, the OCSPResponderURL setting will be ignored.
Set the pointer to the created MQAIR in AuthInfoRecPtr of the MQSCO(SSL Configuration Options) structure. At this time, set AuthInfoRecCount to 1. As mentioned earlier, you can create a list of MQAIRs and set AuthInfoRecCount to a value greater than 1, but for OCSP configurations only the first MQAIR is referenced. Then, set the pointer to the created MQSCO in SSLConfigPtr of MQCNO (Connect Options). At this time, it is necessary to specify MQCNO_VERSION_4 or higher (default is MQCNO_VERSION_1).

Ex. 15.1.1 Specify the parameters for certificate verification by OCSP and connect to the queue manager

Specify the parameters for certificate verification by OCSP in mqpgfc and connect to the queue manager.

>mqpgfc -qm PL81N -q LQ1 MQGMO_WAIT MQWI_UNLIMITED -x <ipaddr or hostname>:<port> -ch PL81N.MQ ICHL -cl PL921WCA -cs TLS_AES_128_GCM_SHA256 MQCD_VERSION_11 -ru "http://<ipaddr or hostname>: <port>/" -tr MQAIR_VERSION_2 MQAIT_OCSP MQCNO_VERSION_4 -kr "..\clientssl\key" [2022/02/02 13:22:24.707] MQCONNX start qmgr:PL81N Options:0x00000000 [2022/02/02 13:22:26.205] MQCONNX stop hcon:50331654 qmgr:PL81N CompCd=00 ReasonCd=00 [2022/02/02 13:22:26.205] MQOPEN start hcon:50331654 ObjectName:LQ1 Options:0x00000001 [2022/02/02 13:22:26.337] MQOPEN stop hcon:50331654 hobj:101 ObjectName:LQ1 CompCd=00 ReasonCd =00 [2022/02/02 13:22:26.337] MQGET start hcon:50331654 hobj:101 Options:0x00000001 >

*Option descriptions
MQGMO_WAIT: Wait for a message to arrive on the queue
MQWI_UNLIMITED: Unlimited message arrival wait time
-x: Connection string to queue manager
-ch: Server connection channel name
-cl: Certificate label
-cs: Cipher Spec
MQCD_VERSION_11: Version of MQCD(Channel Definition) structure(to enable certificate label specification)
-ru: URL to connect to OCSP responder
MQAIR_VERSION_2: Version of MQAIR(Authentication Record) structure(to enable OCSPResponderURL)
MQAIT_OCSP: MQAIR(Authentication Record) type is OCSP
MQCNO_VERSION_4: Allows the MQSCO(SSL Configuration options) structure to be specified in MQCNO(Connect Options).
-kr: Location of the key repository(absolute path and excluding the extension of the key repository file(default is "key")). Specify it with the environment variable MQSSLKEYR, or set it directly in the KeyRepository field of MQSCO(SSL configuration options) structure with this parameter.

Make sure the channel starts successfully. Below is an example of a client connection from a Windows machine to a NonStop machine.

$ mqpcf chs -qm PL81N -c PL81N.MQICHL SECPROT SSLCERTI SSLCIPH
1: CHANNEL(PL81N.MQICHL) CHLTYPE(SVRCONN) CONNAME(16.168.2.37) CHLINSTYPE(CURRENT) SECPROT(TLSV13) SSLCERTI(E=support@pulsarintegration.com,CN=www.pulsarintegration.com,O=Pulsar Integration Inc.,ST=Chiba,C=JP) SSLCIPH(TLS_AES_128_GCM_SHA256) STATUS(RUNNING) STOPREQ(NO) SUBSTATE(RECEIVE) RAPPLTAG(...\mqpgfc.exe)

Behavior when unable to connect to OCSP responder(Client Connection)

Stop the OCSP responder on the server side.
The application will not be able to check the server certificate on the NonStop server side.

$ openssl ocsp -ignore_err -index index.txt -CA cacert.pem -rsigner cacert.pem -rkey private/cakey.pem -port 2560
Enter pass phrase for private/cakey.pem:
ocsp: waiting for OCSP client connections...
^C *Interrupt by CTRL+C
$

Restart the application and check the status.

>mqpgfc -qm PL81N -q LQ1 MQGMO_WAIT MQWI_UNLIMITED -x <ipaddr or hostname>:<port> -ch PL81N.MQ ICHL -cl PL921WCA -cs TLS_AES_128_GCM_SHA256 MQCD_VERSION_11 -ru "http://<ipaddr or hostname>: <port>/" -tr MQAIR_VERSION_2 MQAIT_OCSP MQCNO_VERSION_4 -kr "..\clientssl\key" [2022/02/02 14:38:22.459] MQCONNX start qmgr:PL81N Options:0x00000000 [2022/02/02 14:38:25.569] MQCONNX stop hcon:-1 qmgr:PL81N CompCd=02 ReasonCd=2393 MQCONNX fail : PL81N CompCd=02 ReasonCd=2393 !!! Queue Manager Connect Fail PL81N !!! >mqrc 2393 2393 0x00000959 MQRC_SSL_INITIALIZATION_ERROR * The connection fails with the reason code 2393 MQRC_SSL_INITIALIZATION_ERROR.

OCSPAuthentication is set in the SSL stanza of mqclient.ini on the client side, but since it is not set, its behavior is the default REQUIRED. Check the error messages of both.

*AMQ9716 was output to tthe client application(Windows) side, and the revoking status could not be confirmed that is displayed as the reason why the channel could not be started. ----- amqccisa.c : 9406 ------------------------------------------------------- AMQ9716E: Remote SSL certificate revocation status check failed for channel 'PL81N.MQICHL' Explanation IBM MQ failed to determine the revocation status of the remote SSL certificate for one of the following reasons: (a) The channel was unable to contact any of the CRL servers or OCSP responders for the certificate. (b) None of the OCSP responders contacted knows the revocation status of the certificate. (c) An OCSP response was received, but the digital signature of the response could not be verified. ------------------------- *FFST is also generated. +-----------------------------------------------------------------------------+ | | | IBM MQ First Failure Symptom Report | | ========================================= | .... | Probe Id :- XC022001 | .... | Major Errorcode :- rrcE_SSL_REVOCATION_CHECK_REQUIRED | | Minor Errorcode :- OK | | Probe Type :- MSGAMQ9716 | | Probe Severity :- 2 | | Probe Description :- AMQ9716E: Remote SSL certificate revocation status | | check failed for channel 'PL81N.MQICHL' | | FDCSequenceNumber :- 0 | | Comment1 :- | | [Class=]GSKVALMethod::X509[Issuer=]EMAIL=support@sd.pulsarintegration.com | | ,CN=www.sd.pulsarintegration.com,O=Pulsar Integration SD | | Inc.,ST=Sydney,C=AU[#=]01[Subject=]CN=www.sd.pulsarintegration.PL81N.com, | | O=Pulsar Integration PL81NA Inc.,ST=Sydney,C=AU | | Comment2 :- gsk_attribute_get_buffer - | | GSK_UNKNOWNREVOCATIONSTATUS_SUBJECT | | Comment3 :- PL81N.MQICHL | | | +-----------------------------------------------------------------------------+ *No error is displayed on the NonStop (server) side because the client application fails to connect to the OCSP responder and terminates before attempting a channel connection.

Next, start the OCSP responder on the NonStop(server) side and stop the OCSP responder on the client application(Windows) side.

>mqpgfc -qm PL81N -q LQ1 MQGMO_WAIT MQWI_UNLIMITED -x <ipaddr or hostname>:<port> -ch PL81N.MQ ICHL -cl PL921WCA -cs TLS_AES_128_GCM_SHA256 MQCD_VERSION_11 -ru "http://<ipaddr or hostname>: <port>/" -tr MQAIR_VERSION_2 MQAIT_OCSP MQCNO_VERSION_4 -kr "..\clientssl\key" [2022/02/02 15:23:38.532] MQCONNX start qmgr:PL81N Options:0x00000000 [2022/02/02 15:23:59.409] MQCONNX stop hcon:-1 qmgr:PL81N CompCd=02 ReasonCd=2393 MQCONNX fail : PL81N CompCd=02 ReasonCd=2393 !!! Queue Manager Connect Fail PL81N !!! >mqrc 2393 2393 0x00000959 MQRC_SSL_INITIALIZATION_ERROR *Similarly, the connection fails with the reason code 2393 MQRC_SSL_INITIALIZATION_ERROR.

Check the error messages of both.

*AMQ9665E is displayed to the client application(Windows) side, and it is reported that the TLS connection has been closed from the remote side. ----- amqcrhna.c : 785 -------------------------------------------------------- AMQ9665E: SSL connection closed by remote end of channel 'PL81N.MQICHL' ----- amqccisa.c : 11368 ------------------------------------------------------ AMQ9716 is output to the NonStop(server) side, and the revoking status could not be confirmed that is displayed as the reason why the channel could not be started. ----- amqrmrsa.c : 926 -------------------------------------------------------- AMQ9716: Remote SSL certificate revocation status check failed for channel .... The details of the certificate in question are '/C=JP/ST=Chiba/O=Pulsar Integration PL921WC Inc./CN=www.pulsarintegration.PL921WC.com'. .... IBM MQ does not allow the channel to start unless the certificate revocation status can be determined. .... ----- amqcciso.c : 3968 -------------------------------------------------------

Changes in behavior when the certificate cannot be verified(Unknown)(Client connection)

For clients, it is similar to a server-to-server connection except that OCSPAuthentication is set in the SSL stanza of mqclient.ini, so see the description in "Changes in behavior when the certificate cannot be verified(Unknown)" .

Behavior when the query result to the OCSP responder is "Revoked"(Client connection)

Revokes the server certificate on the NonStop side.

$ cd .../openssl/nsca $ openssl ca -config openssl.cnf -cert cacert.pem -keyfile private/cakey.pem -revoke .../var/ mqm/qmgrs/PL81N/ssl/PL81NA.pem Using configuration from openssl.cnf Enter pass phrase for private/cakey.pem: Revoking Certificate 01. Data Base Updated $ $ cat index.txt R 310802082027Z 210929080911Z 01 unknown /C=AU/ST=Sydney/O=Pulsar Integration PL81NA Inc./CN=www.sd.pulsarintegration.PL81N.com V 310824073603Z 02 unknown /C=AU/ST=Sydney/O=Pulsar Integration PL81NA Inc./CN=www.sd.pulsarintegration.PL81Nec.com

Don't forget to restart the OCSP responder.

$ openssl ocsp -ignore_err -index index.txt -CA cacert.pem -rsigner cacert.pem -rkey private/ cakey.pem -port 2560 Enter pass phrase for private/cakey.pem: Waiting for OCSP client connections... ^C *Interrupt by CTRL+C $ $ openssl ocsp -ignore_err -index index.txt -CA cacert.pem -rsigner cacert.pem -rkey private/ cakey.pem -port 2560 Enter pass phrase for private/cakey.pem: nsca Waiting for OCSP client connections...

Start the client application (Windows) and try a TLS connection to check the status.

>mqpgfc -qm PL81N -q LQ1 MQGMO_WAIT MQWI_UNLIMITED -x <ipaddr or hostname>:<port> -ch PL81N.MQ ICHL -cl PL921WCA -cs TLS_AES_128_GCM_SHA256 MQCD_VERSION_11 -ru "http://<ipaddr or hostname>: <port>/" -tr MQAIR_VERSION_2 MQAIT_OCSP MQCNO_VERSION_4 -kr "..\clientssl\key" [2022/02/02 16:46:29.752] MQCONNX start qmgr:PL81N Options:0x00000000 [2022/02/02 16:46:35.380] MQCONNX stop hcon:-1 qmgr:PL81N CompCd=02 ReasonCd=2393 MQCONNX fail : PL81N CompCd=02 ReasonCd=2393 !!! Queue Manager Connect Fail PL81N !!! C:\Users\okadako>mqrc 2393 2393 0x00000959 MQRC_SSL_INITIALIZATION_ERROR

Check what is displayed in both error logs.

>*AMQ9633E is output to the client application(Windows) side, and shows that the certificate was invalid as the reason why the channel could not be started. ----- amqcrhna.c : 789 -------------------------------------------------------- AMQ9633E: Bad SSL certificate for channel 'PL81N.MQICHL' .... (e) an OCSP responder has indicated that it is revoked .... The details of the certificate which could not be validated are '[Class=]GSKVALMethod::X509[Issuer=]EMAIL=support@sd.pulsarintegration.com, CN=www.sd.pulsarintegration.com,O=Pulsar Integration SD Inc.,ST=Sydney,C=AU[#=]01[Subject=]CN=www.sd.pulsarintegration.PL81N.com,O=Pulsar Integration PL81NA Inc.,ST=Sydney,C=AU' The certificate validation error was 575032 .... ----- amqccisa.c : 8789 ------------------------------------------------------- *AMQ9633 is also output to the server(NonStop) side, and shows that the certificate was invalid as the reason why the channel could not be started. ------------------------------------------------------------------------------- AMQ9633: Bad SSL certificate for channel '????'. .... (e) an OCSP responder has indicated that it is revoked .... The details of the certificate which could not be validated are 'sslv3 alert bad certificate'. The certificate validation error was 1042. .... ----- amqcciso.c : 9785 -------------------------------------------------------

cd ,,,\openssl\winca >type index.txt V 310802064352Z 01 unknown /C=JP/ST=Chiba/O=Pulsar Integration PL92WA Inc./CN=www.pulsarintegration.PL92W.com V 310816062807Z 02 unknown /C=JP/ST=Chiba/O=Pulsar Integration PL921WC Inc./CN=www.pulsarintegration.PL921WC.com V 310824072450Z 03 unknown /C=JP/ST=Chiba/O=Pulsar Integration PL921WC Inc./CN=www.pulsarintegration.PL921WCec.com >openssl ca -config openssl.cnf -cert cacert.pem -keyfile private\cakey.pem -revoke ..\..\ clientssl\PL921WCA.pem Using configuration from openssl.cnf Enter pass phrase for private\cakey.pem: Revoking Certificate 02. Data Base Updated >type index.txt V 310802064352Z 01 unknown /C=JP/ST=Chiba/O=Pulsar Integration PL92WA Inc./CN=www.pulsarintegration.PL92W.com R 310816062807Z 220202080659Z 02 unknown /C=JP/ST=Chiba/O=Pulsar Integration PL921WC Inc./CN=www.pulsarintegration.PL921WC.com V 310824072450Z 03 unknown /C=JP/ST=Chiba/O=Pulsar Integration PL921WC Inc./CN=www.pulsarintegration.PL921WCec.com

Don't forget to restart the OCSP responder.

$ openssl ocsp -ignore_err -index index.txt -CA cacert.pem -rsigner cacert.pem -rkey private/ cakey.pem -port 2560 Enter pass phrase for private/cakey.pem: ocsp: waiting for OCSP client connections... ^C *Interrupt by CTRL+C $ >openssl ocsp -ignore_err -index index.txt -CA cacert.pem -rsigner cacert.pem -rkey private/ cakey.pem -port 2560 Enter pass phrase for private/cakey.pem: ocsp: waiting for OCSP client connections...

Start the client application (Windows) and try a TLS connection to check the status.

>mqpgfc -qm PL81N -q LQ1 MQGMO_WAIT MQWI_UNLIMITED -x <ipaddr or hostname>:<port> -ch PL81N.MQ ICHL -cl PL921WCA -cs TLS_AES_128_GCM_SHA256 MQCD_VERSION_11 -ru "http://<ipaddr or hostname>: <port>/" -tr MQAIR_VERSION_2 MQAIT_OCSP MQCNO_VERSION_4 -kr "..\clientssl\key" [2022/02/02 17:19:44.769] MQCONNX start qmgr:PL81N Options:0x00000000 [2022/02/02 17:19:50.793] MQCONNX stop hcon:-1 qmgr:PL81N CompCd=02 ReasonCd=2393 MQCONNX fail : PL81N CompCd=02 ReasonCd=2393 !!! Queue Manager Connect Fail PL81N !!! C:\Users\okadako>mqrc 2393 2393 0x00000959 MQRC_SSL_INITIALIZATION_ERROR

Check what is displayed in both error logs.

*AMQ9665E is output to the client application(Windows) side, and it is reported that the TLS connection has been closed by the remote side. ----- amqcrhna.c : 785 -------------------------------------------------------- AMQ9665E: SSL connection closed by remote end of channel 'PL81N.MQICHL' ----- amqccisa.c : 11368 ------------------------------------------------------ *AMQ9633 is output to the NonStop(Server) side, and shows that the certificate was invalid as the reason why the channel could not be started. ------------------------------------------------------------------------------- AMQ9633: Bad SSL certificate for channel '????'. .... (e) an OCSP responder has indicated that it is revoked .... The details of the certificate which could not be validated are 'Certificate /C=JP/ST=Chiba/O=Pulsar Integration PL921WC Inc./CN=www.pulsarintegration.PL921WC.com was revoked by AUTHINFO URL http://xxx.xxx.xxx.xxx:xxxx'. The certificate validation error was 23. .... ----- amqcciso.c : 9785 -------------------------------------------------------

Same as when connecting between servers, if you want to undo the revocation after validation, use a backup of index.txt to undo it. Don't forget to restart the OCSP responder as well.

$ cp -p index.txt.old index.txt
$ cat index.txt
V 310802082027Z 01 unknown /C=AU/ST=Sydney/O=Pulsar Integration PL81NA Inc./CN=www.sd.pulsarintegration.PL81N.com
V 310824073603Z 02 unknown /C=AU/ST=Sydney/O=Pulsar Integration PL81NA Inc./CN=www.sd.pulsarintegration.PL81Nec.com
*After restoring index.txt, restart the OCSP responder.

to the top