21 Configuring Transport Layer Security Encryption

Transport Layer Security (TLS), previously called Secure Sockets Layer (SSL) facilitates the encryption of data across the internet between Web applications and servers.

21.1 Migrating to Transport Layer Security Version 1.3

Version 1.3 of Transport Layer Security (TLS) provides much strong security than previous versions, but you must perform specific tasks to ensure that your environment is correctly using this TLS version.

21.1.1 Configuration File Changes Required to Support Transport Layer Security Version 1.3

The enhancements in Transport Layer Security (TLS) version 1.3 affect current TLS configurations.

The following TLS 1.2 features are not available in TLS 1.3. This topic provides how to address TLS configurations that will be affected by the removal of these features.

  • Static RSA handshake for key exchanges has been desupported. However, the digital signatures use case continues to be supported in TLS 1.3.

    To address this change: In the configuration files, leave the references to the TLS cipher suites blank, which allows for auto-detection to set them to the latest version. Alternatively, you can explicitly call out TLS1.3 cipher suites in the configuration files using the SSL_CIPHER_SUITES parameter. CBC mode ciphers are desupported.

  • CBC mode ciphers have been desupported starting in Oracle Database 23ai.

    To address this change: Remove CBC mode ciphers from the configuration files.

  • The following cipher suites are no longer supported: AES-CBC, RC4, SHA1, MD5, DES, 3DES.

    To address this change: Remove references to these cipher suites from your configuration files.

21.1.2 Addressing the New Capabilities of Transport Layer Security Version 1.3

Transport Layer Security (TLS) version 1.3 provides valuable improvements over previous versions of TLS.

  • Perfect Forward Secrecy (PFS) is supported by default in TLS 1.3. To enable PFS in TLS 1.2, discontinue the use of RSA key exchange and switch to Ephemeral Elliptic-curve Diffie–Hellman ciphers in TLS 1.2.

    To address this change: In the configuration files, leave the references to the TLS cipher suites blank, which allows for auto-detection to set them to the latest version. Alternatively, you can explicitly call out TLS1.3 cipher suites in the configuration files using the SSL_CIPHER_SUITES parameter. CBC mode ciphers are desupported.

  • Faster TLS handshakes, stronger cipher suites.

    To address this change: No changes need to be made, given the implicit benefits when adopting TLS 1.3.

21.2 Transport Layer Security and Secure Sockets Layer

Transport Layer Security (TLS) is a cryptographic protocol used to secure computer networks.

21.2.1 The Difference Between Transport Layer Security and Secure Sockets Layer

The Transport Layer Security (TLS) cryptographic protocol was built on top of the older Secure Sockets Layer (SSL) protocol.

Although SSL was primarily developed by Netscape Communications Corporation, the Internet Engineering Task Force (IETF) took over development of it, and renamed it Transport Layer Security (TLS). TLS is an IETF standard.

Oracle Database Security Guide uses the terms Transport Layer Security and TLS instead of Secure Sockets Layer and SSL since the Oracle Database has implemented TLS. However, other documentation in the Oracle Database library may still use the earlier terms Secure Socket Layer and SSL. Where distinctions occur between how you use or configure these protocols, Oracle Database Security Guide specifies what is appropriate for either SSL or TLS.

The Oracle Database software still uses some of the older terminology. For example, the netmgr tool still uses the terms Secure Socket Layer and SSL. Many SSL parameters, such as SSL_SERVER_CERT_DN, use the older terminology. The names of cipher suites and the wording in error messages also use the SSL terminology. However, all these features work with and apply to Transport Layer Security.

21.2.2 Using Transport Layer Security in a Multitenant Environment

Transport Layer Security (TLS) can be used for application containers.

If you want to use Transport Layer Security (TLS) for an application container, then you must ensure that each PDB is able to use its own wallet with its own certificates for TLS authentication. (You can check the Oracle wallet search order for the alternative locations that are supported by the Oracle Database server.)
  • Place the PDB wallet in a subdirectory of the wallet root directory where the name of the subdirectory is the GUID of the PDB.
    For example:
    WALLET_ROOT/PDB_GUID/tls

21.3 How Transport Layer Security Works in an Oracle Environment: The TLS Handshake

When a network connection over Transport Layer Security is initiated, the client and server perform a TLS handshake before performing the authentication.

The handshake process is as follows:

  1. The client and server establish which cipher suites to use. This includes which encryption algorithms are used for data transfers.

  2. The server sends its certificate to the client, and the client verifies that the server's certificate was signed by a trusted CA. This step verifies the identity of the server.

  3. Similarly, if client authentication is required, the client sends its own certificate to the server, and the server verifies that the client's certificate was signed by a trusted CA.

  4. The client and server exchange key information using public key cryptography. Based on this information, each generates a session key. A key is shared by at least two parties (usually a client and a server) that is used for data encryption for the duration of a single communication session. Session keys are typically used to encrypt network traffic; a client and a server can negotiate a session key at the beginning of a session, and that key is used to encrypt all network traffic between the parties for that session. If the client and server communicate again in a new session, they negotiate a new session key. All subsequent communications between the client and the server is encrypted and decrypted by using this session key and the negotiated cipher suite.

The authentication process is as follows:

  1. On a client, the user initiates an Oracle Net connection to the server by using TLS.

  2. TLS performs the handshake between the client and the server.

  3. If the handshake is successful, then the server verifies that the user has the appropriate authorization to access the database.

21.4 Public Key Infrastructure in an Oracle Environment

A public key infrastructure (PKI) is a substrate of network components that provide a security underpinning, based on trust assertions, for an entire organization.

21.4.1 About Public Key Cryptography

Traditional private-key or symmetric-key cryptography requires a single, secret key shared by two or more parties to establish a secure communication.

This key is used to both encrypt and decrypt secure messages sent between the parties, requiring prior, secure distribution of the key to each party. The problem with this method is that it is difficult to securely transmit and store the key.

Public-key cryptography provides a solution to this problem, by employing public and private key pairs and a secure method for key distribution. The freely available public key is used to encrypt messages that can only be decrypted by the holder of the associated private key. The private key is securely stored, together with other security credentials, in an encrypted container called a wallet.

Public-key algorithms can guarantee the secrecy of a message, but they do not necessarily guarantee secure communications because they do not verify the identities of the communicating parties. To establish secure communications, it is important to verify that the public key used to encrypt a message does in fact belong to the target recipient. Otherwise, a third party can potentially eavesdrop on the communication and intercept public key requests, substituting its own public key for a legitimate key (the third-party attack).

In order to avoid such an attack, it is necessary to verify the owner of the public key, a process called authentication. Authentication can be accomplished through a certificate authority (CA), which is a third party that is trusted by both of the communicating parties.

The CA issues public key certificates that contain an entity's name, public key, and certain other security credentials. Such credentials typically include the CA name, the CA signature, and the certificate effective dates (From Date, To Date).

The CA uses its private key to encrypt a message, while the public key is used to decrypt it, thus verifying that the message was encrypted by the CA. The CA public key is well known and does not have to be authenticated each time it is accessed. Such CA public keys are stored in wallets.

21.4.2 Public Key Infrastructure Components in an Oracle Environment

Public key infrastructure (PKI) components in an Oracle environment include a certificate authority, certificates, certificate revocation lists, and wallets.

21.4.2.1 Certificate Authority

A certificate authority (CA) is a trusted third party that certifies the identity of entities, such as users, databases, administrators, clients, and servers.

When an entity requests certification, the CA verifies its identity and grants a certificate, which is signed with the CA's private key.

Different CAs may have different identification requirements when issuing certificates. Some CAs may verify a requester's identity with a driver's license, some may verify identity with the requester's fingerprints, while others may require that requesters have their certificate request form notarized.

The CA publishes its own certificate, which includes its public key. Each network entity has a list of trusted CA certificates. Before communicating, network entities exchange certificates and check that each other's certificate is signed by one of the CAs on their respective trusted CA certificate lists.

Network entities can obtain their certificates from the same or different CAs.

21.4.2.2 Certificates

A certificate is created when an entity's public key is signed by a trusted certificate authority (CA).

A certificate ensures that an entity's identification information is correct and that the public key actually belongs to that entity.

A certificate contains the entity's name, public key, and an expiration date, as well as a serial number and certificate chain information. (A certificate chain is an ordered list of certificates containing an end-user or subscriber certificate and its certificate authority certificate.) It can also contain information about the privileges associated with the certificate.

When a network entity receives a certificate, it verifies that it is a trusted certificate, that is, one that has been issued and signed by a trusted certificate authority. A certificate remains valid until it expires or until it is revoked.

21.4.2.3 Certificate Revocation Lists

When a CA signs a certificate binding a public key pair to a user identity, the certificate is valid for a specified time.

However, certain events, such as user name changes or compromised private keys, can render a certificate invalid before the validity period expires. When this happens, the CA revokes the certificate and adds its serial number to a Certificate Revocation List (CRL). The CA periodically publishes CRLs to alert the user population when it is no longer acceptable to use a particular public key to verify its associated user identity.

When servers or clients receive user certificates in an Oracle environment, they can validate the certificate by checking its expiration date, signature, and revocation status. Certificate revocation status is checked by validating it against published CRLs. If certificate revocation status checking is turned on, then the server searches for the appropriate CRL depending on how this feature has been configured. The server searches for CRLs in the following locations in this order:

  1. Local file system

  2. Oracle Internet Directory

  3. CRL Distribution Point (CRL DP), a location specified in the CRL Distribution Point (CRL DP) X.509, version 3, certificate extension when the certificate is issued. A CRL DP is an optional extension specified by the X.509 version 3 certificate standard, which indicates the location of the Partitioned CRL where revocation information for a certificate is stored. Typically, the value in this extension is in the form of a URL. CRL DPs allow revocation information within a single certificate authority domain to be posted in multiple CRLs. CRL DPs subdivide revocation information into more manageable pieces to avoid proliferating voluminous CRLs, thereby providing performance benefits. For example, a CRL DP is specified in the certificate and can point to a file on a Web server from which that certificate's revocation information can be downloaded.

Note:

To use CRLs with other Oracle products, refer to the specific product documentation. This implementation of certificate validation with CRLs is only available in the Oracle Database 12c release 1 (12.1) and later SSL adapter.

21.4.2.4 Wallets

A wallet is a container that stores authentication and signing credentials, including private keys, certificates, and trusted certificates Transport Layer Security (TLS) needs.

A wallet is optional if you want to use a walletless one-way TLS configuration on the client with CA certificates in the system's certificate store.

In an Oracle environment, every entity that communicates over TLS must have a wallet containing an X.509 version 3 certificate, private key, and list of trusted certificates, with the exception of Diffie-Hellman.

Security administrators use the orapki utility to manage security credentials on the server. Wallet owners use it to manage security credentials on clients. You can do the following:

  • Generate a public-private key pair and create a certificate request

  • Store a user certificate that matches with the private key

  • Configure trusted certificates

21.5 Transport Layer Security Encryption Combined with Authentication Methods

You can configure Oracle Database to use TLS concurrently with database user names and passwords, RADIUS, and Kerberos.

21.5.1 Architecture: Oracle Database and Transport Layer Security

It is important to understand the architecture of how Oracle Database works with TLS.

Figure 23-4 , which displays the Oracle Database implementation of Transport Layer Security architecture, shows that Oracle Databases operates at the session layer on top of TLS and uses TCP/IP at the transport layer. The session layer is a network layer that provides the services needed by the presentation layer entities that enable them to organize and synchronize their dialogue and manage their data exchange. This layer establishes, manages, and terminates network sessions between the client and server. The transport layer is a networking layer that maintains end-to-end reliability through data flow control and error recovery methods.

This separation of functionality lets you employ TLS concurrently with other supported protocols.

21.5.2 How Transport Layer Security Works with Other Authentication Methods

Transport Layer Security can be used with other authentication methods that Oracle Database supports.

Figure 21-1 illustrates a configuration in which Transport Layer Security is used in combination with another authentication method.

Figure 21-1 Transport Layer Security in Relation to Other Authentication Methods

Description of Figure 21-1 follows
Description of "Figure 21-1 Transport Layer Security in Relation to Other Authentication Methods"

In this example, Transport Layer Security is used to establish the initial handshake (server authentication), and an alternative authentication method is used to authenticate the client. The process is as follows:

  1. The client seeks to connect to the Oracle database server.

  2. Transport Layer Security performs a handshake during which the server authenticates itself to the client and both the client and server establish which cipher suite to use.

  3. Once the Transport Layer Security handshake is successfully completed, the user seeks access to the database.

  4. The Oracle database server authenticates the user with the authentication server using a non-TLS authentication method such as a password, Kerberos, RADIUS, or a cloud identity token (Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM), Microsoft Azure AD).

  5. Upon validation by the authentication method, the Oracle database server grants access and authorization to the user, and then the user can access the database securely by using TLS.

