You are here

Using Let’s Encrypt Certificates in NuoDB - A Step by Step Tutorial

Introduction

This tutorial will walk you through the whole process of using free Let’s Encrypt certificates in NuoDB. First, we will create certificates using Let’s Encrypt as described in their documentation. Second, we will convert those certificates into various certificate formats that NuoDB processes require. At the end of this tutorial, we will show you what to look for in NuoDB log files and how to use TLS in the various TLS enabled database drivers.

Acquiring a Signed Certificate

The process of obtaining a signed certificate typically involves generating a key-pair and a Certificate Signing Request (CSR), which is submitted to the certificate authority (CA). Once a signed certificate is obtained, it must be converted into a format supported by NuoDB. For details on how your organization obtains signed certificates, refer to the documentation for your chosen CA.

In this tutorial, we will follow the steps as described in the Let’s Encrypt CA documentation.

  1. Download a clone of Let’s Encrypt from the official GitHub repository. /opt is a common installation directory for third-party packages, so let’s install the clone to
    /opt/letsencrypt: 
    sudo git clone https://github.com/letsencrypt/letsencrypt /opt/letsencrypt
  2. Navigate to the new /opt/letsencrypt directory: 
    cd /opt/letsencrypt
  3. Run Let’s Encrypt with the --standalone parameter. For each additional domain name requiring a certificate, add -d example.com to the end of the command. 
    sudo -H ./letsencrypt-auto certonly --standalone -d example.com 
    -d www.example.com
  4. Follow the Let’s Encrypt command line prompts
  5. The output of the Let’s Encrypt script shows where your certificate is stored; in this case,
    /etc/letsencrypt/live:
    sudo ls /etc/letsencrypt/live
    > example.com
    sudo ls /etc/letsencrypt/live/example.com
    > cert.pem       chain.pem      fullchain.pem  privkey.pem
  6. Your certificates will be in the PEM format and will contain the -----BEGIN CERTIFICATE----- and  -----END CERTIFICATE-----  sections. To verify your public certificate run
    openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem -text -noout
    > 
    Certificate:
        Data:
            Version: 3 (0x2)
    		… 
    Signature Algorithm: sha256WithRSAEncryption
            Issuer: C=US, O=Let's Encrypt, CN=Let's Encrypt Authority X3
            Validity
                Not Before: Jan 28 00:03:40 2019 GMT
                Not After : Apr 28 00:03:40 2019 GMT
            Subject: CN=example.com
    X509v3 extensions:
                X509v3 Key Usage: critical
                    Digital Signature, Key Encipherment
                X509v3 Extended Key Usage: 
                    TLS Web Server Authentication, TLS Web Client Authentication
                X509v3 Basic Constraints: critical
                    CA:FALSE
                Authority Information Access: 
                    OCSP - URI:http://ocsp.int-x3.letsencrypt.org
                    CA Issuers - URI:http://cert.int-x3.letsencrypt.org/
                X509v3 Subject Alternative Name: 
                    DNS:example.com, DNS:www.example.com

     

Note: NuoDB recommends using a private CA whenever possible. For more info on how to generate a CSR, see NuoDB docs - Enabling TLS.

For more information, consult: Using Certificates Signed by a Public Certificate Authority

Converting Certificate Formats

NuoDB Admin accepts PKCS12 and JKS file formats. These are industry-standard formats for X509 certificate data, and either of these formats can be used for a NuoDB Admin process’s keystore, which contains its key-pair certificate, and truststore, which contains the set of certificates trusted by the admin process.

Since NuoDB Admin does not support the PEM format, we will convert the PEM files created by Lets’ Encrypt into PKCS12 files (keystore and truststore) that the NuoDB Admin process can load.

  1. create keystore from PEM files
    $ openssl pkcs12 -export -name nuoadmin -OUT nuoadmin.p12 -inkey 
    privkey.pem -IN fullchain.pem 
    Enter Export Password: <enter PASSWD value>
    Verifying - Enter Export Password: <enter PASSWD value>
  2. copy certificate to truststore
    $ nuocmd import certificate --keystore nuoadmin.p12 
    --store-password "$PASSWD" \
        --truststore nuoadmin-truststore.p12 --truststore-password 
    "$PASSWD"
  3. Unify the server certificate name
    ​$ cp cert.pem nuoadmin.cert

Note: The $PASSWD environmental variable is assumed to be the same value you used to create the PKCS key in step 1.

For more information on converting between certificate formats, see the following resources:

Generating Client Certificates

Clients are authorized in the NuoDB admin tier using x509 client certificates. To keep your deployment safe, NuoDB follows best practices for password-less auth.

You can create client PKCS12 certificates using standard third-party tools such as OpenSSL (see resources above). Here we will use the NuoDB convenience functionality of nuocmd.

  1. Generate a key-pair certificate to be used by NuoDB Command clients: nuocmd
    create keypair --keystore nuocmd.p12 --store-password "$PASSWD"
    --dname "CN=nuocmd"
     
  2. Import the client certificate generated in the previous step into the truststore: nuocmd
    import certificate --keystore nuocmd.p12 --store-password "$PASSWD" --truststore nuoadmin-truststore.p12
    --truststore-password "$PASSWD"
     
  3. Convert the client key and certificate to PEM format so that it can be used by NuoDB Command (nuocmd): nuocmd show certificate --keystore nuocmd.p12
    --store-password "$PASSWD"> nuocmd.pem

