Connect Liquibase to Oracle Database with SSL/TLS

Last updated: March 24, 2026

This procedure configures Liquibase to connect to Oracle Database over TCPS (SSL/TLS), encrypting traffic between the client and server on port 2484. Server-side configuration—including the Oracle listener and server wallet—must be completed by your Oracle DBA before you begin. The client wallet stores the server’s trusted certificate.

Before you begin

Install Liquibase
Ensure Java is installed.
Install Oracle Client Tools (included with Oracle Database, Oracle Instant Client, or Oracle Database Client) to obtain the orapki utility used in this procedure.
Ask your Oracle DBA to configure the server listener for TCPS on port 2484 and provide you with the server’s certificate (in PEM or DER format) and the server certificate’s distinguished name (DN).

Procedure

Download Oracle JDBC drivers

All JARs are available from the Oracle JDBC Downloads page and Maven Central. Replace 21.13.0.0 with the latest 21.x release.

Download the following JARs from the Oracle JDBC Downloads page and place them in your lib/ directory.

ojdbc11.jar
oraclepki.jar
osdt_core.jar
osdt_cert.jar

wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/ojdbc11.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/oraclepki.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_core.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_cert.jar

mkdir -p lib
curl -L -o lib/ojdbc11.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"
curl -L -o lib/oraclepki.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
curl -L -o lib/osdt_core.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
curl -L -o lib/osdt_cert.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

Download the following JARs from the Oracle JDBC Downloads page and place them in your lib/ directory.

ojdbc11.jar
oraclepki.jar
osdt_core.jar
osdt_cert.jar

wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/ojdbc11.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/oraclepki.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_core.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_cert.jar

mkdir -p lib
curl -L -o lib/ojdbc11.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"
curl -L -o lib/oraclepki.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
curl -L -o lib/osdt_core.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
curl -L -o lib/osdt_cert.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

Create server wallet directory

Create the server wallet directory on your Oracle Database server. Be sure to:

Replace /path/to/oracle with your actual ORACLE_HOME path.
Replace ORCL with your Oracle SID.

# Set Oracle environment
export ORACLE_HOME=/path/to/oracle
export ORACLE_SID=ORCL

# Create wallet directory
mkdir -p $ORACLE_HOME/network/admin/wallet_server
chmod 750 $ORACLE_HOME/network/admin/wallet_server

Generate server certificate

Create an auto-login wallet and generate a self-signed certificate.

Be sure to:

Replace your-server.example.com with your Oracle server hostname. For example, db.company.com, oracle.example.org.
Replace YourOrg and US with your organization and country.
Use a certificate from a trusted CA instead of self-signed for production environments.

# Create auto-login wallet
orapki wallet create \
  -wallet $ORACLE_HOME/network/admin/wallet_server \
  -auto_login_only

# Generate self-signed certificate (valid for 10 years)
orapki wallet add \
  -wallet $ORACLE_HOME/network/admin/wallet_server \
  -auto_login_only \
  -dn "CN=your-server.example.com,O=YourOrg,C=US" \
  -keysize 2048 \
  -self_signed \
  -validity 3650

# Verify wallet
orapki wallet display \
  -wallet $ORACLE_HOME/network/admin/wallet_server \
  -complete

Export server certificate

Export the server certificate to share with Liquibase clients.

Be sure to:

Replace your-server.example.com with your Oracle server hostname.
Provide /tmp/server_cert.pem to the Liquibase client via scp or your organization's secure file transfer process.

# Export certificate for client
orapki wallet export \
  -wallet $ORACLE_HOME/network/admin/wallet_server \
  -dn "CN=your-server.example.com,O=YourOrg,C=US" \
  -cert /tmp/server_cert.pem

# Verify export
cat /tmp/server_cert.pem

Configure listener.ora

Add SSL/TLS listener configuration to $ORACLE_HOME/network/admin/listener.ora. Be sure to:

Replace $ORACLE_HOME/network/admin/wallet_server with the actual path to your server wallet directory.

# Standard TCP listener (existing)
LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC1))
      (ADDRESS = (PROTOCOL = TCP)(HOST = 0.0.0.0)(PORT = 1521))
    )
  )

# SSL/TLS listener (NEW)
SSL_LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCPS)(HOST = 0.0.0.0)(PORT = 2484))
    )
  )

