Setting Up Oracle Wallets for mTLS: A Complete Guide

In this post, we’ll dive into the real-world process of setting up Oracle wallets for secure mTLS connections using trusty tools like OpenSSL and orapki.

Need a quick setup? Check out BookStack Oracle Wallets for mTLS – Mingau says it’s worth it! 🐾

What is Mutual TLS?

A few days ago, I configured an Oracle wallet to establish mutual TLS (mTLS) connections for a client.

Mutual TLS is a more secure variation of TLS where both the client and the server authenticate each other using certificates. It’s widely used in environments where secure, authenticated communication is critical, such as APIs between internal services or business partners.

In this post, I’ll walk you through the steps I used to configure an Oracle wallet from an existing private key and certificates using OpenSSL and orapki. This method is especially useful when you’re provided with PEM-format certificates and keys and need to get them into a format Oracle can use.

Step 1: Generate a P12 File with OpenSSL

The first step is to combine the private key, public certificate, and the root CA into a single .p12 file (PKCS#12), which Oracle tools can import:

openssl pkcs12 -export \
    -in /u01/app/oracle/product/19.0.0/orcl/wallet/yourapi.domain.com.crt \
    -inkey /u01/app/oracle/product/19.0.0/orcl/wallet/yourapi.domain.com.key \
    -certfile /u01/app/oracle/product/19.0.0/orcl/wallet/rootca.crt \
    -out openssl.p12

You’ll be prompted to set a password for this file. Keep it handy, you’ll need it in the next steps.

Step 2: Create a Wallet with Auto Login

Use orapki to create the wallet directory and enable auto-login, which allows the Oracle DB to use the wallet without needing a password at runtime:

orapki wallet create \
    -wallet /u01/app/oracle/product/19.0.0/orcl/wallet \
    -pwd PASSWORD \
    -auto_login

Replace PASSWORD with your secure wallet password.

Step 3: Import the P12 File into the Wallet

Now, import the .p12 file you created using OpenSSL:

cd /u01/app/oracle/product/19.0.0/orcl/wallet
orapki wallet import_pkcs12 -wallet . -pkcs12file openssl.p12

This will extract the private key and certificates into the Oracle wallet format.

Step 4: Validate the Wallet Contents

Check that the wallet contains what you expect:

orapki wallet display -wallet /u01/app/oracle/product/19.0.0/orcl/wallet

You should see the subject and issuer for each certificate, including the trusted CA and the identity certificate.

Step 5: Test the HTTPS Connection from the Database

Finally, configure your Oracle session to use the wallet and test the mTLS connection using UTL_HTTP:

EXEC UTL_HTTP.set_wallet('file:/u01/app/oracle/product/19.0.0/orcl/wallet');

SELECT utl_http.request('https://yourapi.domain.com/api/') FROM dual;

If everything is working correctly, you should get a valid response from the API.

Conclusion

Setting up Oracle for mTLS can be tricky when starting with raw PEM-format certificates. But using OpenSSL to bundle your certs and orapki to manage the wallet makes the process a lot more manageable and even repeatable in production environments.

This post was reviewed and approved by Mingau, our Chief Information Security Officer (CISO) at Hexacats, who insists that all APIs must be paws-itively secure and that no certificate shall go unvalidated under her watch.

If your database doesn’t speak mTLS yet, just know: Mingau is judging you. 🐱