Let’s Encrypt

Getting started with Let’s Encrypt (LE for short) requires minimal knowledge of certificate architectures but does require a working knowledge of Unix or Windows systems. LE employs an automated approach to certificate creation and management via the IETF protocol specification called “Automated Certificate Management Environment” (ACME). ACME provides increased security paradigm through automation. Some of the advantages of this approach are shown below:

• Automated certificate creation, renewal and revocation
• Domain Name/Owner Validation
• Cross Signed Certificates Capability
• ACME Based
• Extensible

To learn more about Let’s Encrypt, please visit their homepage at https://letsencrypt.org/ and if you’d like to know straight to the tech this link https://letsencrypt.org/how-it-works/ has more detail.

Now, let’s get started on creating LE certificates and using them with Couchbase.

Securing Couchbase

Creating certificates with LE for use with any application is easy and for Couchbase server it is just as simple as issuing a few commands. There are prerequisites which should be understood before jumping in. They are discussed within current Couchbase Server documentation and the LE web site.

• Couchbase Resources
  http://developer.couchbase.com/documentation/server/4.5/security/security-comm-encryption.html
  https://developer.couchbase.com/documentation/server/current/security/security-x509certsintro.html

• LetsEncrypt.com

https://letsencrypt.org/getting-started/

Create Certificates with CertBot

Prior to creating and installing certificates you need to get the LE automated tool called CertBot.

Pre-requisites

To install CertBot, the automated certificate tool from Let’s Encrypt, there are two ways.

1. From your OS provider: Visit https://certbot.eff.org/ and choose your OS
2. Through GitHub: requires you have “git” installed

Once you’ve installed CertBot you’re ready to start creating certificates.

Note: There are some caveats such as deploying in the cloud or in a system not on the edge. Pay attention to your connection to the client or the internet when deciding network and server topologies with Let’s Encrypt.

The following steps were used with instances in Amazon AWS to create certificates for use with Couchbase Server. Your steps should be similar but we provide these steps as an example.

1. Run certbot from the command line the first time with ‘-h’ option:

2. Start the certificate creation dialog in Manual Mode for prompt driven creation

3. Accept the license

4. Acknowledge how to validate the domain is yours (web server or standalone built-in pythons server)

5. provide a valid public DNS host name

6. provide a valid email address

Figure: Example of a valid hostname

The screenshot above is from the setup screens used during request configuration.

If certificate creation was successful you’ll see a message like so:

To ensure certificates were saved properly you can list out the directory contents like so:

Certificate Subject Alternative Name (SAN) Configuration

It is likely that the certificate will be addressed as more than one name. You can add additional names to a certificate, also called Subject Alternative Name (SAN). An example of creating a certificate for multiple domains using SAN is shown below:

Once satisfied with your certificate creation and preparation it is time to add certificates to Couchbase Server.

Deploy Certificates to Couchbase

Preparation

Once certificate creation has completed successfully you must use a set of command line tools to make sure Couchbase can access the certificates. The full description is in the Couchbase server documentation link shown and an example setup will be provided in the following paragraphs.

https://developer.couchbase.com/documentation/server/current/security/security-x509certsintro.html

In order for the LE certificates to be used for encryption you are required to provide the “CA root” certificate from LE. The following link provides a diagram and a description of the hierarchy about the CA.

https://letsencrypt.org/certificates/

The CA diagram itself is shown here: https://letsencrypt.org/certs/isrg-keys.png

Importing certificates

Importing certificates to Couchbase server must be done on each node. Additionally, a special directory called “inbox” in the Couchbase server directory is used to store the certificates. Take special care when running the commands as root so as not to damage anything in the Couchbase server directory. Ensure owner and group are set to “couchbase” for the “inbox” directory and all files inside.

This procedure must be completed on each node. Each node must also have a DNS addressable hostname or use a reverse proxy like NGinX or other method. For more information go to http://www.letsencrypt.com/documentation or refer to following guides: https://github.com/certbot/certbot/wiki/Links

1.    Download the CA-Root Cert
a.    Using your browser save the text shown here:
I.    https://www.identrust.com/certificates/trustid/root-download-x3.html to a plaintext file such as:    lets-encrypt-x3-rootCA.pem
b.    Format the key inside the file like below and save as plain text (not RTF or anything else)
I.    —–BEGIN CERTIFICATE—–
—–END CERTIFICATE—–
2.    Create the Couchbase Server “Inbox” directory
a.    mkdir /opt/couchbase/var/lib/couchbase/inbox
3.    Change permissions from “root” to “couchbase”
a.    chown couchbase:couchbase –R /opt/couchbase/var/lib/couchbase/inbox
4.    Make the “inbox” your current working directory
a.    cd /opt/couchbase/var/lib/couchbase/inbox
5.    Copy certificates created with Let’s Encrypt to the inbox
a.    cp /etc/letsencrypt/live/your.domain.com/cert1.pem .
b.    cp /etc/letsencrypt/live/your.domain.com/pkey1.pem .
c.    cp /etc/letsencrypt/live/your.domain.com/fullchain.pem chain.pem
6.    Convert the private key to RSA
a.    openssl rsa -in pkey.pem > pkey.key
7.    Import the different certificates to Couchbase Server
a.    Import the ROOT-CA Cert to Couchbase
I.    /opt/couchbase/bin/couchbase-cli ssl-manage -c localhost –upload-cluster-ca=lets-encrypt-x3-rootCA.pem -u <admin_user> -p <admin_password>
b.    Import the RSA converted private key on the node
I.    /opt/couchbase/bin/couchbase-cli ssl-manage -c localhost –set-node-certificate  -u <admin_user> -p <admin_password>

Testing the configuration

To test if the configuration is working, open a web browser like FireFox, I.E. or Chrome version 50.x to the server URL via HTTPS like so:

https://myurl.com:18091/

You will see an image like the following in the address bar signifying the UI is now secured.

This is the same port you use at the application tier to secure communications between the application and the server.

If you need additional assistance with x.509 certificates you can refer to Couchbase 4.5 documentation here: http://developer.couchbase.com/documentation/server/4.5/admin/admin-intro.html

You may also send an email to austin.gonyou@couchbase.com or Don.Pinto@couchbase.com