Common GSKit errors

Db2® relies on the IBM® Global Security Kit (GSKit) product to process its cryptographic requests for Transport Layer Security (TLS) and native encryption. If the GSKit encounters an error, a message token is returned by Db2 in the SQLCA, along with an appropriate SQLCODE, to report the error.

These tokens can take the form of GSKit Error: XXX (where 'XXX' is a number representing the GSKIT return code) or, if the tokens are being returned with SQL1782N and reason code 5, they can be concatenated with the reason code message token in the SQLCA in the form of 5:XXX.

To see the General, and Key Management return codes for the GSKit, see GSKit return codes.

The following information provides some details on how to address some common GSKit errors that can arise with TLS and native encryption.
Note: Not all possible scenarios are represented in the following examples, only the ones most frequently encountered.

GSKit 401: GSK_ERROR_BAD_DATE

This return code indicates that the certificate specified by the SSL_SVR_LABEL database manager configuration parameter or the SSL_KMIP_CLIENT_CERTIFICATE_LABEL keystore configuration parameter is not yet valid, or is expired based on the current system date. To resolve the 401 error, first ensure the system date is correct. If the system date is accurate, the certificate must be renewed if it is CA-signed or recreated if it is self-signed.

GSKit 402: GSK_ERROR_NO_CIPHERS

This return code indicates that the client and server could not negotiate a common TLS version or cipher. To resolve this issue, ensure the server enables the TLS version and ciphers supported by the client. In a Db2 server, this can be done by adjusting the SSL_VERSIONS and SSL_CIPHERSPECS database manager configuration parameters. In a Db2 client, or for the KMIP configuration of Db2, this can be done with the TLSVersion keyword in the configuration file.

GSKit 407: GSK_ERROR_BAD_KEYFILE_LABEL

This return code indicates that the specified label cannot be found. The most common cause of this error is an incorrect value in either the SSL_SVR_LABEL database manager configuration parameter or the SSL_KMIP_CLIENT_CERTIFICATE_LABEL keystore configuration parameter. This problem can be caused by a misspelling or by placing quotation marks around the label value. Another possible cause is that the label represents a certificate without a private key that is required by Db2.

GSKit 408: GSK_ERROR_BAD_KEYFILE_PASSWORD

This return code indicates that the key file cannot be used because the specified key file password is incorrect. The key file might also be corrupted.

This error can be returned in these scenarios:
  • The password to access the key file is incorrect.
  • Db2 does not have the correct permissions to access the password stash file, if a password stash file is being used.
  • The password stash file was created with an incompatible version of GSKit.
    Note: GSKit version 8.0.50.69 (and higher) generates a password stash file that older versions of GSKit cannot read. If you believe that this scenario might apply, try recreating the stash file with the current GSKit version.

GSKit 410: GSK_ERROR_BAD_MESSAGE

This return code indicates that an incorrectly formatted TLS message was received from the partner in an TLS relationship. This error can be returned in the following scenarios:
  • A Db2 client or a server attempting to access a keystore does not have the correct firewall access.
  • A Db2 client with TLS enabled is attempting to connect to a server on a port that does not have TLS enabled.
  • A Db2 client that does not have TLS enabled is attempting to connect to a server on a port that has TLS enabled.

GSKit 414: GSK_ERROR_BAD_CERT

This return code indicates that an incorrectly formatted certificate was received from the partner in an TLS relationship.

This error can be returned in the following scenarios:
  • You are using self-signed certificates and the certificate is missing.
  • The certificate that is being used is from a local certificate authority that does not have the Basic Constraints extension active.
    Note: You can use the ALLOW_NONCRITICAL_BASIC_CONSTRAINT keystore configuration parameter to bypass this problem.
  • You are using CA-signed certificates, and the CA root certificate is missing.
  • The client does not support Server Name Indication (SNI), and the server environment requires SNI to route TLS connections to the correct endpoint. Upgrade the client to Db2 11.5.7 or later if the server relies on SNI.
  • One of the certificates in the chain is expired.
Resolving a GSKit 414 error
You can resolve a 414 error by addressing the following items:
  1. Ensure that the expected certificate chain is being returned by the server. This can be achieved outside of Db2 using a tool like OpenSSL:
    openssl s_client -connect <hostname>:<port> -showcerts
    If the expected certificate is not being returned, the configuration on the peer must be corrected.
  2. Ensure that the client has the correct certificate to validate the certificate chain returned from step 1. The certificate in use on the client must be valid (not expired), and the subject and issuer must be the same. If the server uses a self-signed certificate, the certificate in use on the client must match the certificate returned by the server. If the server uses a CA-signed certificate, contact the CA to determine which certificate to use.
    If the certificate on the client is contained within a key database, use GSKit to inspect the certificate details: 
    gsk8capicmd_64 -cert -details -label <certificate label> -db /path/to/cert.p12 -stashed
    If the client is using a bare certificate file, use either GSKit or OS tools like OpenSSL to inspect the certificate:
    gsk8capicmd_64 -cert -details -file /path/to/cert.pem openssl x509 -in /path/to/cert.pem -noout -text

