TCPS support for cloud databases for OCI Database Management

August 25, 2022 | 9 minute read
Murtaza Husain
Director, Product Management - Management Cloud
Vignesh Ram Shankaran
Consulting Member of Technical Staff
Text Size 100%:

Earlier in April 2022, we released TCPS support for connecting and registering external databases in Oracle Cloud Infrastructure (OCI). We are now excited to announce that Oracle Cloud Infrastructure Database Management service (DBMS) also supports secure connections to cloud databases (Exadata Cloud Service, OCI VM/BM) using TCPS protocol. 

Key use cases for TCPS support for cloud database 

  • Option to connect to external and cloud databases using TCP and TCPS protocols
  • Support for Transport Layer Security (TLS) authentication via database wallet of your choice: Java Keystore or Public-Key Cryptography Standards (PKCS) #12
  • Support for database wallet as a secret integrated with OCI Vault service 

TCPS administration support details

TCPS support for cloud databases is now available on the Administration page under Managed Database/Enable Database Management pane. When enabling Database Management, you have the option of selecting either TCP or TCPS as the connectivity protocol to the cloud database. By default, TCP protocol is selected. To use Database Management with TCPS, the prerequisite would be to add a TCPS listener to the cloud database. This new listener can be used to talk to database via a secure channel.

TCPS setup to create a new database wallet

TCPS setup starts with the provisioning of a wallet on the database. This wallet is an encrypted file protected by a password and contains certificates that help establish a secure channel between the database and Database Management. As in any TLS connection there are two entities involved here, Database Management being the client and the database being the server.

Setting up the wallet involves the following steps:

  • Create a wallet on database i.e., server wallet
  • Create a wallet for Database Management i.e., client wallet
  • Exchange certificates between the wallets to establish mutual TLS
  • Update server sqlnet.ora with parameters for TLS connection
  • Update listener to add the TLS port

The server and client wallets can be created using an orapki command line utility which is available out-of-the-box.

Here’s detailed information on how to set up the wallet. If you’ve already configured the wallet and listener, then skip these steps and move to the next section

Create a server wallet

The server wallet, created on the database, will contain all the user certificates and trusted certificates required to verify any clients making a call to the database over the secure port.

  1. Create a tcps_wallets folder under /u01/app/oracle.
  2. Run the following command to create a server wallet in the tcps_wallet folder:

    orapki wallet create -wallet "/u01/app/oracle/tcps_wallet/serverwallet" -pwd <WALLET PASSWORD> -auto_login to create a serverwallet under tcps_wallet folder.
     
  3. Add a self-signed user certificate to the wallet using the following command:

    orapki wallet add -wallet "/u01/app/oracle/tcps_wallet/serverwallet" -pwd <WALLET PASSWORD> -dn "CN=DB-CA,O=MYORG,C=MYOFFICE" -keysize 2048 -self_signed -validity 3650

Note that the keysize can either be 512|1024|2048 bits. The Federal Information Processing Standards (FIPS) mandates key size of 2048 bits.

Now the sever wallet is created and you can run the following command to view/list the certificates added to the wallet: orapki wallet display -wallet "/u01/app/oracle/tcps_wallet/serverwallet". The wallet should look something like this:

Create a client wallet

The client wallet will contain the certificate that represents the client in the certificate exchange. Eventually, both the client and server wallet exchange certificates and establish the mutual TLS (mTLS). In this case the client wallet will be used by Database Management.

Note: The client wallet is required only if the database user wants to establish mTLS between Database Management and the database. If TLS is the only requirement, then creating a client wallet is not be required.

  1. Move to tcps_wallets folder under /u01/app/oracle.
  2. Run the following command to create a client wallet in the tcps_wallet folder:

    orapki wallet create -wallet "/u01/app/oracle/tcps_wallet/clientwallet" -pwd <WALLET PASSWORD> -auto_login to create a clientwallet under tcps_wallet folder
     
  3. Add a self-signed user certificate to the wallet using the following command:

orapki wallet add -wallet "/u01/app/oracle/tcps_wallet/clientwallet " -pwd <WALLET PASSWORD> -dn "CN=DEV-CA,O=MYORG,C=MYOFFICE" -keysize 2048 -self_signed -validity 3650

Note that the keysize can either be 512|1024|2048 bits. The Federal Information Processing Standards (FIPS) mandates key size of 2048 bits.

