Revoked certificates and OCSP

Revoked certificates and OCSP

IBM MQ determines which Online Certificate Status Protocol (OCSP) responder to use, and handles the response received. We might have to take steps to make the OCSP responder accessible.
Note: This information applies only to IBM MQ on UNIX, Linux, and Windows systems. To check the revocation status of a digital certificate using OCSP, IBM MQ can use two methods to determines which OCSP responder to contact:

By using the AuthorityInfoAccess (AIA) certificate extension in the certificate to be checked.
By using a URL specified in an authentication information object or specified by a client application.

A URL specified in an authentication information object or by a client application takes priority over a URL in an AIA certificate extension.
If the URL of the OCSP responder lies behind a firewall, reconfigure the firewall so the OCSP responder can be accessed or set up an OCSP proxy server. Specify the name of the proxy server by using the SSLHTTPProxyName variable in the SSL stanza. On client systems, we can also specify the name of the proxy server by using the environment variable MQSSLPROXY. For more details, see the related information.

If we are not concerned whether TLS certificates are revoked, perhaps because we are running in a test environment, we can set OCSPCheckExtensions to NO in the SSL stanza. If you set this variable, any AIA certificate extension is ignored. This solution is unlikely to be acceptable in a production environment, where you probably do not want to allow access from users presenting revoked certificates.
The call to access the OCSP responder can result in one of the following three outcomes:

Good

The certificate is valid.

Revoked

The certificate is revoked.

Unknown

This outcome can arise for one of three reasons:

IBM MQ cannot access the OCSP responder.
The OCSP responder has sent a response, but IBM MQ cannot verify the digital signature of the response.
The OCSP responder has sent a response that indicates that it has no revocation data for the certificate.

If IBM MQ receives an OCSP outcome of Unknown, its behavior depends on the setting of the OCSPAuthentication attribute. For queue managers, this attribute is held in one of the following locations:

In the SSL stanza of the qm.ini file on UNIX and Linux.
In the Windows registry.

This attribute can be set using the IBM MQ Explorer. For clients, the attribute is held in the SSL stanza of the client configuration file.
If an outcome of Unknown is received and OCSPAuthentication is set to REQUIRED (the default value), IBM MQ rejects the connection and issues an error message of type AMQ9716. If queue manager SSL event messages are enabled, an SSL event message of type MQRC_CHANNEL_SSL_ERROR with ReasonQualifier set to MQRQ_SSL_HANDSHAKE_ERROR is generated.

If an outcome of Unknown is received and OCSPAuthentication is set to OPTIONAL, IBM MQ allows the SSL channel to start and no warnings or SSL event messages are generated.

If an outcome of Unknown is received and OCSPAuthentication is set to WARN, the SSL channel starts but IBM MQ issues a warning message of type AMQ9717 in the error log. If queue manager SSL event messages are enabled, an SSL event message of type MQRC_CHANNEL_SSL_WARNING with ReasonQualifier set to MQRQ_SSL_UNKNOWN_REVOCATION is generated.

Digital signing of OCSP responses
An OCSP responder can sign its responses in one of three ways. Your responder will inform you which method is used.

The OCSP response can be digitally signed using the same CA certificate that issued the certificate that we are checking. In this case, we do not need to set up any additional certificate; the steps you have already taken to establish TLS connectivity are sufficient to verify the OCSP response.
The OCSP response can be digitally signed using another certificate signed by the same certificate authority (CA) that issued the certificate we are checking. The signing certificate is sent together with the OCSP response in this case. The certificate flowed from the OCSP responder must have an Extended Key Usage Extension set to id-kp-OCSPSigning so that it can be trusted for this purpose. Because the OCSP response is sent with the certificate which signed it (and that certificate is signed by a CA that is already trusted for TLS connectivity), no additional certificate setup is required.
The OCSP response can be digitally signed using another certificate that is not directly related to the certificate we are checking. In this case, the OCSP response is signed by a certificate issued by the OCSP responder itself. We must add a copy of the OCSP responder certificate to the key database of the client or queue manager that performs the OCSP checking. see Adding a CA certificate, or the public part of a self-signed certificate, into a key repository on UNIX, Linux, and Windows. When a CA certificate is added, by default it is added as a trusted root, which is the required setting in this context. If this certificate is not added, IBM MQ cannot verify the digital signature on the OCSP response and the OCSP check results in an Unknown outcome, which might cause IBM MQ to close the channel, depending on the value of OCSPAuthentication.

Online Certificate Status Protocol (OCSP) in Java and JMS client applications
Due to a limitation of the Java API, IBM MQ can use Online Certificate Status Protocol (OCSP) certificate revocation checking for TLS secure sockets only when OCSP is enabled for the entire Java virtual machine (JVM) process. There are two ways to enable OCSP for all secure sockets in the JVM:

Edit the JRE java.security file to include the OCSP configuration settings that are shown in Table 1 and restart the application.
Use the java.security.Security.setProperty() API, subject to any Java Security Manager policy in effect.

As a minimum, we must specify one of the ocsp.enable and ocsp.responderURL values.

Property Name Description

ocsp.enable This property's value is either true or false. If true, OCSP checking is enabled when doing certificate revocation checking; if false or not set, OCSP checking is disabled.

