Prepare for Oracle Call Interface, ODBC, and JDBC OCI Connections with TLS Authentication

Preparing for any type of Oracle Call Interface (OCI) connection with TLS authentication requires the installation of client software, preparing a wallet file, and configuring certain files and environment variables.

Note:

See Update your Autonomous Database Instance to Allow both TLS and mTLS Authentication for information on allowing TLS connections.

This topic covers the steps to prepare an application to connect using TLS authentication. See Prepare for Oracle Call Interface, ODBC, and JDBC OCI Connections with Wallets (mTLS) for information on the steps to prepare for mTLS authentication with these connection types.

New Oracle Client Installation

The following steps assume Oracle client software has not already been installed on the client computer. If Oracle client software has already been installed and there is a working copy of sqlnet.ora, see Updating an Existing Oracle Client Installation.

Before making an Oracle Call Interface, ODBC, or JDBC OCI connection, do the following:

  1. Install Oracle Client software on your computer. Use either the full Oracle Database Client 11.2.0.4 (or higher) or the Oracle Instant Client 12.1.0.2 (or higher). The Instant Client contains the minimal software needed to make an Oracle Call Interface connection. The Instant Client 12.1.0.2 (or higher) is sufficient for most applications.

  2. Download a root CA wallet and store the wallet file in a secure folder on your client computer. See Download Root CA Wallet for TLS Authentication for more information.

  3. Edit your sqlnet.ora file replacing "?/network/admin" with the name of the folder containing the wallet and adding SSL_SERVER_DN_MATCH=yes.

    For example, edit sqlnet.ora as follows:

    WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="?/network/admin")))
    SSL_SERVER_DN_MATCH=yes

    The changed value on UNIX/Linux is:

    WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="/home/wallet1")))
    SSL_SERVER_DN_MATCH=yes
    

    The changed value on Windows is:

    WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="D:\\myapp\\wallet1")))
    SSL_SERVER_DN_MATCH=yes
    
  4. Create the TNS_ADMIN environment variable and set it to the location of the wallet file

    Use this environment variable to change the directory path of Oracle Net Services configuration files from the default location of ORACLE_HOME\network\admin to the location of the secure folder containing the wallet you created in Step 2. Set the TNS_ADMIN environment variable to the directory where the wallet files are, not to the wallet file itself.

    For example, on UNIX/Linux set TNS_ADMIN to the full path of the directory where you created the wallet:

    export TNS_ADMIN=/home/wallet1

    For example on Windows:

    set TNS_ADMIN=d:\myapp\wallet1

Connections with an HTTP Proxy

If the client is behind a firewall and your network configuration requires an HTTP proxy to connect to the internet, then perform the following steps to update the sqlnet.ora.

Note:

Connections through an HTTP proxy are only available with Oracle Client software version 12.2.0.1 or later.
  1. Add the following line to the sqlnet.ora file to enable connections through an HTTP proxy:

    SQLNET.USE_HTTPS_PROXY=on
  2. Add the HTTP proxy hostname and port to the connection definitions in tnsnames.ora. You need to add the https_proxy and https_proxy_port parameters in the address section of connection definitions. For example, the following sets the HTTP proxy to proxyhostname and the HTTP proxy port to 80; replace these values with your HTTP proxy information:

    ADB1_high =
           (description=
                 (address=
                       (https_proxy=proxyhostname)(https_proxy_port=80)(protocol=tcps)(port=1522)(host=adb.example.oraclecloud.com)
                 )
                 (connect_data=(service_name=adb1_high.adb.oraclecloud.com)
                 )
                 (security=(ssl_server_cert_dn="adb.example.oraclecloud.com,OU=Oracle BMCS US,O=Oracle Corporation,L=Redwood City,ST=California,C=US")
                 )
           )

Note:

Configuring sqlnet.ora and tnsnames.ora for the HTTP proxy may not be enough depending on your organization's network configuration and security policies. For example, some networks require a username and password for the HTTP proxy. In such cases contact your network administrator to open outbound connections to hosts in the oraclecloud.com domain using port 1522 without going through an HTTP proxy.

For more information on SQLNET.USE_HTTPS_PROXY, see Net Services Reference.

For information on HTTPS_PROXY and HTTPS_PROXY_PORT, see Protocol Address Section.

Updating an Existing Oracle Client Installation

If you have an existing Oracle Client installation, you already have sqlnet.ora and the TNS_ADMIN environment variable. In this case, do the following:

Update your sqlnet.ora file by adding the following:

WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="/home/wallet1")))