1 files changed, 93 insertions, 0 deletions
diff --git a/doc/wiki/SSL.CertificateCreation.txt b/doc/wiki/SSL.CertificateCreation.txt
new file mode 100644
index 0000000..59dcfe0
--- /dev/null
+++ b/doc/wiki/SSL.CertificateCreation.txt
@@ -0,0 +1,93 @@
+SSL certificate creation
+========================
+
+Self-signed SSL certificates
+----------------------------
+
+Self-signed SSL certificates are the easiest way to get your SSL server
+working. However unless you take some action to prevent it,*this is at the cost
+of security*:
+
+ * The first time the client connects to the server, it sees the certificate
+   and asks the user whether to trust it. The user of course doesn't really
+   bother verifying the certificate's fingerprint, so a man-in-the-middle
+   attack can easily bypass all the SSL security, steal the user's password and
+   so on.
+ * If the client was lucky enough not to get attacked the first time it
+   connected, the following connections will be secure as long as the client
+   had permanently saved the certificate. Some clients do this, while others
+   have to be manually configured to accept the certificate.
+
+The only way to be fully secure is to import the SSL certificate to client's
+(or operating system's) list of trusted CA certificates prior to first
+connection. See <SSL.CertificateClientImporting.txt> how to do it for different
+clients.
+
+Self-signed certificate creation
+--------------------------------
+
+Dovecot includes a script to build self-signed SSL certificates using OpenSSL.
+In the source distribution this exists in doc/mkcert.sh
+[http://dovecot.org/doc/mkcert.sh]. Binary installations usually create the
+certificate automatically when installing Dovecot and don't include the script.
+
+The SSL certificate's configuration is taken from doc/dovecot-openssl.cnf
+[http://dovecot.org/doc/dovecot-openssl.cnf] file. Modify the file before
+running mkcert.sh. Especially important field is the CN (Common Name) field,
+which should contain your server's host name. The clients will verify that the
+CN matches the connected host name, otherwise they'll say the certificate is
+invalid. It's also possible to use wildcards (eg. *.domain.com) in the host
+name. They should work with most clients.
+
+By default the certificate is created to '/etc/ssl/certs/dovecot.pem' and the
+private key file is created to '/etc/ssl/private/dovecot.pem'. Also by default
+the certificate will expire in 365 days. If you wish to change any of these,
+modify the mkcert.sh script.
+
+Certificate Authorities
+-----------------------
+
+The correct way to use SSL is to have each SSL certificate signed by an
+Certificate Authority (CA). The client has a list of trusted Certificate
+Authorities, so whenever it sees a new SSL certificate signed by a trusted CA,
+it will automatically trust the new certificate without asking the user any
+questions.
+
+There are two ways to get a CA signed certificate: get it from an external CA,
+or create your own CA.
+
+The clients have a built-in list of trusted CAs, so getting it from one of
+those CAs will have the advantage of the certificate working without any client
+configuration. There are already-trusted-CAs where you can buy the certificate,
+and there are already-trusted-CAs where you can get your certificate for free.
+On the oher hand, if you create your own CA, you'll have to install the CA
+certificate to all the clients (see <SSL.CertificateClientImporting.txt>).
+
+So the two options end up being three:
+
+ * a) Get it from an external CA (which already have the public keys installed
+   on the clients, so the clients trust the CA)
+    * a.1) Purchase the certificate.
+    * a.2) Get a free certificate.
+ * b) Create your own CA (in this case you'll have to add the CA public keys
+   into the clients, as you are bot trusted by default)
+
+If you choose "a.2)", there is letsencrypt.org [https://letsencrypt.org/] where
+you need to do some technical effort to demonstrate to a robot that you own the
+domains for which the certificate is issued. Let's encrypt is an initiative of
+the Internet Security Research Group (ISRG), with board members from Cisco,
+Mozilla and the University of Michingan among others and technical advisors
+from Akamai, Google, Electronic Frontier Foundation, Internet Sociaty and
+independents among others. Let's encrypt CA is trusted by default by many
+clients. If you can control the entries in your DNS, you'll be able to
+demonstrate to the robot that "you are you" for domain-based identities. There
+is this specific conversation about letsencrypt + dovecot here
+[https://community.letsencrypt.org/t/simple-guide-using-lets-encrypt-ssl-certs-with-dovecot/2921].
+
+If you choose "b)", there are multiple different tools for managing your own
+CA. The simplest way is to use a CA managing tool as gnoMint
+[http://gnomint.sourceforge.net/] or TinyCA [http://tinyca.sm-zone.net/].
+However, if you need to tailor the properties of the CA, you always can use
+OpenSSL, very much customizable, but however a bit cumbersome.
+
+(This file was created from the wiki on 2019-06-19 12:42)