Setup SSL for YSQL in Yugabyte manually

This is blogpost providing a quick (and dirty) way of enabling SSL for clients connecting to YSQL, alias the postgres compatible API in YugabyteDB.

If you need to do this in an official way, you should use Yugabyte Anywhere.

Create certificates

The creation of certificates is done using the openssl executable. This is an executable that is normally available on any linux system and on any Mac.

The way SSL works using openssl is that a so-called keypair is needed for encryption and decryption. You can create a key file, alias private key, at will, and you can create a CSR (certificate signing request) at will, but to make your CSR usable as a certificate, it must be signed by a CA (certificate authority).

For quickly creating test certificates, you can create a (dummy) certificate authority for yourself. Obviously, certificates signed by this dummy authority are not accepted as official certificates.

Certificate Authority

The creation of a CA is quite simple:

Create the CA key file:

openssl genrsa -out test.ca.key

Create the CA certificate file:

openssl req -new -x509 -key test.ca.key -out test.ca.crt

There are some questions asked, for test purposes you can just leave these blank, except for the common name: use localhost.

Server key and CSR

The creation of the server certificate files is also simple:

Create server key file:

openssl genrsa -out test.server.key

Create the server CSR file:

openssl req -new -key test.server.key -out test.server.csr

There are some question asked here too, which are the same questions as the CA creation, because both are about a public key/certificate. If there is a hostname used, the common name should match the hostname used.

This does create the CSR, the certificate signing request.

Sign the CSR

The last step is to use the CA files to sign the server CSR:

openssl x509 -req -in test.server.csr -CA test.ca.crt -CAkey test.ca.key -CAcreateserial -out test.server.crt

That's it! Now you got a number of files:

• The test.ca.crt file, which is the CA certificate, which sometimes is needed, when the CA needs to be provided for server certificate validation.
• The test.server.key file, which is the private key file. If this file is made available, the SSL security is compromised.
• The test.server.crt file, which is the (public) certificate file.

Plus:

• The test.ca.key file, which is the private key of the certificate authority. This file is only needed for signing.
• The test.ca.srl file, which contains the serial number of signed certificates (needed for a real CA to keep track of serials).
• The test.server.csr, which contains the signing request. This file can be reused when the certificate (.crt) expires.

Enable SSL for YugabyteDB YSQL (postgres API)

To enable SSL for YugabyteDB YSQL, there are two steps that need to be done:

• Put the needed files in a place and file format where the tablet server process can find these.
• Actually enable SSL for client to server encryption.
• (optionally, for test) Allow unencrypted connections alongside encrypted connections.

Put the certificate/SSL files in place.

(assuming the Yugabyte tablet server process is started with the user yugabyte and it's home directory is /home/yugabyte)

mkdir ~/certs
cp test.ca.crt ~/certs/ca.crt
cp test.server.key ~/certs/node.0.0.0.0.key
cp test.server.crt ~/certs/node.0.0.0.0.crt
chmod 700 certs

There is something to say here: the names of the key and certificate file is taken from the general parameter that controls on which address or addresses the tablet server is listening: rpc_bind_addresses. In the above situation, it was set to 0.0.0.0, which means all addresses.

Enable SSL and point the tablet server to the files

To enable client to server SSL, set the following tablet server setting:

use_client_to_server_encryption=true

To point the tablet server to the certificate files:

certs_for_client_dir=/home/yugabyte/certs

Enable unencrypted traffic alongside encrypted traffic

To allow unencrypted traffic as well as encrypted traffic, add the following line to the tablet server flag file:

ysql_hba_conf_csv="host all all all trust"

In a real life situation this is very likely not a good idea, but for test and testing this is or can be very useful. Read the documentation for more configuration options, such as configuring special unencrypted access for backup for example.