21.6 Transport Layer Security and Firewalls

Oracle Database supports two application proxy-based and stateful packet inspection of firewalls.

These firewalls are as follows:

  • Application proxy-based firewalls: Examples are Network Associates Gauntlet, or Axent Raptor.

  • Stateful packet inspection firewalls: Examples are Check Point Firewall-1, or Cisco PIX Firewall.

When you enable TLS, stateful inspection firewalls behave like application proxy firewalls because they do not decrypt encrypted packets.

Firewalls do not inspect encrypted traffic. When a firewall encounters data addressed to a TLS port on an intranet server, it checks the target IP address against its access rules and lets the TLS packet pass through to permitted TLS ports, rejecting all others.

21.7 Transport Layer Security Parameters

Oracle provides parameters to control Transport Layer Security.

21.7.1 Ways to Configure a Parameter for Transport Layer Security

There are two ways to configure a parameter for Transport Layer Security (TLS).

  • Static: Oracle recommends that you do not specify values for the SSL_VERSION and SSL_CIPHER_SUITES parameters in the sqlnet.ora and listener.ora files. Omitting these values facilitate auto-detection of the TLS version (which ensures that the highest available version is selected) and their associated cipher suites. Oracle Database uses the TLS_AES_256_GCM_SHA384 cipher as the default.

    For environments where you want to enforce TLS1.3 explicitly, the parameter values are as follows:

    • SSL_VERSION = TLSv1.3
    • SSL_CIPHER_SUITES = (TLS_AES_256_GCM_SHA384 ,TLS_AES_128_GCM_SHA256, TLS_AES_128_CCM_SHA256, TLS_CHACHA20_POLY1305_SHA256)

    FIPS-compliant ciphers are as follows:

    • TLS_AES_256_GCM_SHA384
    • TLS_AES_128_GCM_SHA256
    • TLS_AES_128_CCM_SHA256
  • Dynamic: The TLS parameter used in the TNS connect string that takes precedence over the same or similar parameter in sqlnet.ora.

21.7.2 Cipher Suite and Authentication Parameters for Transport Layer Security

Oracle provides a range of cipher suite and authentication parameters for Transport Layer Security (TLS).

The following table lists parameters that you can use to set for TLS cipher suites and authentication.

Table 21-1 TLS Parameters

Parameter Description Static Dynamic

AUTHENTICATION_SERVICE

Specifies the authentication service for the connection

No

Yes

SQLNET.AUTHENTICATION_SERVICES

Enables one or more authentication services

Yes

No

SSL_ALLOW_WEAK_DN_MATCH

Allows the earlier weaker distinguished name (DN) matching behavior during server-side certificate validation

Yes

Yes

SSL_CLIENT_AUTHENTICATION

Specifies whether a client is authenticated using TLS

Yes

Yes

HTTPS_CLIENT_AUTHENTICATION

Specifies whether a client is authenticated using TLS for HTTPS connections

Yes

Yes

SSL_CIPHER_SUITES

Specifies the TLS cipher suites allowed for TLS connections

Yes

Yes

SSL_SERVER_CERT_DN

Specifies the distinguished name (DN) of the database server

No

Yes

SSL_SERVER_DN_MATCH

Enforces server-side certification validation through distinguished name (DN) matching

Yes

Yes

SSL_VERSION

Lists the valid TLS versions that Oracle Database uses for connections

Yes

Yes

21.7.3 Oracle Wallet Location

You must specify wallet location parameters for applications that must access an Oracle wallet for loading the security credentials into the process space.

Table 21-2 shows the configuration example for each configuration type.

  • Static configuration: sqlnet.ora, listener.ora

  • Dynamic configuration: tnsnames.ora

Table 21-2 Wallet Location Parameters

Static Configuration Dynamic Configuration
WALLET_LOCATION =
(SOURCE=
  (METHOD=File)
  (METHOD_DATA=
     (DIRECTORY=your_wallet_dir)
      )

)

WALLET_LOCATION=your_wallet_dir

The default wallet location is the ORACLE_HOME directory.

Note:

The parameter WALLET_LOCATION is deprecated for use with Oracle Database 23ai for the Oracle Database server. It is not deprecated for use with the Oracle Database client.

For Oracle Database server, Oracle recommends that you use the WALLET_ROOT system parameter instead of using WALLET_LOCATION.

21.7.4 Oracle Wallet Search Order

Oracle Database provides several routes for finding the wallet on a server in a Transport Layer Security (TLS) environment.

The Oracle Database server retrieves the wallet by searching in these locations, in the following order:

  1. Per-PDB wallet under WALLET_ROOT in the init.ora file

    Note that WALLET_ROOT/tls for the CDB root, WALLET_ROOT/pdb_ID/tls for PDB

  2. Per-PDB wallet under WALLET_LOCATION in the sqlnet.ora file

    Note that WALLET_LOCATION/tls for the CDB root, WALLET_LOCATION/pdb_ID/tls for PDB

  3. WALLET_LOCATION in the sqlnet.ora file
  4. $TNS_ADMIN environment variable setting
  5. Default wallet location:
    • Linux: /etc/ORACLE/WALLETS/user_name
    • Windows: C:\Users\user_name\\ORACLE\WALLETS

The TNS listener retrieves the wallet location by searching in these locations, in the following order:

  1. WALLET_LOCATION in the listener.ora file
  2. $TNS_ADMIN environment variable setting
  3. Default wallet location:
    • Linux: /etc/ORACLE/WALLETS/user_name
    • Windows: C:\Users\user_name\\ORACLE\WALLETS

Oracle Database Client retrieves the wallet by searching in these locations, in the following order:

  1. Connect string
  2. WALLET_LOCATION in the sqlnet.ora file
  3. $TNS_ADMIN environment variable setting
  4. Default wallet location:
    • Linux: /etc/ORACLE/WALLETS/user_name
    • Windows: C:\Users\user_name\\ORACLE\WALLETS
  5. System wallets located in the certificate store location. The default certificate store location depends on the platform. For Windows, it is in the Microsoft Certificate Store for Microsoft Windows. For Linux, its locations are as follows:
    • RHEL/Oracle Linux: /etc/pki/tls/cert.pem
    • Debian/Ubuntu/Gentoo: /etc/ssl/certs/ca-certificates.crt
    • Fedora/RHEL: /etc/pki/tls/certs/ca-bundle.crt
    • OpenSUSE: /etc/ssl/ca-bundle.pem
    • OpenELEC: /etc/pki/tls/cacert.pem
    • CentOS/RHEL7: /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
    • Alpine Linux: /etc/ssl/cert.pem

21.8 Transport Layer Security Connections without a Client Wallet

A Transport Layer Security (TLS) connection that uses a common root certificate for the database server does not require a client wallet.

21.8.1 About Transport Layer Security Connections without a Client Wallet

You can configure a Transport Layer Security (TLS) connection without a client wallet if your environment meets certain requirements.

Consider using a TLS connection without a client wallet if your environment meets these requirements:

  • The client certificate is not used as a means of user authentication to the database. Only the server certificate is required to establish a TLS connection.
  • The server certificate was issued by a certificate authority (CA) whose certificate is available in the system’s default certificate store (common root certificate).
  • The Oracle Database server and listener are configured with client authentication disabled. (Set SSL_CLIENT_AUTHENTICATION=FALSE).

This is the most common type of configuration as long as the root certificate for the database server already exists in the local system certificate store. This configuration can be used for both cloud and on-premises databases. This configuration enables the client to verify server certificates without having to configure its own wallet.

21.8.2 Configuring a Transport Layer Security Connection without a Client Wallet

Before you can configure Transport Layer Security (TLS) without using client wallets, you must ensure that the database does not require client authentication.

For the C and Instant Client database drivers (and therefore, SQL*Plus), the walletless feature is only available on Microsoft Windows and Linux x64. For the JDBC-thin driver, the walletless feature is available on all platforms.
  1. Log in to the server where the Oracle database resides.
  2. Check the SSL_CLIENT_AUTHENTICATION setting in the sqlnet.ora file.

    The default for SSL_CLIENT_AUTHENTICATION is TRUE, which will require mTLS (mutual TLS requiring a client certificate in a client wallet). Settings are as follows:

    • OFF/FALSE disables mTLS, which enables one-way TLS.
    • ON/TRUE enables mTLS, which disables one-way TLS.
    • OPTIONAL enables the server to behave as follows:
      • If the client sends a certificate, then the connection will be completed as a mTLS connection after authenticating the client.
      • If the client does not send a certificate, then the connection will be completed as a one-way TLS connection.

    By default, the sqlnet.ora file is located in the $ORACLE_HOME/network/admin directory or in the location set by the TNS_ADMIN environment variable.

  3. Ensure that the server wallet exists in the default location, defined by the WALLET_ROOT system parameter, or in the WALLET_LOCATION sqlnet.ora parameter.

    Note:

    The parameter WALLET_LOCATION is deprecated for use with Oracle Database 23ai for the Oracle Database server. It is not deprecated for use with the Oracle Database client.

    For Oracle Database server, Oracle recommends that you use the WALLET_ROOT system parameter instead of using WALLET_LOCATION.

  4. Check the listener.ora file to ensure TLS is specified.
    LISTENER = (ADDRESS=(PROTOCOL=tcps)(HOST=)(PORT=port))

    The listener.ora file requires the SSL_CLIENT_AUTHENTICATION parameter to be set to FALSE or OPTIONAL, like the server equivalent.

  5. Ensure that the listener wallet also exists in the default location or in the WALLET_LOCATION parameter in listener.ora.
    By default, listener.ora is located in the $ORACLE_HOME/network/admin directory.
  6. Log in to the client for the Oracle database.
  7. Modify the client sqlnet.ora and tnsnames.ora files.
    • Edit the SSL_CLIENT_AUTHENTICATION setting in the sqlnet.ora file.

      Set the SSL_CLIENT_AUTHENTICATION=FALSE, because the default is TRUE. A setting of FALSE, will not send information about the client side certificate. Because this applies to every connection, you can change the SSL_CLIENT_AUTHENTICATION parameter in the tnsnames.ora connection string using the same parameter setting. This setting is optional.

    • If you connect to multiple databases and some require mTLS with a client wallet, then you can have two options for setting different connections with and without a client wallet, as follows:
      • Option 1: Set WALLET_LOCATION in sqlnet.ora for a common wallet. Then use WALLET_LOCATION in your connect string (in tnsnames.ora or directly on the command line) to override the setting in sqlnet.ora. You can specify a different wallet location for a connection or tell the connection to use the system default keystore instead. Use the following parameter to change wallet location to the system default keystore:
        net_service_name = (DESCRIPTION=(ADDRESS = (PROTOCOL=tcps)
        (HOST=host_name)(PORT=port)) (SECURITY=(WALLET_LOCATION=SYSTEM)) 
        (CONNECT_DATA=(SERVICE_NAME=service_name)))

        The following example changes the wallet location to a wallet file directory:

        net_service_name = (DESCRIPTION=(ADDRESS = (PROTOCOL=tcps)
        (HOST=host_name)(PORT=port)) (SECURITY=(WALLET_LOCATION=wallet_file_directory))
        (CONNECT_DATA=(SERVICE_NAME=service_name)))

        The default certificate store location depends on the platform. For Windows, it is in the Microsoft Certificate Store for Microsoft Windows. For Linux, its locations are as follows:

        • RHEL/Oracle Linux: /etc/pki/tls/cert.pem
        • Debian/Ubuntu/Gentoo: /etc/ssl/certs/ca-certificates.crt
        • Fedora/RHEL: /etc/pki/tls/certs/ca-bundle.crt
        • OpenSUSE: /etc/ssl/ca-bundle.pem
        • OpenELEC: /etc/pki/tls/cacert.pem
        • CentOS/RHEL7: /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
        • Alpine Linux: /etc/ssl/cert.pem

        For non-Linux and non-Windows systems, if the PEM file is not in one of the locations listed above for Linux systems, then you must either copy the PEM file to one of these default Linux locations or create a symlink from the PEM file to one of these locations. The file must be a PEM file.

        You cannot change the default location of the certificate store. By default, tnsnames.ora is located in the $ORACLE_HOME/network/admin directory.

      • Option 2: Only specify WALLET_LOCATION as part of the connections that need to use a client wallet. Do not specify WALLET_LOCATION in sqlnet.ora. Connections that do not need to use a client wallet will automatically use the local default system keystore if WALLET_LOCATION is not specified in the sqlnet.ora file.
  8. In SQL*Plus, to determine if the database connections are using TLS, check the connections by performing the following query.
     SELECT SYS_CONTEXT ('USERENV', 'NETWORK_PROTOCOL') FROM DUAL;

    Output similar to the following should appear:

    SYS_CONTEXT('USERENV','NETWORK_PROTOCOL')
    -------------------------------------------------------------------
    tcps

