Enable Encryption in Transit (TLS)

Yugabyte Platform allows you to protect data in transit by using the following:

• Server-to-server encryption for intra-node communication between YB-Master and YB-TServer nodes.
• Client-to-server encryption for communication between clients and nodes when using CLIs, tools, and APIs for YSQL and YCQL.

Yugabyte Platform lets you create a new self-signed certificate, use an existing self-signed certificate, or upload a third-party certificate from external providers, such as Venafi or DigiCert (which is only available for an on-premise cloud provider).

You can enable TLS encryption during universe creation and change these settings for an existing universe.

Self-Signed Certificates Generated by Yugabyte Platform

Yugabyte Platform can create self-signed certificates for each universe. These certificates may be shared between universes within a single instance of Yugabyte Platform. The certificate name has the following format:

yb-environment-universe_name, where environment is the environment type (either dev, stg, demo, or prod) that was used during the tenant registration (admin user creation), and universe-name is the provided universe name. The platform generates the root certificate, root private key, and node-level certificates, (assuming node-to-node encryption is enabled), and then provisions those artifacts to the database nodes any time nodes are created or added to the cluster. The following three files are copied to each node:

1. The root certificate (ca.cert).
2. The node certificate (node.ip_address.crt).
3. The node private key (node.ip_address.key).

The platform retains the root certificate and the root private key for all interactions with the cluster.

How to Use Platform-Generated Certificates to Enable TLS

When you create a universe, you can enable TLS using certificates generated by Yugabyte Platform, as follows:

1. Create a new universe via Universes > Create Universe and then configure it.
2. Based on your requirements, select Enable Node-to-Node TLS or Enable Client-to-Node TLS or both.
3. Choose an existing certificate from the Root Certificate list or create a new certificate by accepting the default option Create new certificate.

To view the certificate, navigate to Configs > Security > Encryption in Transit > Self Signed.

You can also modify TLS settings for an existing universe, as follows:

1. Navigate to either Dashboard or Universes and open a specific universe.

2. Click Actions > Edit Security > Encryption in-Transit to open the TLS Configuration dialog and then proceed as follows:

   • If encryption in transit is currently disabled for the universe, enable it via the Encryption in Transit for this Universe field, as per the following illustration:
     
     

     

     
     
     Use the expanded TLS Configuration dialog shown in the following illustration to change the settings to meet your requirements:
     
     

     

   
   

   • If encryption in transit is currently enabled for the universe, you can either disable or modify it, as follows:

     • To disable encryption in transit, disable the Encryption in Transit for this Universe field and then click OK.

     • To modify encryption in-transit settings, leave the Encryption in Transit for this Universe field enabled and make the necessary changes to other fields.
       

       If you are changing certificates, you need to be aware that this requires restart of the Master and T-Server processes and can result in downtime. To avoid downtime, you should accept the default value (enabled) for the Rolling Upgrade field to trigger a sequential node-by-node change with a specific delay between node upgrades (as opposed to a simultaneous change of certificates in every node which occurs when the Rolling Upgrade field is disabled). If you select the Create new certificate option when changing certificates, the corresponding certificates will be rotated, that is, replaced with new certificates.

Self-Signed Self-Provided Certificates

Instead of using platform-provided certificates, you can use your own self-signed certificates that you upload to the platform by following the procedure described in How to Use Self-Signed Self-Provided Certificates to Enable TLS.

The certificates must meet the following criteria:

• Be in the .crt format and the private key must be in the .pem format, with both of these artifacts available for upload.
• Contain IP addresses of the target database nodes or DNS names as the Subject Alternative Names (wildcards are acceptable).

The platform produces the node (leaf) certificates from the uploaded certificates and copies the certificate chain, leaf certificate, and private key to the nodes in the cluster.

How to Use Self-Signed Self-Provided Certificates to Enable TLS

When you create a universe, you can enable TLS using your own certificates, as follows:

1. Navigate to Configs > Security > Encryption in Transit.
2. Click Add Certificate to open the Add Certificate dialog.
3. Select Self Signed.
4. Click Upload Root Certificate, then browse to the root certificate file (<file-name>.crt) and upload it.
5. Click Upload Key, then browse to the root certificate file (<file-name>.key) and upload it.
6. In the Certificate Name field, enter a meaningful name for your certificate.
7. In the Expiration Date field, specify the expiration date of the root certificate. To find this information, execute the openssl x509 -in <root-crt-file-path> -text -noout command and note the Validity Not After date.
8. Click Add to make the certificate available.
9. Go to Universes > Create Universe to open the Create Universe dialog.
10. Configure the universe.
11. Based on your requirements, select Enable Node-to-Node TLS and Enable Client-to-Node TLS.
12. Select an existing certificate from the Root Certificate list and then select the certificate that you have uploaded.
13. Create the universe.

