🔐 What's an Oracle wallet, anyway?

An Oracle wallet is a secure container that stores authentication and signing credentials. A common use of Oracle wallet is authenticating to an Oracle Database instance using mTLS, or secure and authenticated communication between the database client and database server.

For example, if I download a wallet from Autonomous Database it might look like this:

% tree /Wallet_MYDB
/Wallet_MYDB
├── cwallet.sso
├── ewallet.p12
├── ewallet.pem
├── keystore.jks
├── ojdbc.properties
├── README
├── sqlnet.ora
├── tnsnames.ora
└── truststore.jks

1 directory, 9 files

% tree /Wallet_MYDB
/Wallet_MYDB
├── cwallet.sso
├── ewallet.p12
├── ewallet.pem
├── keystore.jks
├── ojdbc.properties
├── README
├── sqlnet.ora
├── tnsnames.ora
└── truststore.jks

1 directory, 9 files

So, what’s in the wallet?

TLS certificates for secure network communication. ewallet.p12 is the PKCS12 keystore, and ewallet.pem is the pem-formatted keys and certificates.
tnsnames.ora contains your database’s TNS names. This doesn’t have to live in the same directory as your database wallet, but it’s often convenient to place them in the same location.
- You can think of a TNS name is an alias for a database connection string
sqlnet.ora contains plain-text configuration options for Oracle Net connectivity.
Java Keystore (JKS) containing private keys, digital certificates, and trusted CA certificates – used specifically for applications that require a JKS instead of a PKCS12 keystore.
ojdbc.properties file for specifying JDBC (Java Database Connectivity API) properties. You likely won’t need this if you’re not using Java/JKS.

At minimum, the cwallet.sso, ewallet.p12, and tnsnames.ora files are required for clients that use Oracle Instant Client. JDBC clients may require the ojdbc.properties and JKS files.

What’s the easiest way to experiment with an Oracle wallet?

Oracle Autonomous Database provides the easiest way to get started using mTLS authentication with Oracle wallet: see Oracle Database Free to get started with Autonomous Database.

Once you sign up for Oracle Cloud Instrastructure (OCI) and create an Always-Free Autonomous Database instance, you can download the database wallet using the OCI console:

Navigate to the Autonomous Database details page.

Click Database connection.

On the Database connection page select Instance Type for the Wallet type:

Click Download wallet.

In the Download wallet dialog, enter a wallet password in the Password field and confirm the password in the Confirm password field.

Click Download to save the wallet zip file.

Unzip the wallet to a location your database client can access.

How do database clients pick up the wallet certificates?

You may specify the wallet location in the database connection string, like with a JDBC connection string:

jdbc:oracle:thin:@${TNS_NAME}?TNS_ADMIN=${WALLET_DIR}

You can also supply the wallet location in the TNS name itself, within the tnsnames.ora file. To do this, within the security property, set the MY_WALLET_DIRECTORY parameter to the location of the database wallet on disk.
mydb_high = (description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1522)(host=adb.****.oraclecloud.com))
(connect_data=(service_name=****mydb_high.adb.oraclecloud.com))(security=(ssl_server_dn_match=yes)(MY_WALLET_DIRECTORY=/mydb)))

In either case (connection string or TNS name), the database client needs the directory containing the tnsnames.ora file, which is supplied using the TNS_ADMIN parameter, or as an environment variable if supported by the database client.

If TNS_ADMIN is incorrectly set, you’ll likely receive an ORA-12154 error from the database client.

References

Questions?

Leave me a comment or reach out on LinkedIn, and I’ll be happy to chat!

andersswanson.dev