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.
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.
- 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
- 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.
- 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 theALLOW_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:
- Ensure that the expected certificate chain is being returned by the
server. This can be achieved outside of Db2 using a tool like
OpenSSL:
If the expected certificate is not being returned, the configuration on the peer must be corrected.openssl s_client -connect <hostname>:<port> -showcerts
- 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:
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 -label <certificate label> -db /path/to/cert.p12 -stashed
gsk8capicmd_64 -cert -details -file /path/to/cert.pem openssl x509 -in /path/to/cert.pem -noout -text
- Ensure that the expected certificate chain is being returned by the
server. This can be achieved outside of Db2 using a tool like
OpenSSL:
GSKit 415: GSK_ERROR_BAD_PEER and GSKit 420: GSK_ERROR_SOCKET_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
- 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.
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.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