Skip to end of metadata
Go to start of metadata


Secure Socket Layer (SSL) is used in conjunction with HTTP to secure web traffic. The resulting protocol is known as HTTPS. In order to utilize SSL, you must generate a key and cert. Additionally, if you want your web traffic to be safely accepted by most web browsers, you will need the cert to be signed by a CA (Certificate Authority). Otherwise, if you bypass the CA, you have the option of self signing your certificate.

Production Security

Apache CouchDB leverages Erlang/OTP's SSL, which is usually linked against a system-provided OpenSSL installation. The security, performance & compatibility with other browsers and operating systems therefore varies heavily depending on how the underlying OpenSSL library was set up.  It is strongly recommended that for production deployments, a dedicated well-known SSL/TLS terminator is used instead. There is nothing fundamentally wrong with Erlang's crypto libraries, however a dedicated TLS application is generally a better choice, and allows tuning and configuring your TLS settings directly rather than relying on whatever Erlang/OTP release is provided by your operating system.

The following have been used at times within the CouchDB community:

Key & CSR Procedure using OpenSSL

OpenSSL is an open source SSL utility and library. It comes standard with many UNIX/LINUX distributions. We will use OpenSSL to generate our private key and generate our certificate signing request (CSR).

Generate Key with OpenSSL

The private key is a special file that must never be revealed to the outside world. It holds a secret that only our CouchDB server should see. CouchDB uses this secret to encrypt traffic and prove to clients that it is the rightful owner to the cert it holds.

Generate Certificate Signing Request with OpenSSL

During the signing process, you will be asked a number of questions. Most CA's will only require you to answer the following fields: country, state, locality, organizational name, common name. Other fields should be left blank

Self Signed Certificates

If you don't require the SSL to be signed by a CA, you can self sign. This is a quick and dirty method that doesn't provide a lot of trust between different parties, but it is great for isolated systems.

Many browsers are now requiring SHA2 signed certs, which is controlled by the -sha256 option in the command.

Requesting CA Signed Cert with Free Service (Comodo)

The most "official" way of obtaining a certificate is to find a recognized CA and request your CSR to be signed. For the sake of this tutorial, we will use a free service from Comodo:

Go to this page:

Fill the form as follows:

  1. Copy and paste your CSR into this box: <PASTE CONTENTS OF SERVER.CSR HERE>
  2. Select the server software used to generate the CSR: OTHER
  3. Select the hash algorithm you would prefer us to use when signing your Certificate: SHA-2

Click the "Next" button.

Continue follow the prompts so that email authorization is sent to the owner of the domain specified by the CSR (in our example, the domain was, so the official contact for that domain will be looked up in DNS).

Once you finish proving that you have permission to represent the domain in question, you will eventually be emailed the certificate, along with the intermediate and root certificates.

Saving the Server Certificate

When your CA (in this case Comodo) emails you your certificate, it will sometimes appear in the body of the email. Copy this certificate, starting with "-----BEGIN CERTIFICATE-----" and ending with "-----END CERTIFICATE-----" and paste it into a file named "server.crt". This file represents a public signature derived from the private key we generated earlier (i.e. "server.key").

Creating the Chained CA Cert File

Some clients will require a chain of certs to clear a server cert (in our case, the server cert is the server.crt file). The Comodo CA will email you these files in an attached zip file. These files are the following:

  1. COMODORSAAddTrustCA.crt
  2. COMODORSADomainValidationSecureServerCA.crt
  3. AddTrustExternalCARoot.crt

Combine the contents of these files into a single file, called "comodo.crt". NOTE: This is the only file in this tutorial that is not specific to our server. Other servers from Comodo will be using the same chained certificates to show the chain of authorization all the way up to the root server.

Making Accessible by CouchDB

In order for CouchDB to be able to access and use the certificates, you will need to make sure they are owned by the CouchDB user. Additionally, you will want to restrict other users from accessing these files by modifying the permissions to 600 (only owner can read and write).

Configuring CouchDB To Use The Certificates

Finally, we get back to our CouchDB server. Open up your local.ini file. On Ubuntu, this file can be found in /usr/local/etc/couchdb or /etc/couchdb/local.ini.

Add the following key value pairs to the specified sections:

Disabling CouchDB HTTP layer

It is possible to disable the existing HTTP layer completely, so only allowing HTTPS access - albeit not cleanly, by amending /usr/local/etc/couchdb/default.ini [daemons ]  section accordingly:


Currently it is not possible to disable it in the more common /usr/local/etc/couchdb/local.ini [daemons ]  file.

Accessing and Verifying SSL

By default, CouchDB uses port 6984 for HTTPS. If our server lives locally, we can verify SSL works properly by accessing this URL:


Your web browser should show a lock icon next to the URL. If you click this lock icon, you should be able to see information about your certificate and the CA that signed it.

To verify your SSL is configured correctly, use one of the following sites:

Issues and Problems

As CouchDB's TLS support is directly related to whatever is bundled with the OS (Erlang and OpenSSL library), at times these versions are too old to support the latest crypto deployed by web browsers and other tools.

For example, the process described in this tutorial has some issues when using CouchDB 1.6.1 on Ubuntu 14.04 LTS. When a CouchDB HTTPS page is viewed in Safari, it works fine. The check works fine. However, when viewed in the latest builds of Firefox and Chrome, the page will not load. Firefox gives the following error:

Secure Connection Failed

An error occurred during a connection to The key does not support the requested operation. (Error code: sec_error_invalid_key)

The page you are trying to view cannot be shown because the authenticity of the received data could not be verified.
Please contact the website owners to inform them of this problem.

On Chrome, the following issue is given:

This webpage is not available

The webpage at might be temporarily down or it may have moved permanently to a new web address.

This SSL problem does not occur in CouchDB 1.6.1 on Ubuntu 14.10.


  • No labels