Troubleshooting the Transport Layer Security Configuration

Common errors may occur while you use the Oracle Database Transport Layer Security.

A utility is available through My Oracle Support to review and provide feedback on your TLS client and server configuration. See DBSecChk Utility 2.0.0.5 (Doc ID 3066006.1).

It may be necessary to enable Oracle Net tracing to determine the cause of an error. For information about setting tracing parameters to enable Oracle Net tracing, refer to Tracing Error Information for Oracle Net Services in the Oracle AI Database Net Services Administrator’s Guide.

ORA-28759: Failure to Open File

Cause: The system could not open the specified file. Typically, this error occurs because the wallet cannot be found.

Action: Check the following:

Ensure that the correct wallet location is specified in the sqlnet.ora file. This should be the same directory location where you saved the wallet.
Enable Oracle Net tracing to determine the name of the file that cannot be opened and the reason.
Ensure that auto-login was enabled when you saved the wallet, using orapki or mkstore. The mkstore wallet management command line tool is deprecated with Oracle AI Database 26ai, and can be removed in a future release.

ORA-28786: Decryption of Encrypted Private Key Failure

Cause: An incorrect password was used to decrypt an encrypted private key. Frequently, this happens because an auto-login wallet is not being used.

Action: Use orapki to turn the auto-login feature on for the wallet. Then save the wallet again. For example:

orapki wallet create -wallet wallet_file_location -auto_login

If the auto-login feature is not being used, then enter the correct password.

ORA-28858: SSL Protocol Error

Cause: This is a generic error that can occur during TLS handshake negotiation between two processes.

Action: Enable Oracle Net tracing and attempt the connection again to produce trace output. Then contact Oracle customer support with the trace output.

ORA-28859 SSL Negotiation Failure

Cause: An error occurred during the negotiation between two processes as part of the TLS protocol. This error can occur when two sides of the connection do not support a common cipher suite.

Action: Check the following:

Check the sqlnet.ora file to ensure that the TLS versions on both the client and the server match, or are compatible. For example, if the server accepts only TLS 1.3 and the client accepts only TLS 1.2, then the TLS connection will fail.
Check what cipher suites are configured on the client and the server, and ensure that compatible cipher suites are set on both.

If the error still persists, then enable tracing and attempt the connection again. Contact Oracle Support with the trace output.

See Also: Specifying TLS Protocol and TLS Cipher Suites for details about setting compatible cipher suites on the client and the server

Note: If you do not configure any cipher suites, then all available cipher suites are enabled.

ORA-28862: SSL Connection Failed

Cause: This error occurred because the peer closed the connection.

Action: Check the following:

Ensure that the correct wallet location is specified in the sqlnet.ora file so the system can find the wallet.
Ensure that cipher suites are set correctly in the sqlnet.ora file. Sometimes this error occurs because the sqlnet.ora has been manually edited and the cipher suite names are misspelled. Ensure that case sensitive string matching is used with cipher suite names.
Ensure that the TLS versions on both the client and the server match or are compatible. Sometimes this error occurs because the TLS version specified on the server and client do not match. For example, if the server accepts only TLS 1.3 and the client accepts only TLS 1.2, then the TLS connection will fail.
For more diagnostic information, enable Oracle Net tracing on the peer.

ORA-28865: SSL Connection Closed

Cause: The TLS connection closed because of an error in the underlying transport layer, or because the peer process quit unexpectedly.

Action: Check the following:

Ensure that the TLS versions on both the client and the server match, or are compatible. Sometimes this error occurs because the TLS version specified on the server and client do not match. For example, if the server accepts only TLS 1.3 and the client accepts only TLS 1.2, then the TLS connection will fail.
Enable Oracle Net tracing and check the trace output for network errors.

ORA-28868: Peer Certificate Chain Check Failed

Cause: When the peer presented the certificate chain, it was checked and that check failed. This failure can be caused by a number of problems, including:

One of the certificates in the chain has expired.
A certificate authority for one of the certificates in the chain is not recognized as a trust point.
The signature in one of the certificates cannot be verified.

