SSL/TLS error messages

SSL/TLS error messages

Handshake failures are logged in the MQIPT connection log in the form of JSSE exceptions. See Connection logs. The following table describes the different exceptions, the likely cause and the corresponding action to resolve the failure.

Certificate exceptions usually relate to the certificates at the remote end of the connection.

Where the error relates to the certificate of a IBM MQ client or queue manager, the term key ring file includes the IBM MQ key repository of the remote partner.

In MQIPT, CA certificates are stored in the CA key ring file, which is identified by the SSLClientCAKeyRing and SSLServerCAKeyRing route properties. If the CA key ring route properties are not set, the corresponding personal key ring file (referenced by either the SSLClientKeyRing or SSLServerKeyRing property) is searched for CA certificates instead.

Exception Cause Action

CertificateException The certificate is not trusted because it is signed by a CA that is not in the CA key ring. Check that all of the necessary CA certificates are present in the CA key ring file. Use the IBM Key Management tool supplied with MQIPT to add any missing CA certificates, taking care to obtain a copy of each CA certificate from a trustworthy source.

CertificateExpiredException

The certificate has expired: its notAfter date has passed.
The system clock is set incorrectly.

Obtain a new certificate and insert it into the key ring file. If the certificate belongs to a Certificate Authority, place the new certificate into the CA key ring file.
Check that the UTC system clock is set to the correct time.

CertificateNotYetValidException

The certificate is being used prematurely: its notBefore date has not yet arrived.
The system clock is set incorrectly.

Check that the certificate has been generated and signed correctly. If your organization operates its own CA, the UTC system clock for the CA might be incorrect.
Check that the UTC system clock is set to the correct time.

CertificateParsingException

The certificate contains invalid DER data.
The certificate uses unsupported DER features.

Ensure the certificate has been correctly generated and can be viewed in the IBM Key Management tool supplied with MQIPT. Consider obtaining a new certificate with fewer certificate extensions.

CertificateRevokedException Certificate revocation checking is enabled and the certificate was found to be revoked. The certificate in question should not be trusted. Obtain a replacement certificate and ensure the new certificate and its private key are present in the key ring file.

CertPathBuilderException The certificate chain was not signed by a recognized Certificate Authority.

If we are using CA-signed certificates, check that all root CA and intermediate CA certificates are present in the CA key ring file.
If we are using self-signed certificates, ensure that we have extracted a copy of the public part of the remote certificate and added it to the CA key ring file. Avoid using self-signed certificates in production environments.

CertStoreException
KeyStoreException An error occurred reading a certificate from a key ring for one of the following reasons:

The key ring file is damaged.
The key ring file is missing.
The stored password does not match the key ring file password.
If the route is configured to use cryptographic hardware, MQIPT could not connect to the cryptographic hardware.

Ensure that the key ring file can be read and that all certificates can be viewed with the IBM Key Management tool.
Check that all key ring route properties refer to the correct file name.
Check that the stored key ring file password is correct. Use the mqiptPW tool to store the correct password.
If the route is configure to use cryptographic hardware, check the following:

The Java security properties file specifies that the IBMPKCS11Impl security provider is installed.
The Java security properties file contains the fully-qualified name of the configuration file that is used to initialize the IBMPKCS11Impl security provider.
The configuration file that is used to initialize the IBMPKCS11Impl security provider is valid.

SSLException: No available certificate or key corresponds to the SSL cipher suites which are enabled. We must have a personal certificate with the correct type of key for the CipherSuites we are using. For example, CipherSuites whose names begin with SSL_ECDH_ECDSA_ require a certificate with an Elliptic Curve public key. The most commonly used CipherSuites require a certificate with an RSA public key. Open the key ring file with the IBM Key Management tool. Under the Personal Certificates view, select each certificate in turn and view it. Click View Details and navigate to the Subject Public Key section to see the public key type. Then check the MQIPT SSLClientCipherSuites and SSLServerCipherSuites route properties to ensure that the appropriate CipherSuites are enabled.

SSLException: No cipher suites in common
SSLHandshakeException: No cipher suites in common The handshake has failed to agree a CipherSuite because there is no overlap between the sets of enabled CipherSuites at both ends of the connection. In particular, an outbound IBM MQ connection only enables a single cipher so SSLServer MQIPT routes are particularly likely to experience this error.This error can also occur when all three of the following conditions are true:

no CipherSuite is specified on the route
no suitable site certificate can be found in the key ring configured for the route
anonymous CipherSuites are disabled