Related Topics

21.9 Transport Layer Security Connections with a Client Wallet

You must configure Transport Layer Security on the server, and then the client if mTLS is configured.

21.9.1 Step 1: Configure Transport Layer Security on the Server

During installation, Oracle sets defaults on the Oracle database server and the Oracle client for TLS parameters, except the Oracle wallet location.

21.9.1.1 Step 1A: Confirm the Wallet Creation on the Server

Before proceeding to the next step, confirm that a wallet has been created and that it has a certificate.

  1. Log in to the Oracle Database server where the wallet resides.
  2. Run the following command:
    orapki wallet display -wallet wallet_location
    

    The wallet should contain a certificate with a status of Ready and auto-login turned on. You can use orapki create wallet to create a wallet that has auto-login enabled.

21.9.1.2 Step 1B: Specify the Database Wallet Location on the Server

Next, you are ready to specify a location on the server for the wallet.

  1. Log in to the Oracle Database server.
  2. Create the wallet using either the orapki and mkstore (deprecated) command-line tools.
    For example, to create the wallet using orapki:
    orapki wallet create -wallet wallet_location

    To create the wallet as an auto-login wallet, use this syntax:

    orapki wallet create -wallet wallet_location -auto_login
  3. Modify the WALLET_LOCATION parameter in both the sqlnet.ora and listener.ora files, as follows:
    WALLET_LOCATION = 
     (SOURCE=
      (METHOD=file)
      (METHOD_DATA=
       (DIRECTORY=wallet_location)))

    Note the following:

    • When you specify the directory, note that if you are configuring the database-to-directory TLS connection for Enterprise User Security, then Database Configuration Assistant automatically creates a database wallet while registering the database with the directory. You must use that wallet to store the database PKI credentials for TLS-authenticated Enterprise User Security.

      Note:

      Enterprise User Security (EUS) is deprecated with Oracle Database 23ai.

      Oracle recommends that you migrate to using Centrally Managed Users (CMU). This feature enables you to directly connect with Microsoft Active Directory without an intervening directory service for enterprise user authentication and authorization to the database. If your Oracle Database is in the cloud, you can also choose to move to one of the newer integrations with a cloud identity provider.

      The parameter WALLET_LOCATION is deprecated for use with Oracle Database 23ai for the Oracle Database server. It is not deprecated for use with the Oracle Database client.

      For Oracle Database server, Oracle recommends that you use the WALLET_ROOT system parameter instead of using WALLET_LOCATION.

      For example:

      ALTER SYSTEM SET WALLET_ROOT='wallet_location' SCOPE =  SPFILE SID = "*";
    • The settings in the sqlnet.ora file apply to all pluggable databases (PDBs).

    • Ensure that you enter the same wallet location when you create it and when you set the location in the sqlnet.ora file.

Note:

The listener uses the wallet defined in the listener.ora file. It can use any database wallet. When SSL is configured for a server using Net Manager, the wallet location is entered into the listener.ora and the sqlnet.ora files. The listener.ora file is not relevant to the Oracle client.

To change the listener wallet location so that the listener has its own wallet, you can edit listener.ora to enter the new location.

21.9.1.3 Step 1C: Set the Transport Layer Security Cipher Suites on the Server (Optional)

Optionally, you can set the Transport Layer Security cipher suites.

21.9.1.3.1 About the Transport Layer Security Cipher Suites

A cipher suite is a set of authentication, encryption, and data integrity algorithms used for exchanging messages between network entities.

During a Transport Layer Security handshake, two entities negotiate to see which cipher suite they will use when transmitting messages back and forth.

When you install Oracle Database, the Transport Layer Security cipher suites are set for you by default and negotiated in the order they are listed. You can override the default order by setting the SSL_CIPHER_SUITES parameter. Ensure that you enclose the SSL_CIPHER_SUITES parameter setting in parentheses (for example, SSL_CIPHER_SUITES=(TLS_AES_256_GCM_SHA384)). Otherwise, the cipher suite setting will not parse correctly.

You can prioritize the cipher suites. When the client negotiates with servers regarding which cipher suite to use, it follows the prioritization you set. When you prioritize the cipher suites, consider the following:

  • Compatibility. Server and client must be configured to use compatible cipher suites for a successful connection.

  • Cipher priority and strength. Prioritize cipher suites starting with the strongest and moving to the weakest to ensure the highest level of security possible.

  • The level of security you want to use.

  • The impact on performance.

21.9.1.3.2 TLS Cipher Suite Authentication, Encryption, Integrity, and TLS Versions

Oracle Database supports a set of cipher suites that are set by default when you install Oracle Database.

Table 21-3 lists the authentication, encryption, and data integrity types each cipher suite uses.

To meet your security requirements, Oracle strongly recommends that you use TLS 1.3.

In the following table, the cipher suites that are marked as deprecated are considered less secure. They are disabled for security but can be enabled by setting the parameter SSL_ENABLE_WEAK_CIPHERS to TRUE in sqlnet.ora. By default, SSL_ENABLE_WEAK_CIPHERS is FALSE.

Table 21-3 Transport Layer Security Cipher Suites

Cipher Suites Authentication Encryption Data Integrity TLS Compatibility

TLS_AES_128_CCM_SHA256

CDHE_RSA, DHE_RSA, ECDHE_ECDSA

AES 128 CCM

SHA256 (SHA 2)

TLS 1.3

TLS_AES_128_GCM_SHA256

CDHE_RSA, DHE_RSA, ECDHE_ECDSA

AES 128 GCM

SHA256 (SHA-2)

TLS 1.3

TLS_AES_256_GCM_SHA384

CDHE_RSA, DHE_RSA, ECDHE_ECDSA

AES 256 GCM

SHA384 (SHA-2)

TLS 1.3

TLS_CHACHA20_POLY1305_SHA256 (non-FIPS only)

CDHE_RSA, DHE_RSA, ECDHE_ECDSA

CHACHA20 POLY1305

SHA256 (SHA-2)

TLS 1.3

TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 (deprecated)

DHE_RSA

AES 128 CBC

SHA256 (SHA-2)

TLS 1.2

TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

DHE_RSA

AES 128 GCM

SHA256 (SHA-2)

TLS 1.2

TLS_DHE_RSA_WITH_AES_256_CBC_SHA (deprecated)

DHE_RSA

AES 256 CBC

SHA (SHA-1)

TLS 1.2

TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 (deprecated)

DHE_RSA

AES 256 CBC

SHA256 (SHA-2)

TLS 1.2

TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

DHE_RSA

AES 256 GCM

SHA384 (SHA-2)

TLS 1.2

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA (deprecated)

ECDHE_ECDSA

AES 128 CBC

SHA (SHA-1)

TLS 1.2

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA (deprecated)

ECDHE_ECDSA

AES 128 CBC

SHA (SHA-1)

TLS 1.2

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 (deprecated)

ECDHE_ECDSA

AES 128 CBC

SHA256 (SHA-2)

TLS 1.2

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

ECDHE_ECDSA

AES 128 GCM

SHA256 (SHA-2)

TLS 1.2

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA (deprecated)

ECDHE_ECDSA

AES 256 CBC

SHA (SHA-1)

TLS 1.2

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 (deprecated)

ECDHE_ECDSA

AES 256 CBC

SHA384 (SHA-2)

TLS 1.2

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

ECDHE_ECDSA

AES 256 GCM

SHA384 (SHA-2)

TLS 1.2

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (deprecated)

ECDHE_RSA

AES 128 CBC

SHA (SHA-1)

TLS 1.2

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (deprecated)

ECDHE_RSA

AES 128 CBC

SHA256 (SHA-2)

TLS 1.2

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

ECDHE_RSA

AES 128 GCM

SHA256 (SHA-2)

TLS 1.2

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (deprecated)

ECDHE_RSA

AES 256 CBC

SHA (SHA-1)

TLS 1.2

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (deprecated)

ECDHE_RSA

AES 256 CBC

SHA384 (SHA-2)

TLS 1.2

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

ECDHE_RSA

AES 256 GCM

SHA384 (SHA-2)

TLS 1.2

TLS_RSA_WITH_AES_128_CBC_SHA (deprecated)

RSA

AES 128 CBC

SHA (SHA-1)

TLS 1.2

TLS_RSA_WITH_AES_128_CBC_SHA256 (deprecated)

RSA

AES 128 CBC

SHA256 (SHA-2)

TLS 1.2

TLS_RSA_WITH_AES_128_GCM_SHA256 (deprecated)

RSA

AES 128 GCM

SHA256 (SHA-2)

TLS 1.2

TLS_RSA_WITH_AES_256_CBC_SHA (deprecated)

RSA

AES 256 CBC

SHA (SHA-1)

TLS 1.2

TLS_RSA_WITH_AES_256_CBC_SHA256 (deprecated)

RSA

AES 256 CBC

SHA256 (SHA-2)

TLS 1.2

TLS_RSA_WITH_AES_256_GCM_SHA384 (deprecated)

RSA

AES 256 GCM

SHA384 (SHA-2)

TLS 1.2

21.9.1.3.3 Enabling Weak Cipher Suites

You can enable deprecated cipher suites by setting the SSL_ENABLE_WEAK_CIPHERS parameter.

Table 21-3 lists the cipher suites that have been disabled.
  1. Log in to Oracle Database.
  2. Modify the following parameter in the sqlnet.ora file on both the server and client:
    SSL_ENABLE_WEAK_CIPHERS=value

    In this specification, value can be one of the following:

    • FALSE (or OFF, NO, 0) disables the weak ciphers. The setting is the default. If you try to use a weak cipher, then depending on where you are, the following errors appear:
      • In the database server: ORA-28860: Fatal SSL error
      • In the database client: ORA-29039: There are no matching cipher suites.

      When SSL_ENABLE_WEAK_CIPHERS is set to FALSE, then the following cipher suites are available for use:

      • TLS_AES_128_CCM_SHA256
      • TLS_AES_128_GCM_SHA256
      • TLS_AES_256_GCM_SHA384
      • TLS_CHACHA20_POLY1305_SHA256
      • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
      • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
      • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    • TRUE (or ON, YES, 1) enables the weak ciphers.
21.9.1.3.4 Specifying Transport Layer Security Cipher Suites for the Database Server

You may optionally specify the Transport Layer Security cipher suites for the database server if specific ciphers are preferred.

Oracle recommends that you do not specify the SSL_CIPHER_SUITES parameter so that the strongest cipher suite common to the server and client are used.
  1. Log in to the Oracle Database server.
  2. Modify the SSL_CIPHER_SUITES parameter in the sqlnet.ora file.
    SSL_CIPHER_SUITES= (SSL_cipher_suite1 [,SSL_cipher_suite2])
21.9.1.4 Step 1D: Set the Required Transport Layer Security Version on the Server (Optional)

The SSL_VERSION parameter defines the version of TLS that must run on the systems with which the server communicates.

Optionally, you can set the SSL_VERSION parameter in the sqlnet.ora or the listener.ora file.

You can require these systems to use any valid version.

  • In the server sqlnet.ora file, set the SSL_VERSION parameter to indicate the supported TLS versions on the server.
    Valid values are undetermined (the default), TLSv1.2, and TLSv1.3. Separate multiple entries with a comma. For example:
    SSL_VERSION=(TLSv1.2,TLSv1.3)
21.9.1.5 Step 1E: Set Transport Layer Security Client Authentication on the Server (Optional)

The SSL_CLIENT_AUTHENTICATION parameter controls whether the client is authenticated using TLS.

You must set this parameter in the sqlnet.ora file on the server. The default value of SSL_CLIENT_AUTHENTICATION parameter is TRUE.

You can set the SSL_CLIENT_AUTHENTICATION to FALSE if you are using one-way TLS that only requires authenticating the server.

Also, you can set this parameter to FALSE for the client to authenticate itself to the server by using any of the non-SSL authentication methods supported by Oracle Database, such as Kerberos or RADIUS.

  • To set SSL_CLIENT_AUTHENTICATION on the server, edit the sqlnet.ora file.
    For example:
    SSL_CLIENT_AUTHENTICATION=FALSE