# Wallet location for server certificate
WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = $ORACLE_HOME/network/admin/wallet_server)
    )
  )

# SSL authentication (server only, no client cert required)
SSL_CLIENT_AUTHENTICATION = FALSE

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC1))
      (ADDRESS = (PROTOCOL = TCP)(HOST = 0.0.0.0)(PORT = 1521))
      (ADDRESS = (PROTOCOL = TCPS)(HOST = 0.0.0.0)(PORT = 2484))
    )
  )

WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = $ORACLE_HOME/network/admin/wallet_server)
    )
  )

SSL_CLIENT_AUTHENTICATION = FALSE

# Standard TCP listener (existing)
LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC1))
      (ADDRESS = (PROTOCOL = TCP)(HOST = 0.0.0.0)(PORT = 1521))
    )
  )

# SSL/TLS listener (NEW)
SSL_LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCPS)(HOST = 0.0.0.0)(PORT = 2484))
    )
  )

# Wallet location for server certificate
WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = $ORACLE_HOME/network/admin/wallet_server)
    )
  )

# SSL authentication (server only, no client cert required)
SSL_CLIENT_AUTHENTICATION = FALSE

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC1))
      (ADDRESS = (PROTOCOL = TCP)(HOST = 0.0.0.0)(PORT = 1521))
      (ADDRESS = (PROTOCOL = TCPS)(HOST = 0.0.0.0)(PORT = 2484))
    )
  )

WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = $ORACLE_HOME/network/admin/wallet_server)
    )
  )

SSL_CLIENT_AUTHENTICATION = FALSE

Configure server sqlnet.ora

Add SSL/TLS configuration to $ORACLE_HOME/network/admin/sqlnet.ora.

Be sure to:

Replace $ORACLE_HOME/network/admin/wallet_server with the actual path to your server wallet directory.
Use modern TLS 1.2+ ciphers for JDBC compatibility.
Avoid older SSL 3.0 ciphers (SSL_RSA_WITH_3DES_EDE_CBC_SHA).
For Java/JDBC clients, prefer GCM ciphers. For example, TLS_RSA_WITH_AES_256_GCM_SHA384.

# Wallet location
WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = $ORACLE_HOME/network/admin/wallet_server)
    )
  )

# SSL/TLS Configuration
SQLNET.AUTHENTICATION_SERVICES = (TCPS, NTS, BEQ)
SSL_CLIENT_AUTHENTICATION = FALSE

# SSL Version (recommend TLS 1.2 or higher)
SSL_VERSION = 1.2

# Cipher Suites (modern, secure ciphers)
SSL_CIPHER_SUITES = (TLS_RSA_WITH_AES_256_GCM_SHA384, TLS_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA)

# Network Encryption (optional, adds extra security)
SQLNET.ENCRYPTION_SERVER = ACCEPTED
SQLNET.ENCRYPTION_TYPES_SERVER = (AES256, AES192, AES128)
SQLNET.CRYPTO_CHECKSUM_SERVER = ACCEPTED
SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER = (SHA256, SHA1)

Restart and verify Oracle listener

Restart the Oracle listener to apply the SSL/TLS configuration.

# Stop listener
lsnrctl stop

# Start listener
lsnrctl start

# Verify SSL listener is running
lsnrctl status

Look for (PROTOCOL=tcps)(HOST=0.0.0.0)(PORT=2484) in the output. This confirms the SSL listener is active.

Optionally, test the SSL handshake with OpenSSL.

Be sure to:

Replace your-server.example.com with your Oracle server hostname.

# Test SSL handshake (optional but recommended)
openssl s_client -connect your-server.example.com:2484 -showcerts

Create the client wallet

Create the client wallet directory and copy the server certificate from the Oracle server.

mkdir -p ~/liquibase-ssl

Copy the server certificate from the Oracle server to your client machine.

Be sure to:

Replace your_oracle_user with your Oracle server OS user. For example, oracle, opc
Replace your_oracle_server with the Oracle server hostname or IP.

scp your_oracle_user@your_oracle_server:/tmp/server_cert.pem ~/liquibase-ssl/

Create the auto-login wallet.

orapki wallet create -wallet ~/liquibase-ssl -auto_login_only

