Perspectives Technical Documentation

Let’s focus first on the second purpose, protecting information. This is achieved using cryptography. The particular form of cryptography used in TLS relies on two ‘keys’: a public one and a private one. The webserver sends the public one to the browser; it is part of the certificate.

Now the imagery of two keys is not very enlightening. It is better to consider the public key to be a kind of box, that can only be unlocked by the (private) key. So the server sends a box to the browser; when the user wants to send some sensitive information to the server, the browser puts it into the box, clicks it shut and sends it back. The server can open the box with its key. No one intercepting the box along the way can open it, as they do not have the key. This is the practice of encrypting information to communicate it privately.

But wait! How do we know that the box received by the browser is, indeed, the one sent by the server? If we reckon with interceptors, what if a crook should insert his own box in the response sent by the server!? The browser puts the sensitive data in it and gone is the users secret, as the crook intercepts the reply and opens the box with his own (private) key.

So the webserver should prove its identity, or, rather, prove that the public key (box) it ships with its responses is indeed owned by it (the first purpose of TLS). This is where the certificate comes in, and with it the notion of signing.

The King’s signature on a banknote should convince people it is genuine. Only the King can create that signature and all can verify that, the King being a well-known public figure! Obviously, long gone are the days that all we needed was that signature, but the principle is clear. This is signing: only one party can put their sign on something and all others have the ability to verify it.

Now if this sounds familiar, you are right. It is just like protecting information, but the other way round:

The roles are reversed, or, rather, the keys are switched. On protecting information, the (private) key holder sends out the boxes (the public key). On signing, the (public) key holder puts something in a box, and everyone holding the (not so) private key can open it.

Because we can open the box with the King’s key, we know for sure that he is the one that put something in it (cause he keeps the unlocked boxes (=the public key) private). So signing requires distributing the (private) key; protecting requires distributing the box (public key).

To sum up where we stand: to protect information flowing from the browser to the server, we encrypt it using the public key sent by the server (the box). To make sure that public key is really owned by the server, it is signed and so becomes a certificate.

But, you may observe, haven’t we just pushed the problem a bit further away? For what is checking a certificate other than using a key (the private one, this time, issued by someone who certified the servers’ public key)? So how do we know that key is genuine?

In our minds eye we can see a chain of certifiers, each certified by someone higher up in the chain. As a matter of fact, this is exactly how it works. But the buck stops somewhere and that is with a certificate we call a root, issued by an authority.

Who decides who is an (certificate) authority and who not? This is largely the outcome of a historical process. There is now a smallish number of certificate authorities (CA’s) that are regarded as trustworthy.

You will have accessed countless websites over https and yet never spent a conscious thought on which CA you can trust. So when exactly did this happen? When did you decide to trust, say, the certificates signed by VerySign?

Well, you did not, otherwise than by using your browser and the list of CA’s trusted by the Root Program active on your computer. Such lists are compiled by the suppliers of operating systems, such as Apple and Microsoft.

When you use a Mac, you can inspect that list using the KeyChain App (it keeps your passwords safe, but it also holds the list of CA’s and certificates to trust).

To sum up: when you access a website protected with TLS, your browser receives its certificate, that holds a public key it will use to encrypt your information prior to sending it back. Before doing so it checks the certificate is signed by an authority that is in the list of authorities kept in the operating system of your computer.

You can create a self-signed certificate if you wish. The common name field in it should be https://localhost:6984. This is the secure endpoint of Couchdb on your computer.

Alternatively, you may download a certificate for this endpoint signed by Perspect IT from https://mycontexts.com/couchdb.pem. And https://mycontexts.com/privkey.pem. Notice that Perspect IT is not a certificate authority. Neither do you have to trust us; you will have to declare trust in the certificate yourself. You can safely do so, as it only certifies an endpoint on your own computer (Couchdb, that you have installed yourself).

Following the instructions for configuring https options in Couchdb (see below), put the certificate in the directory /etc/couchdb/cert. You probably may be able to store the files in another directory. If so, adapt the lines in the ssl section in your local.ini file accordingly (see below). Make sure the directory where you put the files is readable by the Couchdb process!

The official Couchdb documentation describes https options in https://docs.couchdb.org/en/latest/config/http.html#https-ssl-tls-options. From that section we’ve copied the relevant steps. Before carrying them out, stop Couchdb; after finishing, restart again.

Where to find the Couchdb configuration files is described here: https://docs.couchdb.org/en/stable/config/intro.html#configuration-files.

If you use Firefox, open the Certificate Manager (Tools > Options > Advanced > Certificates: View Certificates).

If you run Chrome or Safari on Mac OSX, open KeyChain Access. Select the Certificates Category. Drag and drop the couchdb.pem file on the right. Double click it and change the settings to “Always trust”.

We have no instructions for Microsoft Windows.