# Securing connections to RDS for PostgreSQL with SSL/TLS
RDS for PostgreSQL supports Secure Socket Layer (SSL) encryption for PostgreSQL DB instances. Using SSL, you can encrypt a PostgreSQL connection between your applications and your PostgreSQL DB instances. You can also force all connections to your PostgreSQL DB instance to use SSL. RDS for PostgreSQL also supports Transport Layer Security (TLS), the successor protocol to SSL.
To learn more about Amazon RDS and data protection, including encrypting connections using SSL/TLS, see [Data protection in Amazon RDS](DataDurability.md).
**Topics**
+ [
# Using SSL with a PostgreSQL DB instance
](PostgreSQL.Concepts.General.SSL.md)
+ [
# Updating applications to connect to PostgreSQL DB instances using new SSL/TLS certificates
](ssl-certificate-rotation-postgresql.md)
# Using SSL with a PostgreSQL DB instance
Amazon RDS supports Secure Socket Layer (SSL) encryption for PostgreSQL DB instances. Using SSL, you can encrypt a PostgreSQL connection between your applications and your PostgreSQL DB instances. By default, RDS for PostgreSQL uses and expects all clients to connect using SSL/TLS, but you can also require it. RDS for PostgreSQL supports Transport Layer Security (TLS) versions 1.1, 1.2, and 1.3.
For general information about SSL support and PostgreSQL databases, see [SSL support](https://www.postgresql.org/docs/11/libpq-ssl.html) in the PostgreSQL documentation. For information about using an SSL connection over JDBC, see [Configuring the client](https://jdbc.postgresql.org/documentation/head/ssl-client.html) in the PostgreSQL documentation.
SSL support is available in all AWS Regions for PostgreSQL. Amazon RDS creates an SSL certificate for your PostgreSQL DB instance when the instance is created. If you enable SSL certificate verification, then the SSL certificate includes the DB instance endpoint as the Common Name (CN) for the SSL certificate to guard against spoofing attacks.
**Topics**
+ [
## Connecting to a PostgreSQL DB instance over SSL
](#PostgreSQL.Concepts.General.SSL.Connecting)
+ [
## Requiring an SSL connection to a PostgreSQL DB instance
](#PostgreSQL.Concepts.General.SSL.Requiring)
+ [
## Determining the SSL connection status
](#PostgreSQL.Concepts.General.SSL.Status)
+ [
## SSL cipher suites in RDS for PostgreSQL
](#PostgreSQL.Concepts.General.SSL.Ciphers)
## Connecting to a PostgreSQL DB instance over SSL
**To connect to a PostgreSQL DB instance over SSL**
1. Download the certificate.
For information about downloading certificates, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
1. Connect to your PostgreSQL DB instance over SSL.
When you connect using SSL, your client can choose whether to verify the certificate chain. If your connection parameters specify `sslmode=verify-ca` or `sslmode=verify-full`, then your client requires the RDS CA certificates to be in their trust store or referenced in the connection URL. This requirement is to verify the certificate chain that signs your database certificate.
When a client, such as psql or JDBC, is configured with SSL support, the client first tries to connect to the database with SSL by default. If the client can't connect with SSL, it reverts to connecting without SSL. The default `sslmode` mode used is different between libpq-based clients (such as psql) and JDBC. The libpq-based and JDBC clients default to `prefer`.
Use the `sslrootcert` parameter to reference the certificate, for example `sslrootcert=rds-ssl-ca-cert.pem`.
The following is an example of using `psql` to connect to a PostgreSQL DB instance using SSL with certificate verification.
```
$ psql "host=db-name.555555555555.ap-southeast-1.rds.amazonaws.com
port=5432 dbname=testDB user=testuser sslrootcert=rds-ca-rsa2048-g1.pem sslmode=verify-full"
```
## Requiring an SSL connection to a PostgreSQL DB instance
You can require that connections to your PostgreSQL DB instance use SSL by using the `rds.force_ssl` parameter. The `rds.force_ssl` parameter default value is 1 (on) for RDS for PostgreSQL version 15 and later. For all other RDS for PostgreSQL major versions 14 and older, the default value of this parameter is 0 (off). You can set the `rds.force_ssl` parameter to 1 (on) to require SSL/TLS for connections to your DB cluster. You can set the `rds.force_ssl` parameter to 1 (on) to require SSL for connections to your DB instance.
To change the value of this parameter, you need to create a custom DB parameter group. You then change the value for `rds.force_ssl` in your custom DB parameter group to `1` to turn on this feature. If you prepare the custom DB parameter group before creating your RDS for PostgreSQL DB instance you can choose it (instead of a default parameter group) during the creation process. If you do this after your RDS for PostgreSQL DB instance is already running, you need to reboot the instance so that your instance uses the custom parameter group. For more information, see [Parameter groups for Amazon RDS](USER_WorkingWithParamGroups.md).
When the `rds.force_ssl` feature is active on your DB instance, connection attempts that aren't using SSL are rejected with the following message:
```
$ psql -h db-name.555555555555.ap-southeast-1.rds.amazonaws.com port=5432 dbname=testDB user=testuser
psql: error: FATAL: no pg_hba.conf entry for host "w.x.y.z", user "testuser", database "testDB", SSL off
```
## Determining the SSL connection status
The encrypted status of your connection is shown in the logon banner when you connect to the DB instance:
```
Password for user master:
psql (10.3)
SSL connection (cipher: DHE-RSA-AES256-SHA, bits: 256)
Type "help" for help.
postgres=>
```
You can also load the `sslinfo` extension and then call the `ssl_is_used()` function to determine if SSL is being used. The function returns `t` if the connection is using SSL, otherwise it returns `f`.
```
postgres=> CREATE EXTENSION sslinfo;
CREATE EXTENSION
postgres=> SELECT ssl_is_used();
ssl_is_used
---------
t
(1 row)
```
For more detailed information, you can use the following query to get information from `pg_settings`:
```
SELECT name as "Parameter name", setting as value, short_desc FROM pg_settings WHERE name LIKE '%ssl%';
Parameter name | value | short_desc
----------------------------------------+-----------------------------------------+-------------------------------------------------------
ssl | on | Enables SSL connections.
ssl_ca_file | /rdsdbdata/rds-metadata/ca-cert.pem | Location of the SSL certificate authority file.
ssl_cert_file | /rdsdbdata/rds-metadata/server-cert.pem | Location of the SSL server certificate file.
ssl_ciphers | HIGH:!aNULL:!3DES | Sets the list of allowed SSL ciphers.
ssl_crl_file | | Location of the SSL certificate revocation list file.
ssl_dh_params_file | | Location of the SSL DH parameters file.
ssl_ecdh_curve | prime256v1 | Sets the curve to use for ECDH.
ssl_key_file | /rdsdbdata/rds-metadata/server-key.pem | Location of the SSL server private key file.
ssl_library | OpenSSL | Name of the SSL library.
ssl_max_protocol_version | | Sets the maximum SSL/TLS protocol version to use.
ssl_min_protocol_version | TLSv1.2 | Sets the minimum SSL/TLS protocol version to use.
ssl_passphrase_command | | Command to obtain passphrases for SSL.
ssl_passphrase_command_supports_reload | off | Also use ssl_passphrase_command during server reload.
ssl_prefer_server_ciphers | on | Give priority to server ciphersuite order.
(14 rows)
```
You can also collect all the information about your RDS for PostgreSQL DB instance's SSL usage by process, client, and application by using the following query:
```
SELECT datname as "Database name", usename as "User name", ssl, client_addr, application_name, backend_type
FROM pg_stat_ssl
JOIN pg_stat_activity
ON pg_stat_ssl.pid = pg_stat_activity.pid
ORDER BY ssl;
Database name | User name | ssl | client_addr | application_name | backend_type
---------------+-----------+-----+----------------+------------------------+------------------------------
| | f | | | autovacuum launcher
| rdsadmin | f | | | logical replication launcher
| | f | | | background writer
| | f | | | checkpointer
| | f | | | walwriter
rdsadmin | rdsadmin | t | 127.0.0.1 | | client backend
rdsadmin | rdsadmin | t | 127.0.0.1 | PostgreSQL JDBC Driver | client backend
postgres | postgres | t | 204.246.162.36 | psql | client backend
(8 rows)
```
To identify the cipher used for your SSL connection, you can query as follows:
```
postgres=> SELECT ssl_cipher();
ssl_cipher
--------------------
DHE-RSA-AES256-SHA
(1 row)
```
To learn more about the `sslmode` option, see [Database connection control functions](https://www.postgresql.org/docs/11/libpq-connect.html#LIBPQ-CONNECT-SSLMODE) in the *PostgreSQL documentation*.
## SSL cipher suites in RDS for PostgreSQL
The PostgreSQL configuration parameter [ssl\$1ciphers](https://www.postgresql.org/docs/current/runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL) specifies the categories of cipher suites that are allowed for SSL connections to the database when using TLS 1.2 and lower.
In RDS for PostgreSQL 16 and later, you can modify the `ssl_ciphers` parameter to use specific values from the allowlisted cipher suites. This is a dynamic parameter that doesn't require a database instance reboot. To view the allowlisted cipher suites, use either the Amazon RDS console or the following AWS CLI command:
```
aws rds describe-db-parameters --db-parameter-group-name --region --endpoint-url --output json | jq '.Parameters[] | select(.ParameterName == "ssl_ciphers")'
```
The following table lists both the default cipher suites and the allowed cipher suites for versions that support custom configurations.
| PostgreSQL engine version | Default ssl\$1cipher suite values | Allowlisted custom ssl\$1cipher suite values |
| --- | --- | --- |
| 18 | HIGH:\$1aNULL:\$13DES | `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` |
| 17 | HIGH:\$1aNULL:\$13DES | `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` |
| 16 | HIGH:\$1aNULL:\$13DES | `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` |
| 15 | HIGH:\$1aNULL:\$13DES | Custom ssl\$1ciphers isn't supported |
| 14 | HIGH:\$1aNULL:\$13DES | Custom ssl\$1ciphers isn't supported |
| 13 | HIGH:\$1aNULL:\$13DES | Custom ssl\$1ciphers isn't supported |
| 12 | HIGH:\$1aNULL:\$13DES | Custom ssl\$1ciphers isn't supported |
| 11.4 and higher minor versions | HIGH:MEDIUM:\$13DES:\$1aNULL:\$1RC4 | Custom ssl\$1ciphers isn't supported |
| 11.1, 11.2 | HIGH:MEDIUM:\$13DES:\$1aNULL | Custom ssl\$1ciphers isn't supported |
| 10.9 and higher minor versions | HIGH:MEDIUM:\$13DES:\$1aNULL:\$1RC4 | Custom ssl\$1ciphers isn't supported |
| 10.7 and lower minor versions | HIGH:MEDIUM:\$13DES:\$1aNULL | Custom ssl\$1ciphers isn't supported |
To configure all instance connections to use the `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` cipher suite, modify your parameter group as shown in the following example:
```
aws rds modify-db-parameter-group --db-parameter-group-name --parameters "ParameterName='ssl_ciphers',ParameterValue='TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384',ApplyMethod=immediate"
```
This example uses an ECDSA cipher, which requires your instance to use a certificate authority with elliptic curve cryptography (ECC) to establish a connection. For information about certificate authorities provided by Amazon RDS, see [Certificate authorities](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/singWithRDS.SSL.html#UsingWithRDS.SSL.RegionCertificateAuthorities).
You can verify the ciphers in use through the methods described in [Determining the SSL connection status](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/PostgreSQL.Concepts.General.SSL.html#PostgreSQL.Concepts.General.SSL.Status).
Ciphers may have different names depending on the context:
+ The allowlisted ciphers that you can configure in your parameter group are referred to with their IANA names.
+ The `sslinfo` and `psql` logon banner refer to ciphers using their OpenSSL names.
By default, the value of `ssl_max_protocol_version` in RDS for PostgreSQL 16 and later is TLS v1.3. You must set the value of this parameter to TLS v1.2 as TLS v1.3 doesn't use the cipher configurations specified in the `ssl_ciphers` parameter. When you set the value as TLS v1.2, connections use only the ciphers that you define in `ssl_ciphers`.
```
aws rds modify-db-parameter-group --db-parameter-group-name --parameters "ParameterName='ssl_max_protocol_version',ParameterValue='TLSv1.2',ApplyMethod=immediate"
```
To ensure database connections use SSL, set the `rds.force_ssl parameter` to 1 in your parameter group. For more information about parameters and parameter groups, see [Parameter groups for Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithParamGroups.html).
# Updating applications to connect to PostgreSQL DB instances using new SSL/TLS certificates
Certificates used for Secure Socket Layer or Transport Layer Security (SSL/TLS) typically have a set lifetime. When service providers update their Certificate Authority (CA) certificates, clients must update their applications to use the new certificates. Following, you can find information about how to determine if your client applications use SSL/TLS to connect to your Amazon RDS for PostgreSQL DB instance. You also find information about how to check if those applications verify the server certificate when they connect.
**Note**
A client application that's configured to verify the server certificate before SSL/TLS connection must have a valid CA certificate in the client's trust store. Update the client trust store when necessary for new certificates.
After you update your CA certificates in the client application trust stores, you can rotate the certificates on your DB instances. We strongly recommend testing these procedures in a nonproduction environment before implementing them in your production environments.
For more information about certificate rotation, see [Rotating your SSL/TLS certificate](UsingWithRDS.SSL-certificate-rotation.md). For more information about downloading certificates, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md). For information about using SSL/TLS with PostgreSQL DB instances, see [Using SSL with a PostgreSQL DB instance](PostgreSQL.Concepts.General.SSL.md).
**Topics**
+ [
## Determining whether applications are connecting to PostgreSQL DB instances using SSL
](#ssl-certificate-rotation-postgresql.determining-server)
+ [
## Determining whether a client requires certificate verification in order to connect
](#ssl-certificate-rotation-postgresql.determining-client)
+ [
## Updating your application trust store
](#ssl-certificate-rotation-postgresql.updating-trust-store)
+ [
## Using SSL/TLS connections for different types of applications
](#ssl-certificate-rotation-postgresql.applications)
## Determining whether applications are connecting to PostgreSQL DB instances using SSL
Check the DB instance configuration for the value of the `rds.force_ssl` parameter. By default, the `rds.force_ssl` parameter is set to `0` (off) for DB instances using PostgreSQL versions before version 15. By default, `rds.force_ssl` is set to `1` (on) for DB instances using PostgreSQL version 15 and later major versions. If the `rds.force_ssl` parameter is set to `1` (on), clients are required to use SSL/TLS for connections. For more information about parameter groups, see [Parameter groups for Amazon RDS](USER_WorkingWithParamGroups.md).
If you are using RDS PostgreSQL version 9.5 or later major version and `rds.force_ssl` is not set to `1` (on), query the `pg_stat_ssl` view to check connections using SSL. For example, the following query returns only SSL connections and information about the clients using SSL.
```
SELECT datname, usename, ssl, client_addr
FROM pg_stat_ssl INNER JOIN pg_stat_activity ON pg_stat_ssl.pid = pg_stat_activity.pid
WHERE ssl is true and usename<>'rdsadmin';
```
Only rows using SSL/TLS connections are displayed with information about the connection. The following is sample output.
```
datname | usename | ssl | client_addr
----------+---------+-----+-------------
benchdb | pgadmin | t | 53.95.6.13
postgres | pgadmin | t | 53.95.6.13
(2 rows)
```
This query displays only the current connections at the time of the query. The absence of results doesn't indicate that no applications are using SSL connections. Other SSL connections might be established at a different time.
## Determining whether a client requires certificate verification in order to connect
When a client, such as psql or JDBC, is configured with SSL support, the client first tries to connect to the database with SSL by default. If the client can't connect with SSL, it reverts to connecting without SSL. The default `sslmode` mode used for both libpq-based clients (such as psql) and JDBC is set to `prefer`. The certificate on the server is verified only when `sslrootcert` is provided with `sslmode` set to `verify-ca` or `verify-full`. An error is thrown if the certificate is invalid.
Use `PGSSLROOTCERT` to verify the certificate with the `PGSSLMODE` environment variable, with `PGSSLMODE` set to `verify-ca` or `verify-full`.
```
PGSSLMODE=verify-full PGSSLROOTCERT=/fullpath/ssl-cert.pem psql -h pgdbidentifier.cxxxxxxxx.us-east-2.rds.amazonaws.com -U masteruser -d postgres
```
Use the `sslrootcert` argument to verify the certificate with `sslmode` in connection string format, with `sslmode` set to `verify-ca` or `verify-full` to verify the certificate.
```
psql "host=pgdbidentifier.cxxxxxxxx.us-east-2.rds.amazonaws.com sslmode=verify-full sslrootcert=/full/path/ssl-cert.pem user=masteruser dbname=postgres"
```
For example, in the preceding case, if you are using an invalid root certificate, then you see an error similar to the following on your client.
```
psql: SSL error: certificate verify failed
```
## Updating your application trust store
For information about updating the trust store for PostgreSQL applications, see [Secure TCP/IP connections with SSL](https://www.postgresql.org/docs/current/ssl-tcp.html) in the PostgreSQL documentation.
For information about downloading the root certificate, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
For sample scripts that import certificates, see [Sample script for importing certificates into your trust store](UsingWithRDS.SSL-certificate-rotation.md#UsingWithRDS.SSL-certificate-rotation-sample-script).
**Note**
When you update the trust store, you can retain older certificates in addition to adding the new certificates.
## Using SSL/TLS connections for different types of applications
The following provides information about using SSL/TLS connections for different types of applications:
+ **psql**
The client is invoked from the command line by specifying options either as a connection string or as environment variables. For SSL/TLS connections, the relevant options are `sslmode` (environment variable `PGSSLMODE`), `sslrootcert` (environment variable `PGSSLROOTCERT`).
For the complete list of options, see [Parameter key words](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS) in the PostgreSQL documentation. For the complete list of environment variables, see [Environment variables](https://www.postgresql.org/docs/current/libpq-envars.html) in the PostgreSQL documentation.
+ **pgAdmin**
This browser-based client is a more user-friendly interface for connecting to a PostgreSQL database.
For information about configuring connections, see the [pgAdmin documentation](https://www.pgadmin.org/docs/pgadmin4/latest/server_dialog.html).
+ **JDBC**
JDBC enables database connections with Java applications.
For general information about connecting to a PostgreSQL database with JDBC, see [Connecting to the database](https://jdbc.postgresql.org/documentation/use/#connecting-to-the-database) in the PostgreSQL JDBC driver documentation. For information about connecting with SSL/TLS, see [Configuring the client](https://jdbc.postgresql.org/documentation/ssl/#configuring-the-client) in the PostgreSQL JDBC driver documentation.
+ **Python**
A popular Python library for connecting to PostgreSQL databases is `psycopg2`.
For information about using `psycopg2`, see the [psycopg2 documentation](https://pypi.org/project/psycopg2/). For a short tutorial on how to connect to a PostgreSQL database, see [Psycopg2 tutorial](https://wiki.postgresql.org/wiki/Psycopg2_Tutorial). You can find information about the options the connect command accepts in [The psycopg2 module content](http://initd.org/psycopg/docs/module.html#module-psycopg2).
**Important**
After you have determined that your database connections use SSL/TLS and have updated your application trust store, you can update your database to use the rds-ca-rsa2048-g1 certificates. For instructions, see step 3 in [Updating your CA certificate by modifying your DB instance or cluster](UsingWithRDS.SSL-certificate-rotation.md#UsingWithRDS.SSL-certificate-rotation-updating).