You can also modify TLS settings for an existing universe by navigating to Universes, opening a specific universe, clicking Actions > Edit Security > Encryption in-Transit to open the TLS Configuration dialog, and then following the procedure described in How to Use Platform-Generated Certificates to Enable TLS for an existing universe.

Custom CA-Signed Self-Provided Certificates

For universes created with an on-premise cloud provider, instead of using self-signed certificates, you can use third-party certificates from external CAs. The third-party CA root certificate must be configured in the platform. You have to copy the custom CA root certificate, node certificate, and node key to the appropriate database nodes using the procedure described in How to Use Custom CA-Signed Certificates to Enable TLS.

The certificates must meet the following criteria:

• Be in the .crt format and the private key must be in the .pem format.
• Contain IP addresses of the database nodes or DNS names as the Subject Alternative Names (wildcards are acceptable).

How to Use Custom CA-Signed Certificates to Enable TLS

The following procedure describes how to install certificates on the database nodes. You have to repeat these steps for every database node that is to be used in the creation of a universe.

Step 1: Obtain the keys and the custom CA-signed certificates for each of the on-premise nodes for which you are configuring node-to-node TLS. In addition, obtain the keys and the custom signed certificates for client access for configuring client-to-node TLS.

Step 2: For each on-premise node, copy the custom CA root certificate, node certificate, and node key to that node's file system.

If you are enabling client-to-node TLS, make sure to copy the client certificate and client key to each of the nodes.

In addition, ensure the following:

• That the file names and file paths of different certificates and keys are identical across all the database nodes. For example, if you name your CA root certificate as ca.crt on one node, then name it ca.crt on all the nodes. Similarly, if you copy ca.crt to /opt/yugabyte/keys on one node, then copy ca.crt to the same path on other nodes.
• That the yugabyte system user has read permissions to all the certificates and keys.

Step 3: Create a CA-signed certificate in Yugabyte Platform, as follows:

1. Navigate to Configs > Security > Encryption in Transit.

2. Click Add Certificate to open the Add Certificate dialog.

3. Select CA Signed, as per the following illustration:
   
   

   
   
   

4. Upload the custom CA root certificate as the root certificate. If you do not have the root certificate, contact your CA.

5. Enter the file paths for each of the certificates on the nodes. These are the paths from the previous step.

6. In the Certificate Name field, enter a meaningful name for your certificate.

7. Use the Expiration Date field to specify the expiration date of the certificate. To find this information, execute the openssl x509 -in <root crt file path> -text -noout command and note the Validity Not After date.

8. Click Add to make the certificate available.

9. Go to Universes > Create Universe to open the Create Universe dialog.

10. Configure the universe.

11. Based on your requirements, select Enable Node-to-Node TLS and Enable Client-to-Node TLS.

12. Select an existing certificate from the Root Certificate list and then select the certificate that you have uploaded.

13. Create the universe.

You can rotate certificates for universes configured with the same type of certificates. This involves replacing existing certificates with new database node certificates.

How to Rotate Custom CA-Signed Certificates

You can rotate certificates for universes configured with the same type of certificates. This involves replacing existing certificates with new database node certificates.

You rotate the existing custom certificates and replace them with new database node certificates issued by the same custom CA that issued the original certificates as follows:

Step 1: Follow Step 1 of How to Use Custom CA-Signed Certificates to Enable TLS to obtain a new set of certificates for each of the nodes.

Step 2: Follow Step 2 of How to Use Custom CA-Signed Certificates to Enable TLS to copy the certificates to the respective nodes.

Step 3: Follow Step 3 of How to Use Custom CA-Signed Certificates to Enable TLS to create a new CA-signed certificate in Yugabyte Platform.

Step 4: Edit the universe to use the new certificates, as follows:

• Navigate to the universe for which you are rotating the keys.

• Select Actions > Edit Security, as shown in the following illustration:
  
  

  
  

• Select Encryption in-Transit to open the TLS Configuration dialog.

• Complete the TLS Configuration dialog shown in the following illustration:

  • Select the new certificate which you created in Step 3.

  • Modifying certificates requires restart of Master and T-Server processes, which can result in downtime. To avoid downtime, you should accept the default value (enabled) for the Rolling Upgrade field to trigger a sequential node-by-node change with a specific delay between node upgrades (as opposed to a simultaneous change of certificates in every node which occurs when the Rolling Upgrade field is disabled).

  • Click OK.
    

    Typically, this process takes time, as it needs to wait for the specified delay interval after each node is upgraded.
    
    

  

How to Expand the Universe

You can expand universes configured with custom CA-signed certificates.

