Docs added

docs/SSL.md

@@ -0,0 +1,75 @@
+# Mongoose SSL guide
+
+SSL is a protocol that makes web communication secure. To enable SSL
+in mongoose, 3 steps are required:
+
+   1. Valid certificate file must be created
+   2. `ssl_certificate` options must be set to contain path to the
+       certificate file.
+   3. `listening_ports` option must contain a port number with letter `s`
+        appended to it, which instructs Mongoose to use SSL for all connections
+        made to that port.
+
+Below is the `mongoose.conf` file snippet for typical SSL setup:
+
+    document_root     www_root        # Serve files in www_root directory
+    listening_ports   80r,443s        # Redirect all HTTP requests to HTTPS
+    ssl_certificate   ssl_cert.pem    # Location of certificate file
+
+## How to create SSL certificate file
+
+SSL certificate file is a text file that must contain at least two
+sections:
+
+   1. A private key
+   2. A certificate
+
+Both sections should be chunks of text in PEM format. When PEM file is
+opened in a text editor, it looks like this:
+
+    -----BEGIN RSA PRIVATE KEY-----
+    MIIEogIBAAKCAQEAwONaLOP7EdegqjRuQKSDXzvHmFMZfBufjhELhNjo5KsL4ieH
+    hYN0Zii2yTb63jGxKY6gH1R/r9dL8kXaJmcZrfSa3AgywnteJWg=
+    -----END RSA PRIVATE KEY-----
+    -----BEGIN CERTIFICATE-----
+    MIIDBjCCAe4CCQCX05m0b053QzANBgkqhkiG9w0BAQQFADBFMQswCQYDVQQGEwJB
+    SEGI4JSxV56lYg==
+    -----END CERTIFICATE-----
+
+Two aforementioned sections are clearly seen. Typically, those section
+are bigger then in the example shown. The text between the `BEGIN` and
+`END` is the text representation of binary data, a private key and a
+certificate. Therefore, in order to create a certificate file,
+
+   * private key must be converted to PEM format
+   * certificate must be converted to PEM format
+   * those two should be concatenated into a single file
+
+If the certificate chain in used, a chain file also needs to be
+converted into PEM format and appended to the certificate file.
+
+## How SSL works
+
+SSL is a protocol that can encrypt communication between two parties. If third
+party observes all messages passed by, it would be very
+hard for the third party (though not impossible) to decrypt the communication.
+
+The idea is based on so-called public key encryption. Communicating parties
+have two keys: a public key and a private key. A public key is advertised
+to everybody, and it is contained in a certificate. A private key is kept
+secret. Security algorithm works in a way that anybody can encrypt
+a message using public key, and only private key can decrypt it.
+
+This is why web server needs both private key and certificate: private key
+is used to decrypt incoming messages, and certificate is used to tell the
+public key to the other party. When communication starts, parties exchange
+their public keys, and keep private keys to themselves. Man-in-the-middle
+who observes the communication is unable to decrypt the messages cause
+private keys are required for decryption.
+
+Encryption algorithms are built on top of hard mathematical problem, which
+makes it very expensive for man-in-the-middle to compute private keys.
+For example, RSA algorithm is based on a mathematical problem of factorization.
+It is easy to generate two very large prime numbers `P` and `Q` and make
+a product `P * Q`. But given a product, it is very hard to recover these
+two prime numbers - this is called factorization.