Now the client wallet is created and you can run the following command to view/list the certificates added to the wallet: orapki wallet display -wallet "/u01/app/oracle/tcps_wallet/clientwallet". The wallet should look something like this:

 

As you can see the commands for creating a client and server wallet are the same only difference being the wallet provided for adding the certificates.

Exchange certificates between the wallets

Once the client and server wallets are provisioned, the next step is to exchange certificates. This ensures that only the client that has the client wallet created in the previous step can talk to the database over the secure port. This is called mutual TLS.

  1. Run following commands to export client and server wallet certificates:
    1. Export server wallet: orapki wallet export -wallet "/u01/app/oracle/tcps_wallet/serverwallet" -pwd <WALLET PASSWORD> -dn "CN=DB-CA,O=MYORG,C=MYOFFICE" -cert /u01/app/oracle/tcps_wallet/server-certificate.crt
    2. Export client wallet: orapki wallet export -wallet "/u01/app/oracle/tcps_wallet/clientwallet" -pwd <WALLET PASSWORD> -dn "CN=DEV-CA,O=MYORG,C=MYOFFICE" -cert /u01/app/oracle/tcps_wallet/client-certificate.crt
  2. Run the following commands to trust each other’s certificates:
    1. Trust client cert in server wallet: orapki wallet add -wallet "/u01/app/oracle/tcps_wallet/serverwallet" -pwd <WALLET PASSWORD> -trusted_cert -cert client-certificate.crt
    2. Trust server cert in client wallet: orapki wallet add -wallet "/u01/app/oracle/tcps_wallet/clientwallet" -pwd <WALLET PASSWORD> -trusted_cert -cert server-certificate.crt

Update sqlnet.ora with parameters for TLS connection

As the next step, add the following entries in the $ORACLE_HOME/network/admin/sqlnet.ora file on the server.

# Location to the server wallet
WALLET_LOCATION =
(SOURCE =
(METHOD = FILE)
(METHOD_DATA =
(DIRECTORY = "/u01/app/oracle/tcps_wallet/serverwallet)
))
SQLNET.AUTHENTICATION_SERVICES = (TCPS,NTS,BEQ)

# Turn on Client Authentication to be able to establish mTLS
SSL_CLIENT_AUTHENTICATION = TRUE

# Setting this to true would make sure that native encryption would not interfere with TCPS
SQLNET. IGNORE_ANO_ENCRYPTION_FOR_TCPS=TRUE

Update listener to add the TLS port  

The final step of the setup is adding a listener for TLS. As in any network connection a new port needs to be introduced to handle the connection over this secure channel. For instance, 80 for HTTP and 443 for HTTPS.

  1. Open "$ORACLE_HOME/network/admin/listener.ora" and find an existing entry with key as LISTENER. Under the DESCRIPTION_LIST you should be able to find an existing entry for TCP.

    Text

Description automatically generated
    Copy this TCP entry and add a new entry to description block with the following changes:
    1. Change protocol to TCPS
    2. Change the port number to 2484 (or any available port on the database node).


       
  2. Add the wallet location to the listener.ora file.
    # Location to the server wallet
    WALLET_LOCATION =
    (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
    (DIRECTORY = "/u01/app/oracle/tcps_wallet/serverwallet)
    ))
     
  3. Run the following commands to restart the listener:
    1. lsnrctl stop (Stops the listener)
    2. lsnrctl start (Starts the listener)
    3. lsnrctl status (Check the starts of listener after restart)

After the listener is restarted, the TCPS entry should be displayed in the listener status output.

Details to be noted down for using TCPS

Now that TLS/TCPS is configured on the database the following details would be required when enabling Database Management with TCPS protocol:

  1. TCPS listener port number, which is 2824 in this case.
  2. Database wallet file: /u01/app/oracle/tcps_wallet/clientwallet/ewallet.p12.
  3. Wallet password used when creating the client wallet.
  4. Certificate Distinguished Name of the client certificate.

Enablement of Database Management Using TCPS protocol

Database Management can now be enabled from the OCI console with the protocol as TCPS. As part of the flow, you will be asked to provide the wallet details noted above if you select the protocol as TCPS.

To enable Database Management for the cloud databases:

  1. Open the navigation menu in the OCI console, click Observability & Management. Under Database Management, click Administration.
  2. On the left pane on the Administration page, select the compartment in which the cloud database resides and click Enable Database Management.
  3. On the Enable Database Management dialog, provide the details pertaining to the cloud database of interest and select the TCPS option as the connection protocol.