Before adding new nodes to expand an existing universe, you need to prepare those nodes by repeating Step 2 of How to Use Custom CA-Signed Certificates to Enable TLS for each of the new nodes you plan to add to the universe. You need to ensure that the certificates are signed by the same external CA and have the same root certificate. In addition, ensure that you copy the certificates to the same locations that you originally used when creating the universe.

When the universe is ready for expansion, complete the Edit Universe dialog to add new nodes.

Connecting to Clusters

Using TLS, you can conntect to the YSQL and YCQL endpoints.

How to Connect to a YSQL Endpoint with TLS

If you created your universe with the Client-to-Node TLS option enabled, then you must download client certificates to your client computer to establish connection to your database, as follows:

• Navigate to the Certificates page and then to your universe’s certificate.

• Click Actions and select Download YSQL Cert, as shown in the following illustration. This triggers the download of the yugabytedb.crt and yugabytedb.key files.
  
  

  
  
  

• Optionally, when connecting to universes that are configured with custom CA-signed certificates, obtain the root CA and client YSQL certificate from your administrator. These certificates are not available on Yugabyte Platform for downloading.

• For testing with a ysqlsh client, paste the yugabytedb.crt and yugabytedb.key files into the <home-dir>/.yugabytedb directory and change the permissions to 0600, as follows:

  $ mkdir ~/.yugabytedb; cd ~/.yugabytedb
  $ cp <DownloadDir>/yugabytedb.crt .
  $ cp <DownloadDir>/yugabytedb.key .
  $ chmod 600 yugabytedb.*
  

• Run ysqlsh using the sslmode=require option, as follows:

  $ cd <yugabyte software install directory>
  $ bin/ysqlsh -h 172.152.43.78 -p 5433 sslmode=require
  ysqlsh (11.2-YB-2.3.3.0-b0)
  SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
  Type "help" for help.
  
  yugabyte=#
  

To use TLS from a different client, consult the client-specific documentation. For example, if you are using a PostgreSQL JDBC driver to connect to YugabyteDB, see Configuring the Client for more details.

How to Connect to a YCQL Endpoint with TLS

If you created your universe with the Client-to-Node TLS option enabled, then you must download client certificates to your client computer to establish connection to your database, as follows:

• Navigate to the Certificates page and then to your universe’s certificate.

• Click Actions and select Download Root Cert, as shown in the following illustration. This triggers the download of the root.crt file.
  
  

  
  
  

• Optionally, when connecting to universes that are configured with custom CA-signed certificates, obtain the root CA and client YSQL certificate from your administrator. These certificates are not available on Yugabyte Platform for downloading.

• Set SSL_CERTFILE environment variable to point to the locatioin of the downloaded root certificate.

• Run ycqlsh using the -ssl option, as follows:

  $ cp <DownloadDir>/root.crt ~/.yugabytedb/root.crt
  $ export SSL_CERTFILE=~/.yugabytedb/root.crt
  $ bin/ycqlsh 172.152.43.78 --ssl
  Connected to local cluster at 172.152.43.78:9042.
  [ycqlsh 5.0.1 | Cassandra 3.9-SNAPSHOT | CQL spec 3.4.2 | Native protocol v4]
  Use HELP for help.
  ycqlsh>
  

To use TLS from a different client, consult the client-specific documentation. For example, if you are using a Cassandra driver to connect to YugabyteDB, see SSL .

Validating Certificates

When configuring and using certificates, SSL issues may occasionally arise. You can validate your certificates and keys as follows:

1. Verify that the CA CRT and CA private key match by executing the following commands:

   openssl rsa -noout -modulus -in ca.key | openssl md5
   openssl x509 -noout -modulus -in ca.crt | openssl md5
   
   \# outputs should match
   

2. Verify that the CA CRT is actually a certificate authority by executing the following command:

   openssl x509 -text -noout -in ca.crt
   
   \# Look for fields
   
   X509v3 Basic Constraints:
   
     CA:TRUE
   

3. Verify that certificates and keys are in PEM format (as opposed to the DER or other format). If these artifacts are not in the PEM format and you require assistance with converting them or identifying the format, consult Converting Certificates.

4. Ensure that the private key does not have a passphrase associated with it. For information on how to identify this condition, see How to Decrypt an Enrypted SSL RSA Private Key.

Enforcing TLS Versions

As TLS 1.0 and 1.1 are no longer accepted by PCI compliance, and considering significant vulnerabilities around these versions of the protocol, it is recommended that you migrate to TLS 1.2 or later versions.

You can set the TLS version for node-to-node and client-node communication. To enforce TLS 1.2, add the following flag for T-Server:

To enforce the minimum TLS version of 1.2, you need to specify all available subsequent versions for T-Server, as follows:

In additioin, since the ssl_protocols setting does not propagate to PostgreSQL, it is recommended that you specify the minimum TLS version ( ssl_min_protocol_version ) for PostgreSQL by setting the following T-Server gflag: