# Oracle Secure Sockets Layer To enable SSL encryption for an RDS for Oracle DB instance, add the Oracle SSL option to the option group associated with the DB instance. Amazon RDS uses a second port, as required by Oracle, for SSL connections. This approach allows both clear text and SSL-encrypted communication to occur at the same time between a DB instance and SQL\$1Plus. For example, you can use the port with clear text communication to communicate with other resources inside a VPC while using the port with SSL-encrypted communication to communicate with resources outside the VPC. **Note** You can use either SSL or Native Network Encryption (NNE) on the same RDS for Oracle DB instance, but not both. If you use SSL encryption, make sure to turn off any other connection encryption. For more information, see [Oracle native network encryption](Appendix.Oracle.Options.NetworkEncryption.md). SSL/TLS and NNE are no longer part of Oracle Advanced Security. In RDS for Oracle, you can use SSL encryption with all licensed editions of the following database versions: + Oracle Database 21c (21.0.0) + Oracle Database 19c (19.0.0) **Topics** + [ ## TLS versions for the Oracle SSL option ](#Appendix.Oracle.Options.SSL.TLS) + [ ## Cipher suites for the Oracle SSL option ](#Appendix.Oracle.Options.SSL.CipherSuites) + [ ## FIPS support ](#Appendix.Oracle.Options.SSL.FIPS) + [ ## Certificate compatibility with cipher suites ](#Appendix.Oracle.Options.SSL.CertificateCompatibility) + [ # Adding the SSL option ](Appendix.Oracle.Options.SSL.OptionGroup.md) + [ # Configuring SQL\$1Plus to use SSL with an RDS for Oracle DB instance ](Appendix.Oracle.Options.SSL.ClientConfiguration.md) + [ # Connecting to an RDS for Oracle DB instance using SSL ](Appendix.Oracle.Options.SSL.Connecting.md) + [ # Setting up an SSL connection over JDBC ](Appendix.Oracle.Options.SSL.JDBC.md) + [ # Enforcing a DN match with an SSL connection ](Appendix.Oracle.Options.SSL.DNMatch.md) + [ # Troubleshooting SSL connections ](Appendix.Oracle.Options.SSL.troubleshooting.md) ## TLS versions for the Oracle SSL option Amazon RDS for Oracle supports Transport Layer Security (TLS) versions 1.0 and 1.2. When you add a new Oracle SSL option, set `SQLNET.SSL_VERSION` explicitly to a valid value. The following values are allowed for this option setting: + `"1.0"` – Clients can connect to the DB instance using TLS version 1.0 only. For existing Oracle SSL options, `SQLNET.SSL_VERSION` is set to `"1.0"` automatically. You can change the setting if necessary. + `"1.2"` – Clients can connect to the DB instance using TLS 1.2 only. + `"1.2 or 1.0"` – Clients can connect to the DB instance using either TLS 1.2 or 1.0. ## Cipher suites for the Oracle SSL option Amazon RDS for Oracle supports multiple SSL cipher suites. By default, the Oracle SSL option is configured to use the `SSL_RSA_WITH_AES_256_CBC_SHA` cipher suite. To specify a different cipher suite to use over SSL connections, use the `SQLNET.CIPHER_SUITE` option setting. You can specify multiple values for `SQLNET.CIPHER_SUITE`. This technique is useful if you have database links between your DB instances and decide to update your cipher suites. The following table summarizes SSL support for RDS for Oracle in all editions of Oracle Database 19c and 21c. | Cipher suite (SQLNET.CIPHER\$1SUITE) | TLS version support (SQLNET.SSL\$1VERSION) | FIPS support | FedRAMP compliant | | --- | --- | --- | --- | | SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA (default) | 1.0 and 1.2 | Yes | No | | SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA256 | 1.2 | Yes | No | | SSL\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | 1.2 | Yes | No | | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | 1.2 | Yes | Yes | | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 | 1.2 | Yes | Yes | | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | 1.2 | Yes | Yes | | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 | 1.2 | Yes | Yes | | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | 1.2 | Yes | Yes | | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | 1.2 | Yes | Yes | | TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | 1.2 | Yes | Yes | | TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | 1.2 | Yes | Yes | ## FIPS support RDS for Oracle allows you to use the Federal Information Processing Standard (FIPS) standard for 140-2. FIPS 140-2 is a United States government standard that defines cryptographic module security requirements. You turn on the FIPS standard by setting `FIPS.SSLFIPS_140` to `TRUE` for the Oracle SSL option. When FIPS 140-2 is configured for SSL, the cryptographic libraries encrypt data between the client and the RDS for Oracle DB instance. Clients must use the cipher suite that is FIPS-compliant. When establishing a connection, the client and RDS for Oracle DB instance negotiate which cipher suite to use when transmitting messages back and forth. The table in [Cipher suites for the Oracle SSL option](#Appendix.Oracle.Options.SSL.CipherSuites) shows the FIPS-compliant SSL cipher suites for each TLS version. For more information, see [Oracle database FIPS 140-2 settings](https://docs.oracle.com/en/database/oracle/oracle-database/12.2/dbseg/oracle-database-fips-140-settings.html#GUID-DDBEB3F9-B216-44BB-8C18-43B5E468CBBB) in the Oracle Database documentation. ## Certificate compatibility with cipher suites RDS for Oracle supports both RSA and Elliptic Curve Digital Signature Algorithm (ECDSA) certificates. When you configure SSL for your DB instance, you must ensure that the cipher suites you specify in the `SQLNET.CIPHER_SUITE` option setting are compatible with the certificate type used by your DB instance. The following table shows the compatibility between certificate types and cipher suites: | Certificate type | Compatible cipher suites | Incompatible cipher suites | | --- | --- | --- | | RSA certificates (rds-ca-2019, rds-ca-rsa2048-g1, rds-ca-rsa4096-g1) | SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA256 SSL\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | | ECDSA certificates (rds-ca-ecc384-g1) | TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA256 SSL\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | When you specify multiple cipher suites in the `SQLNET.CIPHER_SUITE` option setting, make sure to include at least one cipher suite that is compatible with the certificate type used by your DB instance. If you're using an option group with multiple DB instances that have different certificate types, include at least one cipher suite for each certificate type. If you attempt to associate an option group with an SSL option that contains only cipher suites incompatible with the certificate type of a DB instance, the operation will fail with an error message indicating the incompatibility. # Adding the SSL option To use SSL, your RDS for Oracle DB instance must be associated with an option group that includes the `SSL` option. ## Console **To add the SSL option to an option group** 1. Create a new option group or identify an existing option group to which you can add the `SSL` option. For information about creating an option group, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create). 1. Add the `SSL` option to the option group. If you want to use only FIPS-verified cipher suites for SSL connections, set the option `FIPS.SSLFIPS_140` to `TRUE`. For information about the FIPS standard, see [FIPS support](Appendix.Oracle.Options.SSL.md#Appendix.Oracle.Options.SSL.FIPS). For information about adding an option to an option group, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption). 1. Create a new RDS for Oracle DB instance and associate the option group with it, or modify an RDS for Oracle DB instance to associate the option group with it. For information about creating an DB instance, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md). For information about modifying an DB instance, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md). ## AWS CLI **To add the SSL option to an option group** 1. Create a new option group or identify an existing option group to which you can add the `SSL` option. For information about creating an option group, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create). 1. Add the `SSL` option to the option group. Specify the following option settings: + `Port` – The SSL port number + `VpcSecurityGroupMemberships` – The VPC security group for which the option is enabled + `SQLNET.SSL_VERSION` – The TLS version that client can use to connect to the DB instance For example, the following AWS CLI command adds the `SSL` option to an option group named `ora-option-group`. **Example** For Linux, macOS, or Unix: ``` aws rds add-option-to-option-group --option-group-name ora-option-group \ --options 'OptionName=SSL,Port=2484,VpcSecurityGroupMemberships="sg-68184619",OptionSettings=[{Name=SQLNET.SSL_VERSION,Value=1.0}]' ``` For Windows: ``` aws rds add-option-to-option-group --option-group-name ora-option-group ^ --options 'OptionName=SSL,Port=2484,VpcSecurityGroupMemberships="sg-68184619",OptionSettings=[{Name=SQLNET.SSL_VERSION,Value=1.0}]' ``` 1. Create a new RDS for Oracle DB instance and associate the option group with it, or modify an RDS for Oracle DB instance to associate the option group with it. For information about creating an DB instance, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md). For information about modifying an DB instance, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md). # Configuring SQL\$1Plus to use SSL with an RDS for Oracle DB instance Before you can connect to an RDS for Oracle DB instance that uses the Oracle SSL option, you must configure SQL\$1Plus before connecting. **Note** To allow access to the DB instance from the appropriate clients, ensure that your security groups are configured correctly. For more information, see [Controlling access with security groups](Overview.RDSSecurityGroups.md). Also, these instructions are for SQL\$1Plus and other clients that directly use an Oracle home. For JDBC connections, see [Setting up an SSL connection over JDBC](Appendix.Oracle.Options.SSL.JDBC.md). **To configure SQL\$1Plus to use SSL to connect to an RDS for Oracle DB instance** 1. Set the `ORACLE_HOME` environment variable to the location of your Oracle home directory. The path to your Oracle home directory depends on your installation. The following example sets the `ORACLE_HOME` environment variable. ``` prompt>export ORACLE_HOME=/home/user/app/user/product/19.0.0/dbhome_1 ``` For information about setting Oracle environment variables, see [SQL\$1Plus environment variables](http://docs.oracle.com/database/121/SQPUG/ch_two.htm#SQPUG331) in the Oracle documentation, and also see the Oracle installation guide for your operating system. 1. Append `$ORACLE_HOME/lib` to the `LD_LIBRARY_PATH` environment variable. The following is an example that sets the LD\$1LIBRARY\$1PATH environment variable. ``` prompt>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib ``` 1. Create a directory for the Oracle wallet at `$ORACLE_HOME/ssl_wallet`. The following is an example that creates the Oracle wallet directory. ``` prompt>mkdir $ORACLE_HOME/ssl_wallet ``` 1. Download the certificate bundle .pem file that works for all AWS Regions and put the file in the ssl\$1wallet directory. For information, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md). 1. In the `$ORACLE_HOME/network/admin` directory, modify or create the `tnsnames.ora` file and include the following entry. ``` net_service_name = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCPS) (HOST = endpoint) (PORT = ssl_port_number) ) ) (CONNECT_DATA = (SID = database_name) ) (SECURITY = (SSL_SERVER_CERT_DN = "C=US,ST=Washington,L=Seattle,O=Amazon.com,OU=RDS,CN=endpoint") ) ) ``` 1. In the same directory, modify or create the sqlnet.ora file and include the following parameters. **Note** To communicate with entities over a TLS secured connection, Oracle requires a wallet with the necessary certificates for authentication. You can use Oracle's ORAPKI utility to create and maintain Oracle wallets, as shown in step 7. For more information, see [Setting up Oracle wallet using ORAPKI](https://docs.oracle.com/cd/E92519_02/pt856pbr3/eng/pt/tsvt/task_SettingUpOracleWalletUsingORAPKI.html) in the Oracle documentation. ``` WALLET_LOCATION = (SOURCE = (METHOD = FILE) (METHOD_DATA = (DIRECTORY = $ORACLE_HOME/ssl_wallet))) SSL_CLIENT_AUTHENTICATION = FALSE SSL_VERSION = 1.0 SSL_CIPHER_SUITES = (SSL_RSA_WITH_AES_256_CBC_SHA) SSL_SERVER_DN_MATCH = ON ``` **Note** You can set `SSL_VERSION` to a higher value if your DB instance supports it. 1. Run the following command to create the Oracle wallet. ``` prompt>orapki wallet create -wallet $ORACLE_HOME/ssl_wallet -auto_login_only ``` 1. Extract each certificate in the .pem bundle file into a separate .pem file using an OS utility. 1. Add each certificate to your wallet using separate `orapki` commands, replacing `certificate-pem-file` with the absolute file name of the .pem file. ``` prompt>orapki wallet add -wallet $ORACLE_HOME/ssl_wallet -trusted_cert -cert certificate-pem-file -auto_login_only ``` For more information, see [Rotating your SSL/TLS certificate](UsingWithRDS.SSL-certificate-rotation.md). # Connecting to an RDS for Oracle DB instance using SSL After you configure SQL\$1Plus to use SSL as described previously, you can connect to the RDS for Oracle DB instance with the SSL option. Optionally, you can first export the `TNS_ADMIN` value that points to the directory that contains the tnsnames.ora and sqlnet.ora files. Doing so ensures that SQL\$1Plus can find these files consistently. The following example exports the `TNS_ADMIN` value. ``` export TNS_ADMIN=${ORACLE_HOME}/network/admin ``` Connect to the DB instance. For example, you can connect using SQL\$1Plus and a ** in a tnsnames.ora file. ``` sqlplus mydbuser@net_service_name ``` You can also connect to the DB instance using SQL\$1Plus without using a tnsnames.ora file by using the following command. ``` sqlplus 'mydbuser@(DESCRIPTION = (ADDRESS = (PROTOCOL = TCPS)(HOST = endpoint) (PORT = ssl_port_number))(CONNECT_DATA = (SID = database_name)))' ``` You can also connect to the RDS for Oracle DB instance without using SSL. For example, the following command connects to the DB instance through the clear text port without SSL encryption. ``` sqlplus 'mydbuser@(DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = endpoint) (PORT = port_number))(CONNECT_DATA = (SID = database_name)))' ``` If you want to close Transmission Control Protocol (TCP) port access, create a security group with no IP address ingresses and add it to the instance. This addition closes connections over the TCP port, while still allowing connections over the SSL port that are specified from IP addresses within the range permitted by the SSL option security group. # Setting up an SSL connection over JDBC To use an SSL connection over JDBC, you must create a keystore, trust the Amazon RDS root CA certificate, and use the code snippet specified following. To create the keystore in JKS format, you can use the following command. For more information about creating the keystore, see the [Creating a keystore](https://docs.oracle.com/cd/E35822_01/server.740/es_admin/src/tadm_ssl_jetty_keystore.html) in the Oracle documentation. For reference information, see [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html) in the *Java Platform, Standard Edition Tools Reference*. ``` keytool -genkey -alias client -validity 365 -keyalg RSA -keystore clientkeystore ``` Take the following steps to trust the Amazon RDS root CA certificate. **To trust the Amazon RDS root CA certificate** 1. Download the certificate bundle .pem file that works for all AWS Regions and put the file in the ssl\$1wallet directory. For information about downloading certificates, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md). 1. Extract each certificate in the .pem file into a separate file using an OS utility. 1. Convert each certificate to .der format using a separate `openssl` command, replacing *certificate-pem-file* with the name of the certificate .pem file (without the .pem extension). ``` openssl x509 -outform der -in certificate-pem-file.pem -out certificate-pem-file.der ``` 1. Import each certificate into the keystore using the following command. ``` keytool -import -alias rds-root -keystore clientkeystore.jks -file certificate-pem-file.der ``` For more information, see [Rotating your SSL/TLS certificate](UsingWithRDS.SSL-certificate-rotation.md). 1. Confirm that the key store was created successfully. ``` keytool -list -v -keystore clientkeystore.jks ``` Enter the keystore password when you are prompted for it. The following code example shows how to set up the SSL connection using JDBC. ``` import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; import java.util.Properties; public class OracleSslConnectionTest { private static final String DB_SERVER_NAME = "dns-name-provided-by-amazon-rds"; private static final Integer SSL_PORT = "ssl-option-port-configured-in-option-group"; private static final String DB_SID = "oracle-sid"; private static final String DB_USER = "user-name"; private static final String DB_PASSWORD = "password"; // This key store has only the prod root ca. private static final String KEY_STORE_FILE_PATH = "file-path-to-keystore"; private static final String KEY_STORE_PASS = "keystore-password"; public static void main(String[] args) throws SQLException { final Properties properties = new Properties(); final String connectionString = String.format( "jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=%s)(PORT=%d))(CONNECT_DATA=(SID=%s)))", DB_SERVER_NAME, SSL_PORT, DB_SID); properties.put("user", DB_USER); properties.put("password", DB_PASSWORD); properties.put("oracle.jdbc.J2EE13Compliant", "true"); properties.put("javax.net.ssl.trustStore", KEY_STORE_FILE_PATH); properties.put("javax.net.ssl.trustStoreType", "JKS"); properties.put("javax.net.ssl.trustStorePassword", KEY_STORE_PASS); final Connection connection = DriverManager.getConnection(connectionString, properties); // If no exception, that means handshake has passed, and an SSL connection can be opened } } ``` **Note** Specify a password other than the prompt shown here as a security best practice. # Enforcing a DN match with an SSL connection You can use the Oracle parameter `SSL_SERVER_DN_MATCH` to enforce that the distinguished name (DN) for the database server matches its service name. If you enforce the match verifications, then SSL ensures that the certificate is from the server. If you don't enforce the match verification, then SSL performs the check but allows the connection, regardless if there is a match. If you do not enforce the match, you allow the server to potentially fake its identity. To enforce DN matching, add the DN match property and use the connection string specified below. Add the property to the client connection to enforce DN matching. ``` properties.put("oracle.net.ssl_server_dn_match", "TRUE"); ``` Use the following connection string to enforce DN matching when using SSL. ``` final String connectionString = String.format( "jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=%s)(PORT=%d))" + "(CONNECT_DATA=(SID=%s))" + "(SECURITY = (SSL_SERVER_CERT_DN = \"C=US,ST=Washington,L=Seattle,O=Amazon.com,OU=RDS,CN=%s\")))", DB_SERVER_NAME, SSL_PORT, DB_SID, DB_SERVER_NAME); ``` # Troubleshooting SSL connections You might query your database and receive the `ORA-28860` error. ``` ORA-28860: Fatal SSL error 28860. 00000 - "Fatal SSL error" *Cause: An error occurred during the SSL connection to the peer. It is likely that this side sent data which the peer rejected. *Action: Enable tracing to determine the exact cause of this error. ``` This error occurs when the client attempts to connect using a version of TLS that the server doesn't support. To avoid this error, edit the sqlnet.ora and set `SSL_VERSION` to the correct TLS version. For more information, see [Oracle Support Document 2748438.1](https://support.oracle.com/epmos/faces/DocumentDisplay?id=2748438.1) in My Oracle Support.