ocsp.responderURL This property's value is a URL that identifies the location of the OCSP responder. Here is an example; ocsp.responderURL=http://ocsp.example.net:80. By default, the location of the OCSP responder is determined implicitly from the certificate that is being validated. The property is used when the Authority Information Access extension (defined in RFC 3280) is absent from the certificate or when it requires overriding.

ocsp.responderCertSubjectName This property's value is the subject name of the OCSP responder's certificate. Here is an example; ocsp.responderCertSubjectName=CN=OCSP Responder, O=XYZ Corp. By default, the certificate of the OCSP responder is that of the issuer of the certificate that is being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string distinguished name (defined in RFC 2253) which identifies a certificate in the set of certificates that are supplied during cert path validation. In cases where the subject name alone is not sufficient to uniquely identify the certificate, then both the ocsp.responderCertIssuerName and ocsp.responderCertSerialNumber properties must be used instead. When this property is set, then the properties ocsp.responderCertIssuerName and ocsp.responderCertSerialNumber are ignored.

ocsp.responderCertIssuerName This property's value is the issuer name of the OCSP responder's certificate. Here is an example; ocsp.responderCertIssuerName=CN=Enterprise CA, O=XYZ Corp. By default, the certificate of the OCSP responder is that of the issuer of the certificate that is being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string distinguished name (defined in RFC 2253) which identifies a certificate in the set of certificates that are supplied during cert path validation. When this property is set then the ocsp.responderCertSerialNumber property must also be set. This property is ignored when the ocsp.responderCertSubjectName property is set.

ocsp.responderCertSerialNumber This property's value is the serial number of the OCSP responder's certificate. Here is an example; ocsp.responderCertSerialNumber=2A:FF:00. By default, the certificate of the OCSP responder is that of the issuer of the certificate that is being validated. This property identifies the certificate of the OCSP responder when the default does not apply. This value is a string of hexadecimal digits (colon or space separators might be present) which identifies a certificate in the set of certificates that are supplied during cert path validation. When this property is set then the ocsp.responderCertIssuerName property must also be set. This property is ignored when the ocsp.responderCertSubjectName property is set.

Before you enable OCSP in this way, there are a number of considerations:

Set the OCSP configuration affects all secure sockets in the JVM process. In some cases this configuration might have undesirable side-effects when the JVM is shared with other application code that uses TLS secure sockets. Ensure that the chosen OCSP configuration is suitable for all of the applications that are running in the same JVM.
Applying maintenance to your JRE might overwrite the java.security file. Take care when you apply Java interim fixes and product maintenance to avoid overwriting the java.security file. It might be necessary to reapply your java.security changes after you apply maintenance. For this reason, you might consider setting the OCSP configuration by using the java.security.Security.setProperty() API instead.
Enable OCSP checking has an effect only if revocation checking is also enabled. Revocation checking is enabled by the PKIXParameters.setRevocationEnabled() method.
If we are using the AMS Java Interceptor described in Enable OCSP checking in native interceptors, take care to avoid using a java.security OCSP configuration that conflicts with the AMS OCSP configuration in the keystore configuration file.

Parent topic: Work with revoked certificates

Last updated: 2020-10-04


Property Name	Description
ocsp.enable	This property's value is either true or false. If true, OCSP checking is enabled when doing certificate revocation checking; if false or not set, OCSP checking is disabled.
ocsp.responderURL	This property's value is a URL that identifies the location of the OCSP responder. Here is an example; ocsp.responderURL=http://ocsp.example.net:80. By default, the location of the OCSP responder is determined implicitly from the certificate that is being validated. The property is used when the Authority Information Access extension (defined in RFC 3280) is absent from the certificate or when it requires overriding.
ocsp.responderCertSubjectName	This property's value is the subject name of the OCSP responder's certificate. Here is an example; ocsp.responderCertSubjectName=CN=OCSP Responder, O=XYZ Corp. By default, the certificate of the OCSP responder is that of the issuer of the certificate that is being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string distinguished name (defined in RFC 2253) which identifies a certificate in the set of certificates that are supplied during cert path validation. In cases where the subject name alone is not sufficient to uniquely identify the certificate, then both the ocsp.responderCertIssuerName and ocsp.responderCertSerialNumber properties must be used instead. When this property is set, then the properties ocsp.responderCertIssuerName and ocsp.responderCertSerialNumber are ignored.
ocsp.responderCertIssuerName	This property's value is the issuer name of the OCSP responder's certificate. Here is an example; ocsp.responderCertIssuerName=CN=Enterprise CA, O=XYZ Corp. By default, the certificate of the OCSP responder is that of the issuer of the certificate that is being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string distinguished name (defined in RFC 2253) which identifies a certificate in the set of certificates that are supplied during cert path validation. When this property is set then the ocsp.responderCertSerialNumber property must also be set. This property is ignored when the ocsp.responderCertSubjectName property is set.
ocsp.responderCertSerialNumber	This property's value is the serial number of the OCSP responder's certificate. Here is an example; ocsp.responderCertSerialNumber=2A:FF:00. By default, the certificate of the OCSP responder is that of the issuer of the certificate that is being validated. This property identifies the certificate of the OCSP responder when the default does not apply. This value is a string of hexadecimal digits (colon or space separators might be present) which identifies a certificate in the set of certificates that are supplied during cert path validation. When this property is set then the ocsp.responderCertIssuerName property must also be set. This property is ignored when the ocsp.responderCertSubjectName property is set.