Check the list of enabled CipherSuites in the MQIPT SSLClientCipherSuites and SSLServerCipherSuites route properties. Consider enabling additional CipherSuites. Consult the table provided to determine the correct CipherSuites to enable for each IBM MQ channel CipherSpec value.
If no CipherSuite is specified on the route, check that key ring route properties refer to the correct key ring file, and that the key ring contains a personal certificate that MQIPT can use. If the route is configured to use cryptographic hardware, check that the tokenlabel attribute in the configuration file that is used to initialize the IBMPKCS11Impl security provider specifies the correct cryptographic device token label.

Parent topic: SSL/TLS support

Last updated: 2020-10-04

Exception	Cause	Action
CertificateException	The certificate is not trusted because it is signed by a CA that is not in the CA key ring.	Check that all of the necessary CA certificates are present in the CA key ring file. Use the IBM Key Management tool supplied with MQIPT to add any missing CA certificates, taking care to obtain a copy of each CA certificate from a trustworthy source.
CertificateExpiredException	The certificate has expired: its notAfter date has passed. The system clock is set incorrectly.	Obtain a new certificate and insert it into the key ring file. If the certificate belongs to a Certificate Authority, place the new certificate into the CA key ring file. Check that the UTC system clock is set to the correct time.
CertificateNotYetValidException	The certificate is being used prematurely: its notBefore date has not yet arrived. The system clock is set incorrectly.	Check that the certificate has been generated and signed correctly. If your organization operates its own CA, the UTC system clock for the CA might be incorrect. Check that the UTC system clock is set to the correct time.
CertificateParsingException	The certificate contains invalid DER data. The certificate uses unsupported DER features.	Ensure the certificate has been correctly generated and can be viewed in the IBM Key Management tool supplied with MQIPT. Consider obtaining a new certificate with fewer certificate extensions.
CertificateRevokedException	Certificate revocation checking is enabled and the certificate was found to be revoked.	The certificate in question should not be trusted. Obtain a replacement certificate and ensure the new certificate and its private key are present in the key ring file.
CertPathBuilderException	The certificate chain was not signed by a recognized Certificate Authority.	If we are using CA-signed certificates, check that all root CA and intermediate CA certificates are present in the CA key ring file. If we are using self-signed certificates, ensure that we have extracted a copy of the public part of the remote certificate and added it to the CA key ring file. Avoid using self-signed certificates in production environments.
CertStoreException KeyStoreException	An error occurred reading a certificate from a key ring for one of the following reasons: The key ring file is damaged. The key ring file is missing. The stored password does not match the key ring file password. If the route is configured to use cryptographic hardware, MQIPT could not connect to the cryptographic hardware.	Ensure that the key ring file can be read and that all certificates can be viewed with the IBM Key Management tool. Check that all key ring route properties refer to the correct file name. Check that the stored key ring file password is correct. Use the mqiptPW tool to store the correct password. If the route is configure to use cryptographic hardware, check the following: The Java security properties file specifies that the IBMPKCS11Impl security provider is installed. The Java security properties file contains the fully-qualified name of the configuration file that is used to initialize the IBMPKCS11Impl security provider. The configuration file that is used to initialize the IBMPKCS11Impl security provider is valid.
SSLException: No available certificate or key corresponds to the SSL cipher suites which are enabled.	We must have a personal certificate with the correct type of key for the CipherSuites we are using. For example, CipherSuites whose names begin with SSL_ECDH_ECDSA_ require a certificate with an Elliptic Curve public key. The most commonly used CipherSuites require a certificate with an RSA public key.	Open the key ring file with the IBM Key Management tool. Under the Personal Certificates view, select each certificate in turn and view it. Click View Details and navigate to the Subject Public Key section to see the public key type. Then check the MQIPT SSLClientCipherSuites and SSLServerCipherSuites route properties to ensure that the appropriate CipherSuites are enabled.
SSLException: No cipher suites in common SSLHandshakeException: No cipher suites in common	The handshake has failed to agree a CipherSuite because there is no overlap between the sets of enabled CipherSuites at both ends of the connection. In particular, an outbound IBM MQ connection only enables a single cipher so SSLServer MQIPT routes are particularly likely to experience this error.This error can also occur when all three of the following conditions are true: no CipherSuite is specified on the route no suitable site certificate can be found in the key ring configured for the route anonymous CipherSuites are disabled	Check the list of enabled CipherSuites in the MQIPT SSLClientCipherSuites and SSLServerCipherSuites route properties. Consider enabling additional CipherSuites. Consult the table provided to determine the correct CipherSuites to enable for each IBM MQ channel CipherSpec value. If no CipherSuite is specified on the route, check that key ring route properties refer to the correct key ring file, and that the key ring contains a personal certificate that MQIPT can use. If the route is configured to use cryptographic hardware, check that the tokenlabel attribute in the configuration file that is used to initialize the IBMPKCS11Impl security provider specifies the correct cryptographic device token label.