mongoose/docs/SSL.md

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.