21.9.1.6 Step 1F: Set Transport Layer Security as an Authentication Service on the Server (Optional)

The SQLNET.AUTHENTICATION_SERVICES parameter in the sqlnet.ora file sets the TLS authentication service.

Set this parameter if you want to use TLS authentication in conjunction with another authentication method supported by Oracle Database. For example, use this parameter if you want the server to authenticate itself to the client by using TLS and the client to authenticate itself to the server by using Kerberos.

  • To set the SQLNET.AUTHENTICATION_SERVICES parameter on the server, add TCP/IP with TLS (TCPS) to this parameter in the sqlnet.ora file by using a text editor. For example, if you want to use SSL authentication in conjunction with RADIUS authentication, set this parameter as follows:

     SQLNET.AUTHENTICATION_SERVICES = (TCPS, radius)
    

If you do not want to use TLS authentication in conjunction with another authentication method, then do not set this parameter.

21.9.1.7 Step 1G: Create a Listening Endpoint that Uses TCP/IP with Transport Layer Security on the Server

You can configure a listening endpoint to use TCP/IP with TLS on the server.

  • Configure the listener in the listener.ora file. Oracle recommends using port number 2484 for typical Oracle Net clients.
    For example:
    LISTENER = (ADDRESS=(PROTOCOL=tcps)(HOST=)(PORT=2484))
21.9.1.8 Step 1H: Restart the Listener

To complete the configuration of Transport Layer Security on the server, you must restart the listener.

  • For example:
    lsnrctl reload

21.9.2 Step 2: Configure Transport Layer Security on the Client

When you configure SSL on the client, you configure the server DNs and use TCP/IP with TLS on the client.

21.9.2.1 Step 2A: Confirm the Client Wallet Creation

You must confirm that a wallet has been created on the client and that the client has a valid certificate.

  • Run the following command to check that the wallet has been created.
    orapki wallet display -wallet wallet_location
    
    Oracle recommends that you use the orapki crl delete command remove the trusted certificate in your Oracle wallet that is associated with each certificate authority that you do not use.
21.9.2.2 Step 2B: Configure Server DN Matching and Use TCP/IP with TLS on the Client

Next, you are ready to configure server DN matching and use TCP/IP with Transport Layer Security (TLS) on the client.

21.9.2.2.1 About Configuring the Server DN Matching and Using TCP/IP with TLS on the Client

In addition to validating the server certificate's certificate chain, you can perform an extra check through server DN matching.

Server DN matching is optional, but Oracle recommends it because it adds a layer of security to the client.

You can configure either partial DN matching or full DN matching. The ability to use either partial or full DN matching enables more flexibility based on how you create and manage host certificates.

  • Partial DN matching: After you set the SSL_SERVER_DN_MATCH parameter to TRUE, then partial DN matching is enabled automatically. The client uses the HOST parameter to match against the CN of the server certificate. For example, suppose the client tries to connect to a server with HOST=finance.us.example.com. With partial DN matching, the client checks the server's certificate to verify that CN=finance is the server's DN. Also for partial DN matching, only the host name (finance) is checked, not the fully qualified domain name (finance.us.example.com).
  • Full DN matching: Full DN matching enables the client to match against the complete DN of the server. If you want to perform a full DN match, then you must set the SSL_SERVER_DN_MATCH parameter to TRUE and the SSL_SERVER_CERT_DN parameter to the server's DN in the TNS connect string.

    You must manually edit the tnsnames.ora client network configuration file to specify the server's DN and the TCP/IP with TLS protocol. The tnsnames.ora file can be located on the client or in the LDAP directory. If it is located on the server, then it typically resides in the same directory as the listener.ora file. The tnsnames.ora file is typically located in the setting specified by the TNS_ADMIN environment variable. If TNS_ADMIN is not set, then tnsnames.ora resides in the following directory locations:

    • Linux: $ORACLE_HOME/network/admin/
    • Windows: ORACLE_BASE\ORACLE_HOME\network\admin\
21.9.2.2.2 Configuring the Server DN Matching and Using TCP/IP with TLS on the Client

You must edit the tnsnames.ora and sqlnet.ora files to configure the server DN matching and user TCP/IP with TLS on the client.

21.9.2.2.2.1 Partial DN Matching (Host Name-Based DN Matching)

To enable Partial DN matching, you must set the SSL_SERVER_DN_MATCH parameter to TRUE in the sqlnet.ora file.

After the parameter is set to TRUE, then partial DN matching is enabled by default. The HOST parameter in the connect identifier configured in tnsnames.ora is used to match the server certificate's DN.

By default, the tnsnames.ora and sqlnet.ora files are in the $ORACLE_HOME/network/admin directory on UNIX systems and in ORACLE_HOME\network\admin on Windows.

An example of tnsnames.ora for partial DN matching is as follows:

finance=
    (DESCRIPTION=
    (ADDRESS_LIST=
    (ADDRESS= (PROTOCOL = tcps) (HOST = finance) (PORT = 1575)))
    (CONNECT_DATA=
    (SERVICE_NAME= finance.us.example.com)))

An example of sqlnet.ora for partial DN matching is as follows:

SSL_SERVER_DN_MATCH=TRUE
21.9.2.2.2.2 Full DN Matching

You must edit the tnsnames.ora and sqlnet.ora files to configure the server DN matching and use TCP/IP with TLS on the client.

By default, the tnsnames.ora and sqlnet.ora files are in the $ORACLE_HOME/network/admin directory on UNIX systems and in ORACLE_HOME\network\admin on Windows.

If you want to use full DN matching, then set the SSL_SERVER_CERT_DN parameter to the complete DN in the connect identifier, similar to the following example:

(SECURITY=
(SSL_SERVER_CERT_DN="cn=finance,ou=OracleContext,c=us,o=example"))

The client uses this information to obtain the DN that it expects for the listener and server, enforcing the listener and server's DN to match the DN string.

Note:

Due to changes in the CA certificate format where the Organization Unit (OU) field will be removed starting in 2022, you may need to update your server certificate DN if you set the SSL_SERVER_CERT_DN parameter. After you receive the new server certificate with the OU removed from the DN, you must update the client SSL_SERVER_CERT_DN parameter to match the new DN.

An example of setting tnsnames.ora for full DN matching is as follows:

