-
Notifications
You must be signed in to change notification settings - Fork 2
TLS (SSL) Setup
Transport Layer Security (TLS), formerly known as Secure Sockets Layer (SSL), is a protocol to identify servers unambiguously, and to encrypt all data traveling between Server and Client transparently. Similarly, also the client can identify itself unambiguously to the server, if desired (which is usually not the case with public reachable internet resources. More likely, they will not ask the browser for a certificate, but rather the user for a password).
TLS relies on public/private keys: The server presents its public key ("certificate"), and the client uses this key to create and securely transmit a session key for the further encrypted communication with that server. To avoid man-in-the-middle attacks, the public key of the server itself is signed with the private key of a trustworthy organization. All browsers check such signatures and issue a warning, if a server's certificate is not signed by such an organization (Since many of these organizations are in fact controlled by the NSA, they are not all really trustworthy, but that's another story)
So, to implement TLS, you first need such a Website Certificate, which is signed by one of these organizations. Such a certificate will cost you a substantial yearly fee.
For testing purposes, or for a private server, you can use a self signed certificate. This won't cost you anything, but a visitor will get a warning of the browser, claiming a bad or invalid certificate.
-
make sure you have a Java JDK (not only a JRE) installed. The JDK contains a program called "keytool", which we need.
-
create a directory .jkeys in the home-directory of the user that will run webelexis.
-
from that directory, type the following command:
keytool -genkey -keyalg RSA -alias webelexis_server -keystore keystore.jks -storepass topSecret -validity 360 -keysize 2048(of course, you should write your own password instead of "topSecret"). Keytool will then ask you some questions about you and your organization to embed in the certificate, and at the end ask for a password for the key. Here, you should just hit <Enter> to make the key password the same as the keystore password. -
In the cfglocal.json of your webelexis installation, enter the following lines in the section "bridge":
"ssl": true, "keystore-pwd": "topSecret" -
That's all. Now, your server is reachable only with https:// (but your browser will warn you about a so-evil self-signed certificate).
Note: In spite of the browser's warning, al self-signed certificate is not less secure, than an official one. The key strength is exactly the same and depends only on the parameters you gave to keytool and the quality of the random number generator of your computer. The difference is, that someone else could issue a self-signed certificate claiming to be YOU, and so fool users to trust them, while they think they trust you ('man in the middle- attack').
There's a remedy against this, if you know your users personally: Give the users the key-fingerprint of your self-signed certificate. They can check if the server's certificate has the same fingerprint (the browser will show them in "details"), and if so, trust this certificate manually. Then, the browser will stop to warn, as long as the certificate remains the same.
It is recommended to do this only after you tested your TLS Setup successfully with a self-signed certificate.
keytool -keysize 2048 -genkey -alias webelexis_server -keyalg RSA -keystore keystore.jks
IMPORTANT: Answer keytool's questions as follows:
-
Common Name (CN), on german systems: "Wie lautet Ihr Vor- und Nachname?" Enter the full qualified name of the website, you want to protect. e.g. www.webelexis.ch (without https:// or http://). Do NOT enter your Name here, otherwise the certificate will be invalid.
-
Organizational Unit (OU), "Wie lautet der Name Ihrer organisatorischen Einheit?" Here you are free to enter whatever you want. E.g. name of the practice.
-
Organization (O), "Wie lautet der Name Ihrer Organisation?" Enter the Name of the person who is owner of the domain as named in (CN), as listet with the domain registrar. If domain and owner do not match, most CA's will refuse to sign the certificate.
-
Location (L), "Wie lautet der Name Ihrer Stadt oder Gemeinde?" This must be the same place as listet with the domain registrar as location of the domain's owner.
-
State (ST), "Wie lautet der Name Ihres Bundeslandes?" Enter the name of the "Kanton"/"Bundesland", where the domain's owner is situated. Do NOT enter an abbreviation, e.g. not "ZH" but "Zürich".
-
Country (C), "Wie lautet der Ländercode?" This is a 2-letter ISO abbreviation for the domain holder's country. e.g. "CH".
keytool -certreq -keyalg RSA -alias webelexis-server -file csr.csr -keystore keystore.jks
This will generate a file "csr.csr" in the current directory.
The ways to do this vary greatly. Most commonly, you will enter your details in a web form, pay the price and may then upload your CSR. Sometimes you can directly enter the CSR in a web form. In this case, open the csr.csr file with a plain text editor, select all, copy, and paste it into the web form.
The authority will make some checks whether you are really who you claim to are, and whether you can control the domain, you are requesting a certificate for. They will probably ask you to insert a file into the webroot or to make some specific DNS entries, or even to create a specific email account. So you have better your access details for the website and the domain registrar handy.
After successful checks, they will create your certificate and let you download it.
Most likely, you'll get two files: A root chain of the certificate authority and your signed certificate.
keytool -import -alias root -keystore keystore.jks -trustcacerts -file <filename of the root chain>
keytool -import -alias webelexis-server -keystore keystore.jks -trustcacerts -file <filename of the site certificate>
Then, make sure the keystore is, where webelexis expects it and relaunch. Try "https://<sitename>:2015" and the connection should work with a lock-symbol and without warnings about invalid certificates.