Action: Open your wallet and check the following:

Ensure that all of the certificates installed in your wallet are current (not expired).
Ensure that a certificate authority’s certificate from your peer’s certificate chain is added as a trusted certificate in your wallet.

ORA-28885: No certificate with the required key usage found.

Cause: Your certificate was not created with the appropriate X.509 version 3 key usage extension.

Action: Create the certificate with the appropriate X.509 version 3 key usage extension. For example:

orapki wallet add -wallet user_wallet -asym_alg ECC -eccurve p384 -sign_alg ecdsasha384 -dn 'cn=user_ecc,c=us' -pwd welcome1 -addext_ku digitalSignature

You may add more key usages than just digitalSignature, for example:

-addext_ku digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment,keyAgreement,keyCertSign,cRLSign,encipherOnly,decipherOnly

ORA-29019: The Protocol Version is incorrect

Cause: There is a protocol version mismatch between the two peers.

Action: Specify the correct protocol version or unset TLS_VERSION in the product’s configuration file.

The error code is shown in the trace: [DATE_AND_TIME] ntzdosecneg: SSL handshake failed with error 29019.

ORA-29024: Certificate Validation Failure

Cause: The certificate sent by the other side could not be validated. This may occur if the certificate has expired, has been revoked, or is invalid for any other reason.

Action: Check the following:

Check the certificate to determine whether it is valid. If necessary, get a new certificate, inform the sender that their certificate has failed, or resend.
Check to ensure that the server’s wallet has the appropriate trust points to validate the client’s certificate. If it does not, then use orapki to import the appropriate trust point into the wallet.
Ensure that the certificate has not been revoked and that certificate revocation list (CRL) checking is turned on. For details, refer toConfiguring Certificate Validation with Certificate Revocation Lists

ORA-29223: Cannot Create Certificate Chain

Cause: A certificate chain cannot be created with the existing trust points for the certificate being installed. Typically, this error is returned when the peer does not give the complete chain and you do not have the appropriate trust points to complete it.

Action: Use orapki to install the trust points that are required to complete the chain.

Migrating to and Configuring Transport Layer Security Version 1.3

Version 1.3 of Transport Layer Security (TLS) provides stronger security and faster TLS handshakes, when compared to previous versions of TLS.

Starting with Oracle AI Database 26ai, Oracle Database supports TLS version 1.3 and its newer, more secure cipher suites, which improve the confidentiality of data in transit. Oracle recommends that you move from the desupported TLS versions 1.0 and 1.1 to TLS version 1.3. TLS version 1.2 remains supported.

TLS version 1.3 is supported and enabled by default with 26ai when both the database server and client are version 26ai.

If your environment does not specify the TLS_VERSION parameter in the configuration files, then TLS version 1.3 is enabled by default. If the TLS_CIPHER_SUITES parameter is not explicitly configured, TLS 1.3 cipher suites get automatically picked. The product is designed to pick the strongest TLS version and the strongest available cipher in that version.

The enhancements in Transport Layer Security (TLS) version 1.3 may affect current TLS configurations if one or both of the following parameters are specified.

TLS_VERSION: Remove this parameter from the configuration files to enable all supported TLS versions, or include the string “TLSv1.3” in the value specified

For example,
```
TLS_VERSION = (TLSv1.3, TLSv1.2)
```
TLS_CIPHER_SUITES: Remove this parameter from the configuration files to enable all supported TLS cipher suites, or include one or more of the TLS version 1.3 cipher suites

For example,
```
TLS_CIPHER_SUITES = (TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256, TLS_AES_128_CCM_SHA256)
```

Note: To bring Oracle parameters in accord with the actual encryption and authentication methods for network connections, Oracle is deprecating all connect parameters prefixed with SSL_ in favor of parameters prefixed with TLS_. During this deprecation period, if both the TLS_ and SSL_ versions of a parameter are configured, then the SSL_ version is ignored.

Related Topics