Providing encrypted web access to Etherpad Lite using SSL certificates

rugk edited this page Dec 8, 2015 · 4 revisions



For Developers

How to's

Set up

Advanced steps

Integrating Etherpad in your web app

for Developers

Clone this wiki locally


General warning: incorrectly written plugins may impose risks of mixed https/http content

when referencing an insecure (http) resource within a secure (https) page. Such references create vulnerabilities that put the privacy and integrity of an otherwise-secure page at risk, because the insecure content could be modified in transit. If added to the DOM, insecurely-delivered content can read or alter the rest of the page even if the bulk of the page was delivered over a secure connections. (source)


The following information has been carefully collected but may contain errors or may be fully or partially outdated. Please use the description with care.
Familiarise yourself with the SSL concept and get a second opinion of SSL, server keys and encrypted transmission by studying also other web resources. Relax, stay cool and try the commands below first in a test environment, where you then can easily delete all created files.
Only deploy SSL to your production system if you exactly know what you are doing.

By default, Etherpad Lite runs via http:// which is unsecure in many respects, for example regarding the transmission of admin or user passwords in plain text, and also regarding confidential pad contents. When using http.

But there is hope.

As a server admin you can set up your Etherpad Lite to use the native https server part of Node and Express framework in a fully secure way. There is no need for using an additional Apache or Nginx server or proxy.

The following description for Linux assume that you want to

  • generate self-signed keys
  • which are valid for 9000 days.

If you want to have your key signed by an approved Certificate Authority (CA), it's getting a bit more difficult and you often need to pay yearly. However there are several CAs which also offer free certificates which are also accepted by all mayor browser. Namely this are StartSSL (offers uncommercial certs valid for one year), WoSign - a Chinese CA, which offers certs valid up to three years and the new service Let's Encrypt, which not only offers free certificates, but also makes it possible to completely automate the process of renewal and getting a certificate in a very simple way. If you want to use Let's Encrypt you just need to install a Python script and enter some commands. For all other CAs you currently have to follow the steps below.

Some intermediate files will be generated but not explained here, too keep it concise. Read the page in "References" if you are curious what they are for.

  • uncomment the SSL section in the settings.json of your EPL installation
  • generate a file epl-server.key which does not require a password
# Generate the server key
openssl genrsa -des3 -out epl-server.key 4096
# Remark: the default parameters for certificates (CN, O, OU ..) are retrieved from
# /etc/ssl/openssl.conf 
openssl req -new -key epl-server.key -out epl-server.csr
openssl x509 -req -days 9000 -in epl-server.csr -signkey epl-server.key -out epl-server.crt

# Let's make a version of the server key which does not require a password when the server starts
openssl rsa -in epl-server.key -out epl-server.key.insecure
mv epl-server.key
mv epl-server.key.insecure epl-server.key
  • Generate a second key as your own "Certificate Authority" (CA) with which you can self-sign the epl-server.key
# Generate a second (temporary) key as the key of your own CA
openssl genrsa -des3 -out own-ca.key 4096

# When being asked for the Common Name CN, enter your our Common Name and add " (CA)" to it.
# Rationale: CN of your server key must be somehow distinct from the CN of your own-CA certificate.
openssl req -new -x509 -days 9000 -key own-ca.key -out own-ca.crt

# Sign your epl-server.key with the certificate of your own CA resulting in a self-signed epl-server.key
openssl x509 -req -days 9000 -in epl-server.csr -CA own-ca.crt -CAkey own-ca.key -set_serial 001 -out epl-server.crt
  • deploy the two files (epl-server.key and epl-sever.crt) on your server, so that only the etherpad (process, task, program) user can access this sensitive data
# Set secure file permissions: only the Etherpad lite process must be able to read them
chmod 400 epl-server.key
chown etherpad epl-server.key
chmod 400 epl-server.crt
chown etherpad epl-server.crt
  • The following files have been created during the above steps but are not needed for running the SSL server. You can move these files to a safe place or simply delete them - unless you later want to create further keys based upon the originally generated server keys, and unless you later want to generate newly signed versions. Then you should save these files somewhere else.
# These files are not needed when running the Etherpad using SSL and can be saved elsewhere or deleted
rm epl-server.csr
rm own-ca.key
rm own-ca.crt
  • restart your EPL server

general SSL risk: "man in the middle" (MITM) attack

An important thing is to tell users what a "fingerprint of the server key" is and how they can check whether the received fingerprint in the current browser connection matches the correct server fingerprint. (Details will be added later, I just wanted to mention it.)

Checking fingerprints of public keys

You can print the (sha256, sha1, md5) fingerprints of the certificate and then verify them with the values shown in your browser

openssl x509 -fingerprint -sha256 -noout -in epl-server.crt 
openssl x509 -fingerprint -sha1 -noout -in epl-server.crt 
openssl x509 -fingerprint -md5 -noout -in epl-server.crt 

The fingerprint of the server key of the local machine can be printed by using

ssh-keygen -lf /etc/ssh/