finance=
    (DESCRIPTION=
    (ADDRESS_LIST=
    (ADDRESS= (PROTOCOL = tcps) (HOST = finance) (PORT = 1575)))
    (CONNECT_DATA=
    (SERVICE_NAME= finance.us.example.com))
    (SECURITY=
    (SSL_SERVER_CERT_DN="cn=finance,ou=OracleContext,c=us,o=example"))

An example of setting sqlnet.ora for full DN matching is as follows:

SSL_SERVER_DN_MATCH=TRUE
21.9.2.2.3 Use of the SSL_ALLOW_WEAK_DN_MATCH Parameter to Control SSL_SERVER_DN_MATCH

The SSL_ALLOW_WEAK_DN_MATCH parameter controls how the SSL_SERVER_DN_MATCH parameter allows the service name for partial distinguished name matching and check the database server certificate.

Starting in Oracle Database 23ai, the behavior of the SSL_SERVER_DN_MATCH parameter has changed. Previously, only the database server certificate was checked for DN matching. With Oracle Database 23ai, the listener and server certificates are both checked. Also, the SERVICE_NAME setting is not used to check during partial DN match anymore. The HOST setting can still be used for partial DN matching with the certificate DN and subject alternative name (SAN), on both the listener and server certificates.

You can set SSL_ALLOW_WEAK_DN_MATCH as follows:

  • TRUE enables SSL_SERVER_DN_MATCH to check the database server certificate (but not the listener) and enable the service name to be used for partial DN matching. The search order on the client side is as follows: first, the host name, then the subject alternative name (SAN), and then the service name.
  • FALSE (the default) disables SSL_SERVER_DN_MATCH from checking service name matching. Instead, matching on the client side is based on a search for the HOST setting in the certificate DN, and if that is not available, then in the subject alternative name (SAN) field (but not the service name). The DN check is performed on the listener and the server.

If you used the service name for partial DN matching previously, then you must either get a new certificate or set SSL_ALLOW_WEAK_DN_MATCH to TRUE to revert to the pre-release 23ai behavior. You are most likely using the same certificate for both the database server and listener, but if you are not, then you will either need to do one of the following:

  • Get a new certificate (use the orapki cert create command for self-signed certificates).
  • Change or remove the DN matching strategy.
  • Set the SSL_ALLOW_WEAK_DN_MATCH parameter to TRUE to revert SSL_SERVER_DN_MATCH to its older behavior.

When you set SSL_ALLOW_WEAK_DN_MATCH to TRUE, note the following:

  • When the client performs a full DN match (SSL_SERVER_MATCH=TRUE, SSL_SERVER_CERT_DN="certificate_DN"), then only the database server certificate DN will need to match the SSL_SERVER_CERT_DN value.
  • When the client performs a partial DN match (SSL_SERVER_MATCH=TRUE, SSL_SERVER_CERT_DN is not set), then Oracle Database will compare the connect string parameter HOST to the common name (CN) of the database server certificate DN and the certificate subject alternate names field (SAN). If there is no partial match, then Oracle Database will continue and check the SERVICE_NAME parameter with the CN.
21.9.2.3 Step 2C: Specify Required Client TLS Configuration (Wallet Location)

You can modify the sqlnet.ora file to specify the required client TLS configuration.

  1. Log in to the Oracle Database client.
  2. Modify the WALLET_LOCATION and SSL_SERVER_DN_MATCH parameters in the sqlnet.ora file as follows:
    SSL_CLIENT_AUTHENTICATION =TRUE
    WALLET_LOCATION = 
     (SOURCE=
      (METHOD=File)
      (METHOD_DATA=
       (DIRECTORY=wallet_location)))
    
    SSL_SERVER_DN_MATCH=(ON/OFF)

    For the SSL_SERVER_DN_MATCH settings, note the following:

    • ON requires that the server's distinguished name (DN) match the host name. TLS ensures that the certificate is from the server and connections succeed only if there is a match.
    • OFF enables TLS to check for a match between the DN and the host name, but does not enforce it. Connections succeed regardless of the outcome but an error is logged if the match fails. This setting is the default. The following alert is displayed when you select OFF:
      Security Alert
      Not enforcing the server X.509 name match allows a server to potentially fake its identity. Oracle recommends selecting YES for this option so that connections are refused when there is a mismatch.
      
21.9.2.4 Step 2D: Connect to Multiple Databases with Different Certificates from a Single Database Client

Optionally, you can configure a client configuration to connect with multiple Oracle Database servers using different certificates and wallets.

21.9.2.4.1 About Connecting to Multiple Databases with Different Certificates from a Single Database Client

This feature enables multi-threaded clients to use multiple wallets that have different certificates for simultaneous Transport Layer Security (TLS) sessions.

Use this feature if you have a single client that must connect to different Oracle Databases using different wallets and certificates. An example would be for a client that requires access to multiple pluggable databases (PDBs), each with its own identity (certificate). This feature enables you to configure the client to connect to the correct identity for each PDB. After the configuration is complete, multi-threaded clients will be able to access more than one wallet with different certificates in simultaneous TLS sessions.

21.9.2.4.2 Enabling the Client Connection to Have Distinct TLS Sessions

You can configure the tnsnames.ora file WALLET_LOCATION parameter to enable a client connection to have distinct Transport Layer Security (TLS) sessions.

  1. Log in to the database server where the PDB is located.
  2. Locate the tnsnames.ora file.
    By default, the tnsnames.ora file is in the ORACLE_HOME/network/admin directory. The tnsnames.ora file can also be stored in the directory specified by the TNS_ADMIN environment variable.
  3. Edit the tnsnames.ora file to include the WALLET_LOCATION parameter.
    For example:
    ssl_certs = 
        (DESCRIPTION = 
           (ADDRESS=(PROTOCOL=tcps)(HOST=shobeen.us.example.com) (PORT=1750))
           (CONNECT_DATA=(SID=hr_pdb)) 
           (SECURITY=(WALLET_LOCATION=/oracle/wallets/certificates/hr_cert))
         )

    In this example, WALLET_LOCATION points to a directory that contains an TLS certificate called hr_cert.

    You can use WALLET_LOCATION in both tnsnames.ora and sqlnet.ora. WALLET_LOCATION in tnsnames.ora will overide the WALLET_LOCATION in sqlnet.ora for that tnsnames.ora service.

    The following example shows how multiple wallets with certificates can be configured in tnsnames.ora. Note that the SIDs and wallet locations are different.

    ssl_certs1 = 
        (DESCRIPTION = 
           (ADDRESS=(PROTOCOL=tcps)(HOST=shobeen.us.example.com) (PORT=1750))
           (CONNECT_DATA=(SID=sales_pdb)) 
           (SECURITY=(WALLET_LOCATION=/oracle/wallets/certificates/sales_cert))
         )
    ssl_certs2 = 
        (DESCRIPTION = 
           (ADDRESS=(PROTOCOL=tcps)(HOST=shobeen.us.example.com) (PORT=1750))
           (CONNECT_DATA=(SID=marketing_pdb)) 
           (SECURITY=(WALLET_LOCATION=/oracle/wallets/certificates/marketing_cert))
         )
21.9.2.5 Step 2E: Set the Client Transport Layer Security Cipher Suites (Optional)

Optionally, you can set the Transport Layer Security cipher suites. Oracle Database provides default cipher suite settings.

21.9.2.5.1 About Setting the Client Transport Layer Security Cipher Suites

A cipher suite is a set of authentication, encryption, and data integrity algorithms used for exchanging messages between network entities.

During an SSL handshake, two entities negotiate to see which cipher suite they will use when transmitting messages back and forth.

When you install Oracle Database, the TLS cipher suites are set for you by default. You can override the default by setting the SSL_CIPHER_SUITES parameter. For example, if you add the cipher suite TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, all other cipher suites in the default setting are ignored.

You can prioritize the cipher suites. When the client negotiates with servers regarding which cipher suite to use, it follows the prioritization you set. When you prioritize the cipher suites, consider the following:

  • The level of security you want to use.

  • Administrative requirements. The cipher suites selected for a client must be compatible with those required by the server. For example, in the case of an Oracle Call Interface (OCI) user, the server requires the client to authenticate itself.

You typically prioritize cipher suites starting with the strongest and moving to the weakest.

The currently supported Transport Layer Security cipher suites are set by default when you install Oracle Database.

21.9.2.5.2 Setting the Client Transport Layer Security Cipher Suites

You can modify the sqlnet.ora file to set the client TLS cipher suites.

  1. Log in to the Oracle Database client.
  2. Modify the SSL_CIPHER_SUITES parameter in the sqlnet.ora file as follows:
    SSL_CIPHER_SUITES= (SSL_cipher_suite1 [,SSL_cipher_suite2])
21.9.2.6 Step 2F: Set the Required TLS Version on the Client (Optional)

The SSL_VERSION parameter defines the version of TLS that must run on the systems with which the client communicates.

You must set the SSL_VERSION parameter in the sqlnet.ora file. You can require these systems to use any valid version.

The default setting for this parameter in sqlnet.ora is undetermined, which is set by selecting Any from the list in the SSL tab of the Network Security window. When Any is selected, TLS versions will be tried from higher version to lower version. First, it tries for TLS 1.3, then TLS 1.2.

To meet your security requirements, Oracle strongly recommends that you use TLS 1.3.

  1. In the Require SSL Version list, select the TLS version that you want to configure.

    The default setting is Any.

  2. From the File menu, select, Save Network Configuration.

    The sqlnet.ora file is updated. If you selected Any, then it is updated with the following entry:

    SSL_VERSION=UNDETERMINED
21.9.2.7 Step 2G: Set TLS as an Authentication Service on the Client (Optional)

The SQLNET.AUTHENTICATION_SERVICES parameter in the sqlnet.ora file sets the TLS authentication service.

21.9.2.7.1 About the SQLNET.AUTHENTICATION_SERVICES Parameter

The SQLNET.AUTHENTICATION_SERVICES parameter enables TLS authentication in conjunction with another authentication method supported by Oracle Database.

For example, use this parameter if you want the server to authenticate itself to the client by using TLS and the client to authenticate itself to the server by using RADIUS.

To set the SQLNET.AUTHENTICATION_SERVICES parameter, you must edit the sqlnet.ora file, which is located in the same directory as the other network configuration files.

Depending on the platform, the sqlnet.ora file is in the following directory location:

  • (UNIX) $ORACLE_HOME/network/admin

  • (Windows) ORACLE_BASE\ORACLE_HOME\network\admin\

21.9.2.7.2 Setting the SQLNET.AUTHENTICATION_SERVICES Parameter

You can set the SQLNET.AUTHENTICATION_SERVICES parameter in the sqlnet.ora file.

  • To set the client SQLNET.AUTHENTICATION_SERVICES parameter, add TCP/IP with TLS (TCPS) to this parameter in the sqlnet.ora file by using a text editor.

    For example, if you want to use TLS authentication in conjunction with RADIUS authentication, then set this parameter as follows:

     SQLNET.AUTHENTICATION_SERVICES = (TCPS, radius)
    

If you do not want to use TLS authentication in conjunction with another authentication method, then do not set this parameter.

21.9.2.8 Step 2H: Specify the Certificate to Use for Authentication on the Client (Optional)

If you have multiple certificates, then you can set one or more certificate selection parameters to specify the correct certificate.

By setting the certificate selection parameters for client authentication on Windows, the MSCAPI certificate selection box will not appear, and the matching certificate is automatically used for the Transport Layer Security.

21.9.2.8.1 Setting the SSL_CERTIFICATE_ALIAS Parameter

You can use the SSL_CERTIFICATE_ALIAS parameter to specify the alias of the client certificate.

  • To get the alias name value, run the following orapki command:

    orapki wallet display -wallet wallet_directory -pwd wallet_password -complete

    Next, set this value using the SSL_CERTIFICATE_ALIAS parameter.

    For example, for tnsnames.ora:

    net_service_name= 
          (DESCRIPTION=
            (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) 
            (SECURITY=(SSL_CERTIFICATE_ALIAS=my_cert))
          ) 

    This example shows how to set SSL_CERTIFICATE_ALIAS in the sqlnet.ora file:

    SSL_CERTIFICATE_ALIAS=my_cert
21.9.2.8.2 Setting the SSL_CERTIFICATE_THUMBPRINT Parameter

You can use the SSL_CERTIFICATE_THUMBPRINT to specify the thumbprint of the client certificate.

The value of the parameter is the SHA-1 or SHA-256 thumbprint of the client certificate, in the algorithm:hash format
  • To get the thumbprint value, run the following orapki command:

    orapki wallet display -wallet wallet_directory -pwd wallet_password -complete

    Next, set this value using the SSL_CERTIFICATE_THUMBPRINT parameter. The following example shows how to set it in the tnsnames.ora file.

    For example, in the tnsname.ora file:

    net_service_name= 
          (DESCRIPTION=
            (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) 
            (SECURITY=(SSL_CERTIFICATE_THUMBPRINT=SHA1:1B:11:01:5A:B1:2C:20:B2:12:34:3E:04:7B:83:47:DE:70:2E:4E:11))
          ) 

    This example shows how to set SSL_CERTIFICATE_THUMBPRINT in the sqlnet.ora file:

    SSL_CERTIFICATE_THUMBPRINT=SHA256:B38A5B1A036383922B5DE15361EE03940A56B456417E4124419B88EBC61E1123
21.9.2.8.3 Setting the SSL_EXTENDED_KEY_USAGE Parameter

You can use the SSL_CERTIFICATE_ALIAS parameter to specify the key usage of the client certificate.

You should set the SQLNET.SSL_EXTENDED_KEY_USAGE parameter if you have multiple certificates in the security module, but there is only one certificate with extended key usage field of client authentication, and this certificate is the one you want to use to authenticate to the database.
  • For example, in the sqlnet.ora file:

    SSL_EXTENDED_KEY_USAGE = "client authentication"
21.9.2.9 Step 2I: Check That the Connections Are Using Transport Layer Security

You can query the USERENV namespace to show the network protocol and TLS version for the TLS connection.

  • In SQL*Plus, perform the following queries.
    To display the protocol for an Oracle Database session:
    SELECT SYS_CONTEXT ('USERENV', 'NETWORK_PROTOCOL') FROM DUAL;

    Output similar to the following should appear:

    SYS_CONTEXT('USERENV','NETWORK_PROTOCOL')
    -------------------------------------------------------------------
    tcps

    To display the TLS version for an Oracle session:

    SELECT SYS_CONTEXT ('USERENV', 'TLS_VERSION') FROM DUAL;

    Output similar to the following appears:

    SYS_CONTEXT('USERENV','TLS_VERSION')
    --------------------------------------------------------------------
    TLS 1.3

    To display the TLS cipher suite for an Oracle session:

    SELECT SYS_CONTEXT ('USERENV', 'TLS_CIPHERSUITE') FROM DUAL;

    Output similar to the following appears:

    SYS_CONTEXT('USERENV','TLS_CIPHERSUITE')
    --------------------------------------------------------------------
    TLS_AES_256_GCM_SHA384

21.9.3 Step 3: Log in to the Database Instance

After you have completed the configuration, you are ready to log in to the database.

  • Start SQL*Plus and then enter one of the following connection commands:

    • If you are using Transport Layer Security authentication for the client (SSL_CLIENT_AUTHENTICATION=true in the sqlnet.ora file):

      CONNECT/@net_service_name
      
    • If you are not using Transport Layer Security authentication (SSL_CLIENT_AUTHENTICATION=false in the sqlnet.ora file):

      CONNECT username@net_service_name
      Enter password: password
      

21.10 Transport Layer Security Connections in an Oracle Real Application Clusters Environment

You can configure Transport Layer Security (TLS) connections in an Oracle Real Application Clusters (Oracle RAC) environment by using Oracle RAC tools and modifying Oracle Database configuration files.

21.10.1 Step 1: Configure TCPS Protocol Endpoints

In Oracle Real Application Clusters (Oracle RAC), clients access one of three scan listeners and are then routed to database listeners. To support Transport Layer Security (TLS), all of these listeners must have TCPS protocol endpoints.

  1. Log in to the cluster that hosts the Oracle RAC database.
  2. Check the listener resources to find if they support TCP endpoints.
    For example:
    $ srvctl config listener -h

    Output similar to the following appears:

    Name: LISTENER
    Subnet: 192.0.2.195
    Type: type
    Owner: pfitch
    Home: Grid_home
    End points: TCP:1521

    The following command displays information about the scan listener:

    $ srvctl config scan_listener -h

    Output similar to the following appears:

    SCAN Listener LISTENER_SCAN1 exists. Port: TCP:1529
    Registration invited nodes:
    Registration invited subnets:
    SCAN Listener is enabled.
    SCAN Listener is individually enabled on nodes:
    SCAN Listener is individually disabled on nodes:
  3. Add TCPS endpoints to the database listeners.
    For example:
    $ srvctl modify listener -endpoints "TCP:port_1/TCPS:port_2"
  4. Check the listener configuration.
    For example:
    $ srvctl config listener
    
    Name: LISTENER
    Network: 1, Owner: oracle
    Home: CRS_home
    End points: TCP:port_1/TCPS:port_2
    
    $ lsnrctl status
    
    Listening Endpoints Summary...
    (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=LISTENER)))
    (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=IP_address)(PORT=port_2)))
    (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=IP_address)(PORT=port_1)))
  5. Add TCPS endpoints to the scan listeners.
    For example:
    $ srvctl modify scan_listener -endpoints "TCP:port_1/TCPS:port_2"
  6. Check the scan listener configuration.
    For example:
    $ srvctl config scan_listener
    
    SCAN Listener LISTENER_SCAN1 exists. Port: TCP:port_1/TCPS:port_2
    SCAN Listener LISTENER_SCAN2 exists. Port: TCP:port_1/TCPS:port_2
    SCAN Listener LISTENER_SCAN3 exists. Port: TCP:port_1/TCPS:port_2
    
    $ lsnrctl status listener_scan3
    
    Listening Endpoints Summary...
    (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=LISTENER_SCAN3)))
    (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=IP_address)(PORT=port_1)))
    (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=IP_address)(PORT=port_2)))

21.10.2 Step 2: Ensure That the LOCAL_LISTENER Parameter Is Correctly Set on Each Node

The Oracle Agent automatically sets the LOCAL_LISTENER parameter on each node, but you should double-check to ensure that it is correct.

  1. Log in any Oracle Real Application Clusters (Oracle RAC) node.
  2. In SQL*Plus, as a user with the SYSDBA administrative privilege, check the LOCAL_LISTENER parameter.
    show parameter local_listener;

    Output similar to the following appears:

    NAME                                 TYPE        VALUE
    ------------------------------------ ----------- ------------------------------
    local_listener                       string      (DESCRIPTION=(ADDRESS_LIST=
                                                     (ADDRESS=(PROTOCOL=TCPS)(HOST=IP_address)
                                                     (PORT=port_2))))
  3. If the output is not what you want, then restart each Oracle RAC instance.