After this step, the truststore used by NuoDB admin processes nuoadmin-truststore.p12 should contain both the admin certificate and the client certificate. You can verify this by running: openssl pkcs12 -info -in nuoadmin-truststore.p12

Enter Import Password:
Certificate bag
Bag Attributes
    friendlyName: nuoadmin
subject=/CN=example.com
issuer=/C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3
-----BEGIN CERTIFICATE-----
… 
-----END CERTIFICATE-----
Certificate bag
Bag Attributes
    friendlyName: nuocmd
subject=/CN=nuocmd
issuer=/CN=nuocmd
-----BEGIN CERTIFICATE-----
… 
-----END CERTIFICATE-----

The file nuocmd.pem will be used by NuoDB scripts that only accept PEM files to communicate with the NuoDB admin processes.

Starting NuoDB Admin with TLS

Before starting NuoDB, make sure that all certificates are in a well-known location and are accessible by the nuodb user.

cp nuoadmin.p12 nuoadmin-truststore.p12 nuocmd.pem nuoadmin.cert 
/etc/nuodb/KEYS
chown -R nuodb:nuodb /etc/nuodb/KEYS

Update nuoadmin.conf so that TLS is enabled and the generated certificate files are specified:

    "ssl": "true",
    "keystore": "/etc/nuodb/keys/nuoadmin.p12",
    "keystore-type": "PKCS12",
    "keystore-password": "<PASSWD value>",
    "truststore": "/etc/nuodb/keys/nuoadmin-truststore.p12",
    "truststore-type": "PKCS12",
    "truststore-password": "<PASSWD value>",

Start the NuoDB admin process

service nuoadmin start

Connect to the admin using nuocmd

/etc/nuodb/bin/nuocmd --client-key /etc/nuodb/keys/nuocmd.pem 
--verify-server /etc/nuodb/keys/nuoadmin.cert show domain

You can set environmental variables in place of command line arguments:

export NUOCMD_CLIENT_KEY=/etc/nuodb/KEYS/nuocmd.pem
export NUOCMD_VERIFY_SERVER=/etc/nuodb/KEYS/nuoadmin.cert
nuocmd SHOW DOMAIN

Start the minimal database:

# CREATE an archive
nuocmd CREATE archive --db-name test --server-id server0 
--archive-path /var/opt/nuodb/test-archives/<dbname>
 
# CREATE a DATABASE
nuocmd CREATE DATABASE --db-name test --dba-user dba --dba-password 
dba --te-server-ids server0

For more information, consult: Enabling TLS Encryption.

Verifying Configuration In Log Files

Locate your nuoadmin.log file and look for a log file that starts with TLS Support ENABLED:. This is the engine log report.

cat /var/log/nuodb/nuoadmin.log
TLS Support ENABLED:
  DOMAIN CAs:
    Certificate #0 CN nuocmd: expires Feb 24 02:03:23 2119 GMT
    Certificate #1 CN nuoadmin: expires Feb 24 02:03:22 2119 GMT
  Intermediate Certificates: 
    Certificate #2 CN nuoadmin: expires Feb 24 02:03:22 2119 GMT
  Engine Certificate:
    Certificate #3 CN localhost: expires Jun  4 21:32:01 2020 GMT
Certificate chain will expire ON Jun  4 21:32:01 2020 GMT

Domain CAs should list both the nuocmd client certificate and the nuoadmin server certificate. All NuoDB engine processes will also print the expiration date of the certificate chain.

Using Certificates in Drivers

Each NuoDB driver accepts a different type of certificate format. You can see the list in Connecting to a Database Using TLS and LDAP # Supported Trust Store Formats

In this example, we will focus on the simplest of our drivers, the PyNuoDB driver.

  1. Download a clone of PyNuoDB from the official GitHub repository.

    $ git clone https://github.com/nuodb/nuodb-python.git; cd nuodb-python
     
  2. Follow the example in https://github.com/nuodb/nuodb-python#id3 with the following modification:

    options = {"schema": "test",'trustStore':
    "/etc/nuodb/keys/nuoadmin.cert"}
     
  3. Congratulations, you have TLS in your domain!

Note: For simplicity, NuoDB recommends using the root CA certificate as the trustStore for the driver. The location of well known 3rd party certificates varies on every system. On Ubuntu the certificates can be found in /etc/ssl/certs. The Let’s Encrypt root is /etc/ssl/certs/DST_Root_CA_X3.pem. Or alternatively, you can look in the Lets Encrypt Chain Of Trust. Once you have located the CA root on your system, you can use it as your driver’s trustStore, if the driver supports PEM files. ‘trustStore’: “/etc/ssl/certs/DST_Root_CA_X3.pem”.

For information on the C++ driver see the docs here.

For information on the JDBC driver see the docs here.

(This article was updated on November 4, 2019 to add a link.)

Add new comment