Add the server certificate as a trusted root.

orapki wallet add \
  -wallet ~/liquibase-ssl \
  -trusted_cert \
  -cert ~/liquibase-ssl/server_cert.pem \
  -auto_login_only

Verify the wallet contains the trusted certificate.

orapki wallet display -wallet ~/liquibase-ssl

Add database credentials to wallet

Add your database credentials to the wallet so Liquibase can connect without a username or password in the connection string.

Be sure to:

Replace your_tns_alias with the TNS alias from tnsnames.ora. For example, MYDB_SSL
Replace your_username with your database username.
Replace your_password with your database password.

mkstore -wrl ~/liquibase-ssl \
  -createCredential your_tns_alias your_username your_password

Verify the credentials were stored successfully.

mkstore -wrl ~/liquibase-ssl -listCredential

Download Oracle JDBC drivers

Download the Oracle JDBC and PKI JARs to your Liquibase lib/ directory. Replace 21.13.0.0 with the latest 21.x release.

Download the following JARs from the Oracle JDBC Downloads page and place them in your Liquibase lib/ directory.

ojdbc11.jar
oraclepki.jar
osdt_core.jar
osdt_cert.jar

wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/ojdbc11.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/oraclepki.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_core.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_cert.jar

mkdir -p lib
curl -L -o lib/ojdbc11.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"
curl -L -o lib/oraclepki.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
curl -L -o lib/osdt_core.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
curl -L -o lib/osdt_cert.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

Download the following JARs from the Oracle JDBC Downloads page and place them in your Liquibase lib/ directory.

ojdbc11.jar
oraclepki.jar
osdt_core.jar
osdt_cert.jar

wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/ojdbc11.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/oraclepki.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_core.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_cert.jar

mkdir -p lib
curl -L -o lib/ojdbc11.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"
curl -L -o lib/oraclepki.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
curl -L -o lib/osdt_core.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
curl -L -o lib/osdt_cert.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

Create tnsnames.ora

Create tnsnames.ora in your ~/liquibase-ssl/config/ directory. Be sure to:

Replace your-server.example.com with your Oracle server hostname.
Replace ORCL with your service name.
Replace CN=your-server.example.com,O=YourOrg,C=US with your server certificate's distinguished name.

# SSL/TLS Connection
MYDB_SSL =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = your-server.example.com)(PORT = 2484))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = ORCL)
    )
    (SECURITY =
      (SSL_SERVER_CERT_DN = "CN=your-server.example.com,O=YourOrg,C=US")
    )
  )

# Standard TCP Connection (for comparison)
MYDB =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = your-server.example.com)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = ORCL)
    )
  )

Create sqlnet.ora

Create sqlnet.ora in your wallet directory.

Be sure to:

Replace your_wallet_dir with the absolute path to your wallet directory. For example, /home/user/liquibase-ssl, /Users/name/liquibase-ssl

NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)

# Wallet location (absolute path required)
WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = your_wallet_dir)
    )
  )

SQLNET.WALLET_OVERRIDE = TRUE
DISABLE_OOB = TRUE

# SSL/TLS Configuration
SQLNET.AUTHENTICATION_SERVICES = (TCPS, NTS, BEQ)
SSL_CLIENT_AUTHENTICATION = FALSE
SSL_VERSION = 1.2
SSL_CIPHER_SUITES = (TLS_RSA_WITH_AES_256_GCM_SHA384, TLS_RSA_WITH_AES_256_CBC_SHA256)
SSL_SERVER_DN_MATCH = ON

# Network Encryption
SQLNET.ENCRYPTION_CLIENT = REQUESTED
SQLNET.ENCRYPTION_TYPES_CLIENT = (AES256, AES192, AES128)
SQLNET.CRYPTO_CHECKSUM_CLIENT = REQUESTED
SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT = (SHA256, SHA1)

Configure JDBC properties

Create ojdbc.properties in your wallet directory.

Be sure to:

Replace your_wallet_dir with the absolute path to your wallet directory. For example, /home/user/liquibase-ssl, /Users/name/liquibase-ssl

oracle.net.tns_admin=your_wallet_dir
oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=your_wallet_dir)))

Configure Liquibase