21.10.3 Step 3: Create Transport Layer Security Wallets and Certificates

You must create Transport Layer Security (TLS) wallets and certificates for the cluster and also for clients that will connect to the cluster over TLS.

21.10.3.1 Oracle Real Application Clusters Components That Need Certificates

Specific components in Oracle Real Application Clusters (Oracle RAC) need certificates when you configure Transport Layer Security (TLS) connections.

  • Each cluster node (server) and listener must have a wallet with the user certificate and CA certificates.
  • The client only needs CA certificates of the listeners and servers (either in wallet or system’s certificate store) if one-way TLS is configured.
  • The client needs a wallet with its user certificate and CA certificates of the listeners and servers if mTLS is configured.
21.10.3.2 Creating Transport Layer Security Wallets and Certificates

To create the Transport Layer Security wallets and certificates, you first create the root CA certificate, followed by the cluster and client wallets.

  1. Create the root CA certificate.
    1. Log in to any Oracle Real Application Clusters (Oracle RAC) cluster node.
    2. Use the orapki utility to create the CA wallet in a directory for the CA.
      $ orapki wallet create -wallet CA_home_wallet_file_directory
    3. Create a self-signed root certificate for the CA wallet.
      For example:
      $ orapki wallet add -wallet CA_home_wallet_file_directory -self_signed -dn "CN=test CA,O=test,C=c" -keysize 2048 -validity 3650 -sign_alg sha256
      Enter wallet password: password
    4. Extract the root CA certificate from the wallet.
      This root certificate will be used as the trusted CA certificate in cluster and client wallets and can be distributed or published for users who are building PKCS#12 wallets. For example:
      $ orapki wallet export -wallet CA_home_wallet_file_directory -dn "CN=test CA,O=test,C=c" -cert testCAroot.cer
      Enter wallet password: password

      At this stage, the CA_home_wallet_file_directory directory will contain the new wallet (ewallet.p12) and certificate (testCAroot.cer).

      To check the configuration:

       $ orapki wallet display -wallet CA_home_wallet_file_directory -summary

      Output similar to the following appears:

      Requested Certificates:
      User Certificates:
      Subject:        CN=test CA,O=test,C=c
      Trusted Certificates:
      Subject:        CN=test CA,O=test,C=c
  2. Create the cluster wallet.
    Next, you are ready follow the remaining steps in this procedure to sign the user certificate requests and provide authorized digital user certificates for different entities and processes in your environments. Repeat this process for each entity in the test environment that participates in the public key infrastructure functionality. A valid wallet consists of a root CA certificate and the signed user certificate.
    1. Create a wallet that is in a different location from the from the CA home directory.
      For example:
      $ orapki wallet create -wallet cluster_wallet_file_directory
      Enter password: password
      Enter password again: password 
    2. Create a user identity (user dn) and then a certificate request.
      For example:
      $ orapki wallet add -wallet cluster_wallet_file_directory -dn "CN=testuser" -keysize 2048
      Enter wallet password: password
      $ orapki wallet export -wallet cluster_wallet_file_directory -dn "CN=testuser" -request cluster_wallet_file_directory/testuser.req
      Enter wallet password: password

      At this stage, the cluster_wallet_file_directory directory will contain the SSO wallet (cwallet.sso), the wallet (ewallet.p12) and the certificate request (testuser.req). The certificate request can be signed by the CA generated above.

      For example:

      $ orapki cert create -wallet cluster_wallet_file_directory -request cluster_wallet_file_directory/testuser.req -cert user_wallet_file_directory/testuser.cer -validity 3650 -sign_alg sha256
      Enter wallet password: password

      The cluster_wallet_file_directory directory now has the testuser.req certificate request file.

    3. Import the root certificate (testCAroot.cer) and the signed user certificate (testuser.cer) into the user wallet.
      For example:
      $ orapki wallet add -wallet cluster_wallet_file_directory -trusted_cert -cert CA_home_wallet_file_directory/testCAroot.cer -pwd
      Enter wallet password: user_password
      $ orapki wallet add -wallet cluster_wallet_file_directory -user_cert -cert cluster_wallet_file_directory/testuser.cer
      Enter wallet password: user_password
    4. Check the finished cluster wallet.
      For example:
      $ orapki wallet display -wallet cluster_wallet_file_directory -summary
      
      Requested Certificates:
      User Certificates:
      Subject:        CN=testuser
      Trusted Certificates:
      Subject:        CN=test CA,O=test,C=c

      At this point, you are ready to copy the finished cluster wallet to each node of the cluster.

  3. Create the client wallet.
    1. Create a client wallet with the root certificate (testCAroot.cer).
      To make a successful TLS connection, the client only requires the CA certificates of the server's certificate.
      For example:
      $ orapki wallet create -wallet client_wallet_file_directory -auto_login
      $ orapki wallet add -wallet client_wallet_file_directory -trusted_cert -cert CA_home_wallet_file_directory/testCAroot.cer
    2. Check the finished client wallet.
      For example:
      $ orapki wallet display -wallet client_wallet_file_directory -summary
      
      Requested Certificates:
      User Certificates:
      Trusted Certificates:
      Subject:        CN=test CA,O=test,C=c

21.10.4 Step 4: Create a Wallet in Each Node of the Oracle RAC Cluster

After you have created the cluster wallet, you can copy it to each node of the Oracle Real Applications (Oracle RAC) cluster.

Ensure that each node is accessible by both the Oracle Real Application Clusters (Oracle RAC) database server (process monitor) and by the scan and local listeners that normally run from the GI home.
  1. Copy the PKCS#12 wallet (ewallet.p12) file that you created in the previous section to each node in the cluster.
  2. In each node, create an auto-login wallet (cwallet.sso).
    The cwallet.sso file is an obfuscated mirror copy of the ewallet.p12 and is the file that the database server and its listeners accesses. If you create the cwallet.sso on the Oracle RAC cluster, then you can copy it along with the ewallet.p12 file to the wallet directory on each node. You can also create the cwallet.sso file on each node separately if ewallet.p12 file is already in place. Run the following command in the same location as the ewallet.p12 file:
    $ orapki wallet create -wallet wallet_file_location -auto_login
    Enter wallet password: ewallet_password

21.10.5 Step 5: Define Wallet Locations in the listener.ora and sqlnet.ora Files

To enable the database server and listeners to access the wallets, you must define the wallet locations in the listener.ora and sqlnet.ora files.

  1. Modify the listener.ora file in the Grid home of every node.
    SSL_CLIENT_AUTHENTICATION = FALSE
    
    WALLET_LOCATION =
      (SOURCE =
        (METHOD = FILE)
        (METHOD_DATA =
          (DIRECTORY = wallet_file_location)
  2. In the sqlnet.ora file in the Oracle Database home, and the Grid home, of each cluster node, add the following information:
    SQLNET.AUTHENTICATION_SERVICES = (BEQ, TCP, TCPS)
    
    SSL_CLIENT_AUTHENTICATION = FALSE
    
    WALLET_LOCATION =
      (SOURCE =
        (METHOD = FILE)
        (METHOD_DATA =
          (DIRECTORY = wallet_file_location)
        )
      )

21.10.6 Step 6: Restart the Database Instances and Listeners

With the wallets in place and the *.ora files edited, you must restart the database server and listener processes so that they pick up the new settings.

The restart process will also enable the Oracle Real Application Clusters (Oracle RAC) instances where you set the LOCAL_LISTENER parameter earlier.
  • In any cluster node, use the srvctl utility to restart the database server and listener processes.
    For example:
    $ srvctl stop listener
    $ srvctl start listener
    
    $ srvctl stop scan_listener
    $ srvctl start scan_listener
    
    $ srvctl stop database -d db_name 
    $ srvctl start database -d db_name

21.10.7 Step 7: Test the Cluster Node Configuration

To test the cluster node configuration, you can create a connect descriptor for the node and then try to connect to this node.

  1. In any cluster node, create a connect descriptor in the tnsnames.ora file that uses the scan listener TCPS endpoint.
    For example, for a TCPS endpoint called dbssl:
    DBSSL =
      (DESCRIPTION =
        (ADDRESS = (PROTOCOL = TCPS)(HOST = scan_name)(PORT = port_2))
        (CONNECT_DATA =
          (SERVER = DEDICATED)
          (SERVICE_NAME = service_name)
        )
      )
  2. Use SQL*Plus to try to connect to this TCPS endpoint.
    For example:
    sqlplus user_name/@dbssl
    Enter password: password

21.10.8 Step 8: Test the Remote Client Configuration

After you have tested the wallet on the Oracle Real Applications (Oracle RAC) cluster nodes, you area ready to test the remote client configuration.

  1. In every remote client sqlnet.ora file on the cluster node, define a wallet directory.
    WALLET_LOCATION =
      (SOURCE =
        (METHOD = FILE)
        (METHOD_DATA =
          (DIRECTORY = wallet_file_location)
        )
      )
  2. Move the client wallet that you created earlier, when you created the SSL wallets and certificates, to the client wallet directory.
    $ wallet create -wallet wallet_file_location -auto_login
    Enter wallet password: password

    The wallet_file_location should have an ewallet.p12 file and a cwallet.sso file.

  3. In the tnsnames.ora file, create a connect descriptor that uses the scan listener TCPS endpoint.
    For example:
    DBSSL =
      (DESCRIPTION =
        (ADDRESS = (PROTOCOL = TCPS)(HOST = scan_name)(PORT = port_2))
        (CONNECT_DATA =
          (SERVER = DEDICATED)
          (SERVICE_NAME = service_name)
        )
      )
  4. Use SQL*Plus to try to connect to this TCPS endpoint.
    For example:
    sqlplus user_name/@dbssl
    Enter password: password

21.11 Configuring Transport Layer Security for Client Authentication and Encryption Using Microsoft Certificate Store

To perform this configuration with Microsoft Certificate Store (MCS), you use the orapki command-line tool to generate certificates and manipulate the Oracle wallets.

21.11.1 About Configuring Transport Layer Security for Client Authentication and Encryption Using Microsoft Certificate Store

This type of configuration is the foundation of the Common Access Cards and PIV cards authentication.

As long as the software libraries that are delivered with the Common Access Cards and PIV cards are capable of transparently loading the necessary certificates into the Microsoft Certificate Store, then the Transport Layer Security (TLS) authentication that you configure will be transparently performed.

It is important to note that all the signing certificates of the user certificate that is loaded to the PIV card must be manually loaded into the server's wallet as part of the TLS configuration at the server level.

21.11.2 Step 1: Create and Configure the Server Wallet

You must use orapki to create a server wallet and the server's self-signed certificate.

  1. Log in to the Oracle Database server.
  2. Create a directory for the server wallet.
    For example:
    mkdir /home/oracle/wallet_tls/server
    
  3. Go to this directory.
    cd /home/oracle/wallet_tls/server
    
  4. Create the server wallet.
    orapki wallet create -wallet . -auto_login -pwd password
  5. Check the directory.
    For example:
    ls -la

    Output similar to the following appears:

    total 16
    drwxr-xr-x. 2 oracle oinstall 4096 Oct 28 07:18 .
    drwxr-xr-x. 6 oracle oinstall 4096 Oct 28 07:17 ..
    -rw-------. 1 oracle oinstall 120 Oct 28 07:18 cwallet.sso
    -rw-rw-rw-. 1 oracle oinstall 0 Oct 28 07:18 cwallet.sso.lck
    -rw-------. 1 oracle oinstall 75 Oct 28 07:18 ewallet.p12
    -rw-rw-rw-. 1 oracle oinstall 0 Oct 28 07:18 ewallet.p12.lck
    
  6. Create the server's self-signed certificate.
    orapki wallet add -wallet . -dn "cn=server" -self_signed -keysize 2048 -sign_alg sha256 -validity 365 -pwd password

21.11.3 Step 2: Create and Configure the Client Wallet

You must use orapki to create a client wallet and a certificate request.

  1. Log in to the Oracle Database client.
  2. Create a directory for the client wallet.
    For example:
    mkdir /home/oracle/wallet_tls/client
    
  3. Go to this directory.
    cd /home/oracle/wallet_tls/client
    
  4. Create the client wallet.
    orapki wallet create -wallet . -auto_login -pwd password
  5. Create a request for a user certificate and export the request.
    orapki wallet add -wallet . -dn "cn=client" -keysize 2048 -sign_alg sha256 -pwd password
    orapki wallet export -wallet . -dn "cn=client" -request req.txt -pwd password
  6. Copy the certificate request from the client directory to the server directory.
    For example:
    cp req.txt ../server/
    cd ../server/
  7. Sign the certificate of the client and also export server's CA certificate.
    For example:
    orapki cert create -wallet . -request req.txt -cert sign.txt -validity 1000 -pwd password
    orapki wallet export -wallet . -dn "cn=server" -cert server.txt
    cp server.txt ../client
    cp sign.txt ../client
    orapki wallet add -wallet . -trusted_cert -cert server.txt -pwd password
    orapki wallet add -wallet . -user_cert -cert sign.txt -pwd password
    cp sign.txt server.txt ../client/
    cd ../client

21.11.4 Step 3: Create an External User in the Oracle Database

You must create an external user to be used with the client and server connection.

  1. As a user who can create users and grant them privileges, log in to the PDB that will use this external user account.
  2. Create the external user.
    For example:
    CREATE USER tlsuser IDENTIFIED EXTERNALLY AS 'cn=client';
  3. Grant this account the CONNECT privilege.
    GRANT CONNECT TO tlsuser;

21.11.5 Step 4: Configure the Server listener.ora File

Next, you must check and then restart the server listener.ora file.

  1. Log in to the Oracle Database server.
  2. Check the server listener.ora file to ensure that it is correctly configured.
    For example:
     cat /u01/app/oracle/product/release/dbhome_1/network/admin/listener.ora

    Output similar to the following appears:

    LISTENERBOS =
         (DESCRIPTION_LIST =
           (DESCRIPTION =
             (ADDRESS = (PROTOCOL = TCP)(HOST = domain.com)(PORT = 1529))
            )
           (DESCRIPTION =
             (ADDRESS = (PROTOCOL = TCPS)(HOST = domain.com)(PORT = 1530))
             )
           )
    WALLET_LOCATION =
          (SOURCE =
            (METHOD = File)
              (METHOD_DATA =
               (DIRECTORY = /home/oracle/wallet_tls/server))
  3. Restart the listener and check if the database is registered to this listener.
    su - oracle
    ./lsnrctl start

    Output similar to the following appears:

    Listener Parameter File /u01/app/oracle/product/release/dbhome_1/network/admin/listener.ora
    Listener Log File /u01/app/oracle/diag/tnslsnr/service/instance/alert/log.xml
    Listening Endpoints Summary...
    (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=domain.com)(PORT=1523)))
    (DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=domain.com)(PORT=1525)))
      Services Summary...
       Service "service" has 1 instance(s).
        Instance "instance", status READY, has 1 handler(s) for this service...
       Service "serviceDB" has 1 instance(s).
        Instance "instance", status READY, has 1 handler(s) for this service...
     The command completed successful

