AWS Database Blog
Create Oracle Wallet for AWS DMS SSL connections using SQLcl
AWS Database Migration Service (AWS DMS) requires Oracle Wallet files as certificates when you activate SSL for database migrations to Amazon Relational Database Service (Amazon RDS) for Oracle. SQL Developer Command Line (Oracle SQLcl) provides a lightweight, Java-based alternative for creating and managing Oracle Wallets, including essential utilities such as orapki and mkstore. Using SQLcl provides a lightweight alternative to downloading the full Oracle Client software (approximately 1.2 GB), and typically completes the setup in fewer than 10 steps.
Using SQLcl, you can execute SQL and PL/SQL statements interactively or as a batch file. SQLcl provides inline editing, statement completion, command recall, and supports existing SQL*Plus scripts. You can download Oracle SQLcl from Oracle Technology Network
Amazon Corretto 21 Java version is compatible with Oracle utilities. This post uses Amazon Corretto 21 Java version for SQLcl configuration.
This post covers the following:
- Installing Oracle SQLcl and Java on an Amazon Linux 2023.
- Creating an Oracle Wallet and adding SSL certificates.
- Testing SSL connections to Amazon RDS for Oracle using the Oracle Wallet.
- Uploading the Wallet file to Amazon Simple Storage Service (Amazon S3).
- Importing the Wallet file as an AWS DMS certificate.
- Configuring the AWS DMS endpoint with Secure Socket Layer (SSL) mode, SSL port, and certificate for a successful test connection.
Prerequisites
Verify that the following are available before you begin:
- An Amazon Elastic Compute Cloud (Amazon EC2) instance with Amazon Linux 2023.
- Oracle Java 21 (Amazon Corretto 21).
- Oracle SQLcl package.
- Amazon RDS certificate bundle.
- EC2 instance must have virtual private cloud (VPC) connectivity to the RDS instance (including security group configuration).
- Confirm that the AWS Command Line Interface (AWS CLI) is available on the EC2 instance to run
aws s3 cpoperations. - Create a new IAM role, or use an existing one, for the EC2 service to allow access to Amazon S3. Then attach the role to your EC2 instance. For more information, see Attach an IAM role to an EC2 instance.
Note: SQLcl 26.x requires JDK 17 or 21. If the Java version is different, the SQLcl installation fails with the following error:
Verify your Java version before proceeding:
Implementation steps
The following sections walk through steps required to create an Oracle Wallet, configure SSL, and integrate it with AWS DMS. Each step builds on the previous one, so work through them in order.
1. Environment setup
Before installing SQLcl, prepare your EC2 instance and install Java version 17, 21, or later. Oracle SQLcl requires Java to run.
A. EC2 instance preparation
Complete the following preparation steps to get your EC2 instance ready for SQLcl installation. Confirming your working directory now prevents path-related errors in later steps.
- Launch an Amazon Linux 2023 EC2 instance.
- Connect to the instance using SSH.
- Verify your current working directory:
B. Java installation
Update the system packages and install Amazon Corretto 21. Amazon Corretto provides a certified, production-ready distribution of OpenJDK that Oracle utilities have tested extensively.
- Update system packages:
- Install Amazon Corretto 21:
- Verify the Java installation:
Expected output: The version string should show OpenJDK Corretto-21.
2. SQLcl installation and setup
With Java installed, download and extract Oracle SQLcl. The SQLcl package is a self-contained zip archive and requires no system-level installation. Extract it and run the included binary. The bin directory contains both the Unix shell script and a Windows batch file for launching SQLcl.
A. Download SQLcl
Run the following command to download the latest SQLcl package:
B. Extract SQLcl
Extract the archive and navigate to the bin directory:
C. Verify SQLcl installation
Run SQLcl in no-login mode to confirm it launches successfully and displays the copyright banner:
You should see the SQLcl copyright information and the SQL prompt. The following output confirms a working installation:
3. SSL certificate configuration
When you add the RDS certificates to the Oracle Wallet to establish a secure connection with Amazon RDS for Oracle, add each certificate individually, because the Amazon RDS certificate bundle contains multiple certificates in a single PEM file.
Adding the bundle directly to the wallet causes the DMS endpoint test connection to fail. Refer to the Troubleshooting section for the specific error message.
A. Download the Amazon RDS certificate bundle
Download the regional certificate bundle for your AWS Region. The following example uses the us-east-1 region bundle. Substitute the bundle URL for your target Region:
Note: This example uses us-east-1-bundle.pem for illustration purposes. You can use the certificate bundle for any supported AWS Region. Replace the URL with the bundle URL for your target region.
B. Split the certificate bundle into individual certificates
Use the following awk command to split the bundle into separate PEM files. This creates three files, each containing one certificate: cert.pem, cert1.pem, and cert2.pem:
4. Oracle Wallet creation and configuration
The Oracle Wallet is a secure storage container for SSL certificates. You create and manage it using the orapki utility included in SQLcl. The wallet uses auto-login mode, so Oracle tools can open it without prompting for a password. This is a requirement for automated processes like AWS DMS.
After creating the wallet and adding all three certificates, verify the wallet contents to confirm the configuration before proceeding.
A. Create the Oracle Wallet
Create the wallet directory, restrict its permissions, and then start SQLcl in no-login mode to create the wallet:
The following session shows creating the wallet directory within the sqlcl/bin directory:
Start SQLcl in no-login mode, then create the wallet:
Expected output: “Operation is successfully completed.” from Oracle PKI Tool Release 23.0.0.0.0.
B. Add certificates to the wallet
Add each of the three individual certificates to the wallet. All three certificates must be added for the DMS SSL connection to succeed:
C. Verify the wallet contents
Confirm that all three trusted certificates were successfully added:
The output should list three Trusted Certificates, as shown here:
After adding all certificates, the wallet directory contains the Oracle Wallet files created by the orapki utility:
5. Oracle network files configuration
Three Oracle network configuration files are required to direct SQLcl and JDBC connections to use the wallet for SSL. These files tell the Oracle client where to find the wallet, how to handle SSL authentication, and how to resolve the database alias used in the connection string. Create all three files inside the my_wallet directory.
A. Create sqlnet.ora
Navigate to the wallet directory and create sqlnet.ora. This file specifies the wallet location and SSL connection parameters:
Add the following content:
B. Create tnsnames.ora
Create tnsnames.ora to define the ORCL connection alias that uses the TCPS protocol and SSL port 2484. Replace the HOST value with your actual Amazon RDS for Oracle endpoint:
Add the following content, replacing the host and SID values with those for your RDS instance:
C. Create ojdbc.properties
Create ojdbc.properties to configure the JDBC driver to use the wallet when SQLcl establishes connections:
Add the following content:
After creating all three files, the wallet directory should contain the following files:
6. Environment configuration and testing
Before testing the SSL connection, set the TNS_ADMIN environment variable so that SQLcl and the Oracle JDBC driver can locate the wallet directory and the network configuration files.
Testing both a non-SSL (TCP) and SSL (TCPS) connection confirms that the wallet and network files are correctly configured. It also verifies that the SSL setup is working before you proceed to the AWS DMS integration.
Note: Navigate to the SQLcl bin directory before starting SQLcl in no-login mode:
A. Set the TNS_ADMIN environment variable
Export the TNS_ADMIN variable to point to your wallet directory:
B. Test the SSL (TCPS) connection
Connect using the ORCL alias defined in tnsnames.ora. This connection uses the TCPS protocol on port 2484 with the Oracle Wallet for certificate validation:
After connecting, run the following query to confirm the connection uses TCPS:
The following session transcript illustrates a successful SSL connection. The result tcps in the NETWORK_PROTOCOL column confirms that the wallet and network files are correctly configured:
7. AWS DMS integration
With the Oracle Wallet created and SSL connectivity confirmed, you can now configure AWS DMS to use the wallet for secure Oracle endpoint connections. This involves three steps:
- Upload the wallet file to Amazon S3.
- Import it as a certificate in the AWS DMS console.
- Configure a DMS endpoint that references the imported certificate.
For more information, see Configuring SSL encryption on Oracle and PostgreSQL endpoints in AWS DMS.
8. Verification and troubleshooting
Use the following checks and error resolutions if you encounter issues at any stage of the setup.
Verification steps
Verify configuration files: Confirm that sqlnet.ora, tnsnames.ora, and ojdbc.properties exist in the wallet directory:
Verify wallet permissions: Confirm that the cwallet.sso file is owned by the ec2-user and has read/write access:
Verify SSL connection protocol: After connecting through the ORCL alias, run the following query and confirm the result is tcps:
Verify TNS_ADMIN is set correctly: Confirm the environment variable points to the wallet directory before launching SQLcl:
Common errors and resolutions
Error: SSL handshake failure
If you observe the following error message during the SSL database connection, it indicates that the TLS_RSA_* cipher suites are disabled:
This error occurs because Java security settings disable TLS_RSA_* cipher suites by default. Since Amazon RDS for Oracle uses RSA certificates, you must use an SSL_RSA_* cipher suite. JDK 21 disables all TLS_RSA_* ciphers by default. The workaround is to re-enable the RSA ciphers in your JDK security configuration.
Workaround: Re-enable RSA cipher suites
- Find your java.security file.
- View the full jdk.tls.disabledAlgorithms value.
- Back up the java.security file before making any changes.
- Remove TLS_RSA_* from the disabled algorithms list.
- Verify the changes to your java.security file.
Find your java.security file:
See the full jdk.tls.disabledAlgorithms value (multi-line with \):
Back up the java.security file:
Remove TLS_RSA_* from Disabled Algorithms:
Verify the change:
Note: For RDS Oracle 19c and 21c versions, the Oracle SSL option is configured with the ‘SSL_RSA_WITH_AES_256_CBC_SHA’ cipher suite as the default [ TLS 1.0 or 1.2 ]. If you attempt to establish an SSL connection using SQLcl for Oracle 19c/21c with the default cipher suite, the connection fails with a “handshake_failure” message. Therefore, the preceding steps are required to establish the SSL connection to the RDS Oracle instance.
However, if you set any TLS_* cipher suite for Oracle 19c/21c, the SSL connection succeeds and you do not need to perform the preceding steps. The Oracle SSL option for the RDS Oracle 26ai version uses ‘TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384’ as the default cipher suite [ TLS 1.2 ], so the SSL connection from SQLcl succeeds without any error messages.
Error: DMS certificate validation failure
If the DMS endpoint test connection fails with the following message, the certificate bundle was added directly to the wallet instead of the individual certificate files:
To resolve this, remove the wallet and recreate it using the split certificate files (cert.pem, cert1.pem, cert2.pem) as described in Sections 3 and 4. Adding the bundle file (us-east-1-bundle.pem or global-bundle.pem) directly to the wallet causes this failure.
Error: ORA-17002: I/O error: IO Error (certificate_unknown) PKIX path building failed.
Resolution: SQLcl’s JDBC thin driver ignores the WALLET_LOCATION directive in sqlnet.ora, which only works for OCI or thick clients. Instead, it falls back to the JDK’s default truststore (cacerts), which lacks the Amazon RDS root CA. This causes a TLS handshake failure, even though TNS name resolution works because tnsnames.ora is read from TNS_ADMIN. SSL trust is handled by a separate layer.
To fix this, create an ojdbc.properties file in your TNS_ADMIN or wallet directory with:
This tells the JDBC thin driver to load the wallet (cwallet.sso) from that directory for SSL trust, so it can find the Amazon RDS CA certificate and complete the connection.
Error: ORA-17002: I/O error: IO Error (protocol_version) The server selected protocol version TLS10 is not accepted by client preferences [TLS13, TLS12], connect lapse 14 ms., Authentication lapse 0 ms.
Resolution: This error occurs because of a mismatch between the TLS version [ SQLNET.SSL_VERSION ] in the Oracle SSL option for RDS Oracle and the TLS version set for ‘SSL_VERSION’ in the sqlnet.ora file on the EC2 instance. Make sure that the TLS versions are set up appropriately.
Error: Connection timeout
If connections time out on port 2484, verify that the EC2 instance security group and the RDS instance security group both permit inbound TCP traffic on port 2484 from the DMS replication instance subnet.
Conclusion
In this post, we demonstrated how to install Java and Oracle SQLcl and create an Oracle Wallet using Oracle SQLcl. We also showed how to split the certificate bundle and configure it for secure SSL connections with AWS DMS endpoints to Amazon RDS for Oracle. Using SQLcl instead of the full Oracle Client reduces the tooling footprint while maintaining full wallet management capability through the included orapki and mkstore utilities.
After the SSL configuration is complete, configure AWS DMS replication tasks to begin your database migration using the SSL endpoint that you configured. We also recommend that you review best practices for successful SSL connections to Amazon RDS for Oracle for advanced SSL tuning and cipher suite recommendations. Additionally, explore the AWS DMS documentation for advanced migration configurations, including ongoing replication and task settings.
Finally, try implementing this solution in your development environment before applying it to production to validate the wallet and endpoint settings.