Create or update liquibase.properties. Use the TCPS TNS alias and include the PKI JARs on the classpath. No username or password is needed, because the credentials come from the wallet.

Be sure to:

Replace your_tns_alias with your TNS alias from tnsnames.ora. For example, MYDB_SSL, PROD_SSL
Replace your_lib_path/ with your absolute path to your JAR files directory. For example, /home/user/liquibase-ssl/lib/, /Users/name/liquibase-ssl/lib/

# liquibase.properties — Oracle SSL/TLS connection
liquibase.command.url=jdbc:oracle:thin:/@your_tns_alias
liquibase.command.changelogFile=db.changelog-master.xml
liquibase.classpath=your_lib_path/ojdbc11.jar:your_lib_path/oraclepki.jar:your_lib_path/osdt_core.jar:your_lib_path/osdt_cert.jar

Create sample changelog

Create ~/liquibase-ssl/changelog.xml.

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.0.xsd">

    <changeSet id="1" author="liquibase-test">
        <createTable tableName="test_table">
            <column name="id" type="NUMBER(10)">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="name" type="VARCHAR2(100)"/>
            <column name="created_date" type="TIMESTAMP"
                defaultValueComputed="CURRENT_TIMESTAMP"/>
        </createTable>
    </changeSet>

</databaseChangeLog>

Copy ojdbc.properties to root

Copy ojdbc.properties to the root directory so the JDBC driver can find it automatically.

cp ~/liquibase-ssl/config/ojdbc.properties ~/liquibase-ssl/

This allows the JDBC driver to discover TNS_ADMIN and wallet locations.

Set environment variables

Set the following environment variables before running Liquibase.

# Add to your shell profile (~/.bashrc or ~/.zshrc)
export TNS_ADMIN=~/liquibase-ssl/config

# Or set before running Liquibase:
export TNS_ADMIN=$PWD/config

Test your setup

Test 1: Verify Folder Structure

cd ~/liquibase-ssl
tree -L 2

Expected structure:

liquibase-ssl/
├── config/
│   ├── tnsnames.ora
│   ├── sqlnet.ora
│   ├── ojdbc.properties
│   └── server_cert.pem
├── wallet/
│   ├── cwallet.sso
│   └── cwallet.sso.lck
├── lib/
│   ├── ojdbc11.jar
│   ├── oraclepki.jar
│   ├── osdt_cert.jar
│   └── osdt_core.jar
├── liquibase.properties
├── changelog.xml
└── ojdbc.properties (copy of config/ojdbc.properties)

Test 2: Test SSL Port Connectivity

Be sure to:

Replace your-server.example.com with your Oracle server hostname.

# Test if SSL port is accessible
nc -zv your-server.example.com 2484

# Or use telnet
telnet your-server.example.com 2484

Expected: Connection succeeds.

Test 3: Test SSL Handshake

Be sure to:

Replace your-server.example.com with your Oracle server hostname.

openssl s_client -connect your-server.example.com:2484 -showcerts

Expected output (press Ctrl+C to exit):

SSL handshake has read XXXX bytes
...
Certificate:
    Subject: CN=your-server.example.com,O=YourOrg,C=US
...
Verify return code: 0 (ok) or 18 (self signed certificate)

Test 4: Verify Wallet Contents

# Check wallet
orapki wallet display -wallet ~/liquibase-ssl/wallet

# Check credentials
mkstore -wrl ~/liquibase-ssl/wallet -listCredential

Expected:

Trusted certificate listed
MYDB_SSL credential listed

Test 5: Test Liquibase Connection

cd ~/liquibase-ssl
export TNS_ADMIN=$PWD/config

# Test connection
liquibase status

Expected output:

Database is up to date
No changesets to deploy
Liquibase command 'status' was executed successfully.

Test 6: Apply Changes

# Apply the test changeset
liquibase update

# Verify
liquibase status

Expected:

Table created successfully
"Database is up to date"

Test 7: Verify Encryption

Connect to the database and check the session.

-- Check if connection is encrypted
SELECT network_service_banner
FROM v$session_connect_info
WHERE sid = (SELECT sid FROM v$mystat WHERE rownum = 1);

Expected output should include:

TCP/IP with SSL/TLS
AES256 Encryption service adapter
SHA256 Crypto-checksumming service