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 keyring file includes the IBM MQ key repository of the remote partner.

In MQIPT, CA certificates are stored in the CA keyring file, which is identified by the SSLClientCAKeyRing and SSLServerCAKeyRing route properties. If the CA keyring route properties are not set, the corresponding personal keyring file (SSLClientKeyRing or SSLServerKeyRing) 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 keyring. Check that all of the necessary CA certificates are present in the CA keyring 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 keyring file. If the certificate belongs to a Certificate Authority, place the new certificate into the CA keyring 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 keyring file.

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

If you are using CA-signed certificates, check that all root CA and intermediate CA certificates are present in the CA keyring file.
If you 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 keyring file. Avoid using self-signed certificates in production environments.

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

The keyring file is damaged.
The keyring file is missing.
The stored password does not match the keyring file password.

Ensure that the keyring file can be read and that all certificates can be viewed with the IBM Key Management tool.
Check that all keyring route properties refer to the correct file name.
Check that the stored keyring file password is correct. Use the mqiptPW tool to store the correct password.

SSLException: No available certificate or key corresponds to the SSL cipher suites which are enabled. You must have a personal certificate with the correct type of key for the CipherSuites you 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 keyring 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. 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. 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.

Parent topic: SSL/TLS support

Exception	Cause	Action
CertificateException	The certificate is not trusted because it is signed by a CA that is not in the CA keyring.	Check that all of the necessary CA certificates are present in the CA keyring 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 keyring file. If the certificate belongs to a Certificate Authority, place the new certificate into the CA keyring 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 keyring file.
CertPathBuilderException	The certificate chain was not signed by a recognised Certificate Authority.	If you are using CA-signed certificates, check that all root CA and intermediate CA certificates are present in the CA keyring file. If you 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 keyring file. Avoid using self-signed certificates in production environments.
CertStoreException KeyStoreException	An error occurred reading a certificate from a keyring for one of the following reasons: The keyring file is damaged. The keyring file is missing. The stored password does not match the keyring file password.	Ensure that the keyring file can be read and that all certificates can be viewed with the IBM Key Management tool. Check that all keyring route properties refer to the correct file name. Check that the stored keyring file password is correct. Use the mqiptPW tool to store the correct password.
SSLException: No available certificate or key corresponds to the SSL cipher suites which are enabled.	You must have a personal certificate with the correct type of key for the CipherSuites you 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 keyring 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.	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.	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.