21.11.6 Step 5: Configure the Server sqlnet.ora File

You must ensure that the sqlnet.ora file points to the server wallet that you created earlier.

  1. Log in to the Oracle Database server.
  2. Check the sqlnet.ora file to ensure that it points to the server wallet.
    For example:
    NAMES.DIRECTORY_PATH=(TNSNAMES)
    SQLNET.AUTHENTICATION_SERVICES=(BEQ,TCPS)
    SSL_CLIENT_AUTHENTICATION = TRUE 
    WALLET_LOCATION =
     (SOURCE =
      (METHOD = FILE)
        (METHOD_DATA =
          (DIRECTORY = /home/oracle/wallet_tls/server)
        )
    )
    

21.11.7 Step 6: Import the Client Wallet into the Microsoft Certificate Store

You must use the Microsoft Management Console (MMC) to perform this import operation.

  1. Start the MMC (mmc.exe).
  2. Select File, then add/remove snap-in.
  3. Select Certificates, then Add.
  4. Select My user account, then Finish, and then OK.
  5. Go to the Console Root, then Certificates Current User, then Personal, then Certificates.
  6. Right-click All Tasks, then select Import, then Next, then Browse.
  7. Select the certificate file that contains the certificate needed for the connection (for example, ewallet.p12).
  8. Select Open, then Next.
  9. Enter the wallet password.
  10. Select the Mark this as exportable checkbox.
  11. Select the Include all extended properties checkbox.
  12. Select Place all certificates in the following store: Personal.
  13. Select Next, then Finish.
  14. Ensure that the client's certificate was added to the MY store, by going to Console Root, and then selecting Certificates Current User, then Personal, then Certificates.
  15. Ensure that the CA certificates were added to the ROOT store by going to Console Root, and then selecting Certificates Current User, then Trusted Root Certification Authorities, then Certificates.

21.11.8 Step 7: Configure the Client sqlnet.ora File

You must configure the client sqlnet.ora file to use Microsoft Certificate Store for the client wallet.

  1. Log in to the Oracle Database client.
  2. Check the client side sqlnet.ora file.
    For example:
    WALLET_LOCATION = (SOURCE = (METHOD=MCS))

21.11.9 Step 8: Configure the Oracle Database

In the Oracle database, configure the OS_AUTHENT_PRE parameter.

  1. Log in SQL*Plus on the Oracle Database server as a user who has the ALTER SYSTEM system privilege.
  2. Set the OS_AUTHENT_PRE parameter.
    ALTER SYSTEM SET OS_AUTHENT_PREFIX='' SCOPE=SPFILE;
  3. Restart the database instance.

21.11.10 Step 9: Test the Client and Server Connection

After you complete the Microsoft Certificate Store configuration, you should test the and server connection.

  1. To verify that the MCS is used for the TLS connection, enable the client trace by adding the following lines in the client's sqlnet.ora file.
    trace_level_client=16
    trace_directory_client=trace_directory
    DIAG_ADR_ENABLED=OFF
  2. Make a connection to the server using SQL*Plus and then ensure that the certificates are loaded successfully from MCS.
    nztwOpenWallet: [enter]
    nztwOpenWallet: WRL mcs:, type = 24
    nztwOpenWallet: Loading the EXTKS provider for MCS type wallet
    nztwOpenWallet: [exit] OK

21.12 Certificate Validation with Certificate Revocation Lists

Oracle provides tools that enable you to validate certificates using certificate revocation lists.

21.12.1 About Certificate Validation with Certificate Revocation Lists

The process of determining whether a given certificate can be used in a given context is referred to as certificate validation.