GSKit 415: GSK_ERROR_BAD_PEER and GSKit 420: GSK_ERROR_SOCKET_CLOSED

These return codes indicate that the TLS peer closed the connection. Inspect the diagnostic log on the peer to determine why the connection was closed.
  • If a Db2 client returns this error code, inspect the diagnostic log on the server.
  • If a Db2 server returns this error code, inspect the diagnostic log on the client.

GSKit 446: GSK_ERROR_OTHER_FATAL_ALERT

This return code indicates that the TLS peer closed the connection and set an unexpected fatal alert. The peer must be investigated to determine the error that resulted in the fatal alert.
  • If a Db2 client returns this error code, inspect the diagnostic log on the server.
  • If a Db2 server returns this error code, inspect the diagnostic log on the client.
Note: If TLS 1.3 is enabled and Java clients are in use, erroneous 446 errors are written to the diagnostic log when connections are closed. This issue is addressed in Db2 11.5.9 and later in the known issue DT236921.

Db2 clients and servers with known issue DT236921, write the alert number in addition to the 446 error code in the format 446:<alert number>.

Examples

The following example shows output from running the OpenSSL command for the host server 127.0.0.1 on port 25001, when resolving a 414 error. See step 1:
openssl s_client -connect 127.0.0.1:25001
CONNECTED(00000003)
depth=0 CN = test
verify error:num=18:self signed certificate
verify return:1
depth=0 CN = test
verify return:1
---
Certificate chain
 0 s:/CN=test
   i:/CN=test
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIC4jCCAcqgAwIBAgIIWj6sV07x6hAwDQYJKoZIhvcNAQELBQAwDzENMAsGA1UE
...
d8VGLAD8JA71mZ8Rhos2I5cYRkQ+ug==
-----END CERTIFICATE-----
subject=/CN=test
issuer=/CN=test
---
The following example shows the certificate details returned from running the OpenSSL command when resolving a 414 error. See step 2:
openssl x509 -in test.pem -noout -text
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN=zen-ca-certificate
        Validity
            Not Before: Jan 1 12:00:00 2022 GMT
            Not After : Jan 1 12:00:00 2024 GMT
        Subject: CN=zen-ca-certificate
The following example shows the certificate details returned from running the GSKit command when resolving a 414 error. See step 2:
gsk8capicmd_64 -cert -details -file test.pem
Label : CN=zen-ca-certificate
Key Size : 2048
Version : X509 V3
Serial : ffffffffffffffffffffffffffffffff
Issuer : CN=zen-ca-certificate
Subject : CN=zen-ca-certificate
Not Before : January 1, 2022 12:00:00 AM GMT

Not After : January 1, 2024 12:00:00 AM GMT
The Not After date indicates when the certificate expires. The Issuer and Subject are also shown. The Serial number can be used to verify if the correct certificate is present on both the client and server.

The following example shows the error code followed by the alert number in the format 446:<alert number> for GSKit 446:
2023-08-16-06.03.32.703632-420 I2279E596            LEVEL: Error
PID    : 7907                TID : 140002944083712 PROC : db2sysc 0
INSTANCE: db2inst             NODE : 000           DB  : SAMPLE
APPHDL : 0-26                APPID: 127.0.0.1.58592.230816130339
AUTHID : SAMPLE              HOSTNAME: sample.ibm.com
EDUID  : 21                  EDUNAME: db2agent (SAMPLE) 0
FUNCTION: DB2 UDB, common communication, sqlccMapSSLErrorToDB2Error, probe:30
MESSAGE : DIA3604E The SSL function "gsk_secure_soc_init" failed with the
        return code "446:46" in "sqlccSSLSocketSetup".
DATA #1 : String, 27 bytes
GSK_ERROR_OTHER_FATAL_ALERT
DATA #2 : String, 23 bytes
Peer sent a fatal alert
Note: A list of alert numbers and descriptions can be found in RFC 8446. It is a specification document managed by Internet Engineering Task Force (IETF) for version 1.3 of the TLS protocol.