Certificate validation includes determining that the following takes place:

  • A trusted certificate authority (CA) has digitally signed the certificate

  • The certificate's digital signature corresponds to the independently-calculated hash value of the certificate itself and the certificate signer's (CA's) public key

  • The certificate has not expired

  • The certificate has not been revoked

The Transport Layer Security network layer automatically performs the first three validation checks, but you must configure certificate revocation list (CRL) checking to ensure that certificates have not been revoked. CRLs are signed data structures that contain a list of revoked certificates. They are usually issued and signed by the same entity who issued the original certificate.

21.12.2 What CRLs Should You Use?

You should have CRLs for all of the trust points that you honor.

The trust points are the trusted certificates from a third party identity that is qualified with a level of trust.

Typically, the certificate authorities you trust are called trust points.

21.12.3 How CRL Checking Works

Oracle Database checks the certificate revocation status against CRLs.

These CRLs are located in file system directories, Oracle Internet Directory, or downloaded from the location specified in the CRL Distribution Point (CRL DP) extension on the certificate.

Typically, CRL definitions are valid for a few days. If you store your CRLs on the local file system or in the directory, then you must update them regularly. If you use a CRL Distribution Point (CRL DP), then CRLs are downloaded each time a certificate is used, so there is no need to regularly refresh the CRLs.

The server searches for CRLs in the following locations in the order listed. When the system finds a CRL that matches the certificate CA's DN, it stops searching.

  1. Local file system

    The system checks the sqlnet.ora file for the SSL_CRL_FILE parameter first, followed by the SSL_CRL_PATH parameter. If these two parameters are not specified, then the system checks the wallet location for any CRLs.

    Note: if you store CRLs on your local file system, then you must use the orapki utility to periodically update them (for example, renaming CRLs with a hash value for certificate validation).

  2. Oracle Internet Directory

    If the server cannot locate the CRL on the local file system and directory connection information has been configured in an ldap.ora file, then the server searches in the directory. It searches the CRL subtree by using the CA's distinguished name (DN) and the DN of the CRL subtree.

    The server must have a properly configured ldap.ora file to search for CRLs in the directory. It cannot use the Domain Name System (DNS) discovery feature of Oracle Internet Directory. Also note that if you store CRLs in the directory, then you must use the orapki utility to periodically update them.

  3. CRL DP

    If the CA specifies a location in the CRL DP X.509, version 3, certificate extension when the certificate is issued, then the appropriate CRL that contains revocation information for that certificate is downloaded. Currently, Oracle Database supports downloading CRLs over LDAP.

    Note the following:

    • For performance reasons, only user certificates are checked.

    • Oracle recommends that you store CRLs in the directory rather than the local file system.

21.12.4 Configuring Certificate Validation with Certificate Revocation Lists

You can edit the sqlnet.ora file to configure certificate validation with certificate revocation lists.

21.12.4.1 About Configuring Certificate Validation with Certificate Revocation Lists

The SSL_CERT_REVOCATION parameter must be set to REQUIRED or REQUESTED in the sqlnet.ora file to enable certificate revocation status checking.

The SSL_CERT_REVOCATION parameter must be set to REQUIRED or REQUESTED in the sqlnet.ora file to enable certificate revocation status checking.

By default this parameter is set to NONE indicating that certificate revocation status checking is turned off.

Note:

If you want to store CRLs on your local file system or in Oracle Internet Directory, then you must use the command line utility, orapki, to rename CRLs in your file system or upload them to the directory.

21.12.4.2 Enabling Certificate Revocation Status Checking for the Client or Server

You can enable certificate the revocation status checking for a client or a server.

  1. Log in to the Oracle Database server.
  2. Modify the SSL_CERT_REVOCATION parameter in the sqlnet.ora file.
    SSL_CERT_REVOCATION=value

    In this specification, value can be either of the following settings:

    • required requires certificate revocation status checking. The TLS connection is rejected if a certificate is revoked or no CRL is found. TLS connections are accepted only if it can be verified that the certificate has not been revoked.
    • requested performs certificate revocation status checking if a CRL is available. The TLS connection is rejected if a certificate is revoked. TLS connections are accepted if no CRL is found or if the certificate has not been revoked. For performance reasons, only user certificates are checked for revocation.
  3. If CRLs are stored on your local file system, then set one or both of the following sqlnet.ora parameters that specify where they are stored.
    • SSL_CRL_PATH sets the path to the directory where CRLs are stored. If you omit this setting, then the default is the wallet directory. Both DER-encoded (binary format) and PEM-encoded (BASE64) CRLs are supported. If you want to store CRLs in a local file system directory, then you must use the orapki utility to rename them so the system can locate them.
    • SSL_CRL_FILE sets the path to a comprehensive CRL file (where PEM-encoded (BASE64) CRLs are concatenated in order of preference in one file). Ensure that the file is present in the specified location, or else the application will not be able to start.
  4. If you want to fetch CRLs from Oracle Internet Directory, then edit the ldap.ora file to include the directory server and port information.

    When configuring your ldap.ora file, you should specify only a non-TLS port for the directory. CRL download is done as part of the TLS protocol, and making a TLS connection within a TLS connection is not supported.

    Oracle Database CRL functionality will not work if the Oracle Internet Directory non-TLS port is disabled.

  5. Repeat these steps for the Oracle Database client sqlnet.ora file.
21.12.4.3 Disabling Certificate Revocation Status Checking

You can disable certificate revocation status checking.

  1. Log in to the Oracle Database server.
  2. Modify the SSL_CERT_REVOCATION parameter in the sqlnet.ora file as follows:
    SSL_CERT_REVOCATION=NONE
  3. Repeat this step for the Oracle Database client.

21.12.5 Certificate Revocation List Management

Certificate revocation list management entails ensuring that the CRLs are the correct format before you enable certificate revocation checking.

21.12.5.1 About Certificate Revocation List Management

Oracle Database provides a command-line utility, orapki, that you can use to manage certificates.

Before you can enable certificate revocation status checking, you must ensure that the CRLs you receive from the CAs you use are in a form (renamed with a hash value) or in a location (uploaded to the directory) where your computer can use them.

You can also use LDAP command-line tools to manage CRLs in Oracle Internet Directory.

Note:

CRLs must be updated at regular intervals (before they expire) for successful validation. You can automate this task by using orapki commands in a script

21.12.5.2 Displaying orapki Help for Commands That Manage CRLs

You can display all the orapki commands that are available for managing CRLs.

  • To display all the orapki available CRL management commands and their options, enter the following at the command line:

    orapki crl help
    

Note:

Using the -summary, -complete, or -wallet command options is always optional. A command will still run if these command options are not specified.

21.12.5.3 Renaming CRLs with a Hash Value for Certificate Validation

When the system validates a certificate, it must locate the CRL issued by the CA who created the certificate.

The system locates the appropriate CRL by matching the issuer name in the certificate with the issuer name in the CRL.

When you specify a CRL storage location for the Certificate Revocation Lists Path field in Oracle Net Manager, which sets the SSL_CRL_PATH parameter in the sqlnet.ora file, use the orapki utility to rename CRLs with a hash value that represents the issuer's name. Creating the hash value enables the server to load the CRLs.

On UNIX operating systems, orapki creates a symbolic link to the CRL. On Windows operating systems, it creates a copy of the CRL file. In either case, the symbolic link or the copy created by orapki are named with a hash value of the issuer's name. Then when the system validates a certificate, the same hash function is used to calculate the link (or copy) name so the appropriate CRL can be loaded.

  • Depending on the operating system, enter one of the following commands to rename CRLs stored in the file system:

    • To rename CRLs stored in UNIX file systems:

      orapki crl hash -crl crl_filename [-wallet wallet_location] -symlink crl_directory [-summary]
      
    • To rename CRLs stored in Windows file systems:

      orapki crl hash -crl crl_filename [-wallet wallet_location] -copy crl_directory [-summary]

In this specification, crl_filename is the name of the CRL file, wallet_location is the location of a wallet that contains the certificate of the CA that issued the CRL, and crl_directory is the directory where the CRL is located.

Using -wallet and -summary are optional. Specifying -wallet causes the tool to verify the validity of the CRL against the CA's certificate prior to renaming the CRL. Specifying the -summary option causes the tool to display the CRL issuer's name.

21.12.5.4 Uploading CRLs to Oracle Internet Directory

Publishing CRLs in the directory enables CRL validation throughout your enterprise, eliminating the need for individual applications to configure their own CRLs.

All applications can use the CRLs stored in the directory where they can be centrally managed, greatly reducing the administrative overhead of CRL management and use. The user who uploads CRLs to the directory by using orapki must be a member of the directory group CRLAdmins (cn=CRLAdmins,cn=groups,%s_OracleContextDN%). This is a privileged operation because these CRLs are accessible to the entire enterprise. Contact your directory administrator to get added to this administrative directory group.

  • To upload CRLs to the directory, enter the following at the command line:

    orapki crl upload -crl crl_location -ldap hostname:ssl_port -user username [-wallet wallet_location] [-summary]
    

    In this specification, crl_location is the file name or URL where the CRL is located, hostname and ssl_port (TLS port with no authentication) are for the system on which your directory is installed, username is the directory user who has permission to add CRLs to the CRL subtree, and wallet_location is the location of a wallet that contains the certificate of the CA that issued the CRL.

Using -wallet and -summary are optional. Specifying -wallet causes the tool to verify the validity of the CRL against the CA's certificate prior to uploading it to the directory. Specifying the -summary option causes the tool to print the CRL issuer's name and the LDAP entry where the CRL is stored in the directory.

The following example illustrates uploading a CRL with the orapki utility:

orapki crl upload -crl /home/user1/wallet/crldir/crl.txt -ldap host1.example.com:3533 -user cn=orcladmin

Note:

  • The orapki utility will prompt you for the directory password when you perform this operation.

  • Ensure that you specify the directory SSL port on which the Diffie-Hellman-based TLS server is running. This is the TLS port that does not perform authentication. Neither the server authentication nor the mutual authentication TLS ports are supported by the orapki utility.

21.12.5.5 Listing CRLs Stored in Oracle Internet Directory

You can display a list of all CRLs stored in the directory with orapki, which is useful for browsing to locate a particular CRL to view or download to your local computer.

This command displays the CA who issued the CRL (Issuer) and its location (DN) in the CRL subtree of your directory.

  • To list CRLs in Oracle Internet Directory, enter the following at the command line:

    orapki crl list -ldap hostname:ssl_port

    where the hostname and ssl_port are for the system on which your directory is installed. Note that this is the directory SSL port with no authentication as described in the preceding section.

21.12.5.6 Viewing CRLs in Oracle Internet Directory

Oracle Internet Directory CRLS are available in a summarized format; you also can request a listing of revoked certificates for a CRL.

You can view CRLs stored in Oracle Internet Directory in a summarized format or you can request a complete listing of revoked certificates for a CRL. A summary listing provides the CRL issuer's name and its validity period. A complete listing provides a list of all revoked certificates contained in the CRL.
  • To view a summary listing of a CRL in Oracle Internet Directory, enter the following at the command line:
    orapki crl display -crl crl_location [-wallet wallet_location] -summary
    

    In this specification, crl_location is the location of the CRL in the directory. It is convenient to paste the CRL location from the list that displays when you use the orapki crl list command.

    To view a list of all revoked certificates contained in a specified CRL, which is stored in Oracle Internet Directory, you can enter the following at the command line:

    orapki crl display -crl crl_location [-wallet wallet_location] -complete

    For example, the following orapki command:

    orapki crl display -crl $T_WORK/pki/wlt_crl/nzcrl.txt -wallet $T_WORK/pki/wlt_crl -complete
    

    produces the following output, which lists the CRL issuer's DN, its publication date, date of its next update, and the revoked certificates it contains:

    issuer = CN=root,C=us, thisUpdate = Sun Nov 16 10:56:58 PST 2003, nextUpdate = Mon Sep 30 11:56:58 PDT 2013, revokedCertificates = {(serialNo = 153328337133459399575438325845117876415, revocationDate - Sun Nov 16 10:56:58 PST 2003)}
    CRL is valid
    

    Using the -wallet option causes the orapki crl display command to validate the CRL against the CA's certificate.

    Depending on the size of your CRL, choosing the -complete option may take a long time to display.

    You can also use Oracle Directory Manager, a graphical user interface tool that is provided with Oracle Internet Directory, to view CRLs in the directory. CRLs are stored in the following directory location:

    cn=CRLValidation,cn=Validation,cn=PKI,cn=Products,cn=OracleContext
21.12.5.7 Deleting CRLs from Oracle Internet Directory

The user who deletes CRLs from the directory by using orapki must be a member of the directory group CRLAdmins.

  • To delete CRLs from the directory, enter the following at the command line:
    orapki crl delete -issuer issuer_name -ldap host:ssl_port -user username [-summary]

    In this specification, issuer_name is the name of the CA who issued the CRL, the hostname and ssl_port are for the system on which your directory is installed, and username is the directory user who has permission to delete CRLs from the CRL subtree. Ensure that this must be a directory SSL port with no authentication.

    Using the -summary option causes the tool to print the CRL LDAP entry that was deleted.

    For example, the following orapki command:

    orapki crl delete -issuer "CN=root,C=us" -ldap machine1:3500 -user cn=orcladmin -summary
    

    produces the following output, which lists the location of the deleted CRL in the directory:

    Deleted CRL at cn=root cd45860c.rN,cn=CRLValidation,cn=Validation,cn=PKI,cn=Products,cn=OracleContext

21.12.6 Troubleshooting CRL Certificate Validation

To determine whether certificates are being validated against CRLs, you can enable Oracle Net tracing.

When a revoked certificate is validated by using CRLs, then you will see the following entries in the Oracle Net tracing file without error messages logged between entry and exit:

nzcrlVCS_VerifyCRLSignature: entry
nzcrlVCS_VerifyCRLSignature: exit

nzcrlVCD_VerifyCRLDate: entry
nzcrlVCD_VerifyCRLDate: exit

nzcrlCCS_CheckCertStatus: entry
nzcrlCCS_CheckCertStatus: Certificate is listed in CRL
nzcrlCCS_CheckCertStatus: exit

Note:

Note that when certificate validation fails, the peer in the SSL handshake sees an ORA-29024: Certificate Validation Failure.

21.12.7 Oracle Net Tracing File Error Messages Associated with Certificate Validation

Oracle generates trace messages that are relevant to certificate validation.

These trace messages may be logged between the entry and exit entries in the Oracle Net tracing file. Oracle SSL looks for CRLs in multiple locations, so there may be multiple errors in the trace.

You can check the following list of possible error messages for information about how to resolve them.

CRL signature verification failed with RSA status

Cause: The CRL signature cannot be verified.

Action: Ensure that the downloaded CRL is issued by the peer's CA and that the CRL was not corrupted when it was downloaded. Note that the orapki utility verifies the CRL before renaming it with a hash value or before uploading it to the directory.

See Certificate Revocation List Management for information about using orapki for CRL management.

CRL date verification failed with RSA status

Cause: The current time is later than the time listed in the next update field. You should not see this error if CRL DP is used. The systems searches for the CRL in the following order:

  1. File system

  2. Oracle Internet Directory

  3. CRL DP

The first CRL found in this search may not be the latest.

Action: Update the CRL with the most recent copy.

CRL could not be found

Cause: The CRL could not be found at the configured locations. This will return error ORA-29024 if the configuration specifies that certificate validation is require.

Action: Ensure that the CRL locations specified in the configuration are correct by performing the following steps:

  1. Use Oracle Net Manager to check if the correct CRL location is configured. Refer to Configuring Certificate Validation with Certificate Revocation Lists

  2. If necessary, use the orapki utility to configure CRLs for system use as follows:

Oracle Internet Directory host name or port number not set

Cause: Oracle Internet Directory connection information is not set. Note that this is not an irrecoverable error. The search continues with CRL DP.

Action: If you want to store the CRLs in Oracle Internet Directory, then use Oracle Net Configuration Assistant to create and configure an ldap.ora file for your Oracle home.

Fetch CRL from CRL DP: No CRLs found

Cause: The CRL could not be fetched by using the CRL Distribution Point (CRL DP). This happens if the certificate does not have a location specified in its CRL DP extension, or if the URL specified in the CRL DP extension is incorrect.

Action: Ensure that your certificate authority publishes the CRL to the URL that is specified in the certificate's CRL DP extension.

Manually download the CRL. Then depending on whether you want to store it on your local file system or in Oracle Internet Directory, perform the following steps:

If you want to store the CRL on your local file system:

  1. Use Oracle Net Manager to specify the path to the CRL directory or file. Refer to Configuring Certificate Validation with Certificate Revocation Lists

  2. Use the orapki utility to configure the CRL for system use. Refer to Renaming CRLs with a Hash Value for Certificate Validation

If you want to store the CRL in Oracle Internet Directory:

  1. Use Oracle Net Configuration Assistant to create and configure an ldap.ora file with directory connection information.

  2. Use the orapki utility to upload the CRL to the directory. Refer to Uploading CRLs to Oracle Internet Directory

21.13 Allowing Certificates from Earlier Algorithms

You can use certificates that were associated with earlier deprecated (and weaker) algorithms by setting the ALLOWED_WEAK_CERT_ALGORITHMS sqlnet.ora parameter.

The ALLOWED_WEAK_CERT_ALGORITHMS allows you to explicitly enable earlier algorithms.. However, be aware that earlier algorithms are less secure than newer algorithms. This parameter replaces the ALLOW_MD5_CERTS and ALLOW_SHA1_CERTS parameters, which are deprecated starting in Oracle Database release 23ai.
  1. Log in to the database server or the client server.
  2. Edit the sqlnet.ora parameter file to include the ALLOWED_WEAK_CERT_ALGORITHMS parameter.

    You can specify MD5 or SHA1. If you want to specify both, then separate them with a comma. For example:

    ALLOWED_WEAK_CERT_ALGORITHMS = (MD5,SHA1)

    MD5 is disabled by default and SHA1 is enabled by default. The default location of the sqlnet.ora file is in the $ORACLE_HOME/network/admin directory.

21.14 Troubleshooting the Transport Layer Security Configuration

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

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 Oracle 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 (deprecated).

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 mkstore to turn the auto-login feature on for the wallet. Then save the wallet again. For example:

mkstore -wrl wallet_location -create wallet_name

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:

    Step 2E: Set the Client Transport Layer Security Cipher Suites (Optional) 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: Use mkstore to check the certificate's key usage. For example:

mkstore -wrl wallet_location -listCredential
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 SSL_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 to Configuring 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.