diff --git a/content/documentation/cookbook/tls-encryption.md b/content/documentation/cookbook/tls-encryption.md index 9f05fe7..0a2711b 100644 --- a/content/documentation/cookbook/tls-encryption.md +++ b/content/documentation/cookbook/tls-encryption.md @@ -3,4 +3,51 @@ title = "TLS" weight = 30 +++ -Todo +In the [Configuration File](@/documentation/cookbook/config.md) page of the cookbook, we configure a cleartext IMAP service +that is unsecure, as anyone spying on the network can intercept the user's password. + +## Activate IMAP TLS + +You must replace the `[imap_unsecure]` block of your configuration file with a new `[imap]` block: + +```toml +[imap] +bind_addr = "[::]:993" +certs = "cert.pem" +key = "key.pem" +``` + +## Generate self-signed certificates + +If you want to quickly try the TLS endpoint, you can generate a self-signed certificate with openssl: + +```bash +openssl ecparam -out key.pem -name secp256r1 -genkey +openssl req -new -key key.pem -x509 -nodes -days 365 -out cert.pem +``` + +This configuration is not secure as it is vulnerable to man-in-the-middle attacks. +It will also triggers a big red warning in many email clients, and sometimes it will even be impossible to configure an account. + + +## Generate valid certificates through Let's Encrypt + +Automated certificate renewal has been popularized by Let's Encrypt through the [ACME protocol](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment). +Today, many certificate providers implement it, like ZeroSSL, Buypass Go SSL, or even Google Cloud. +Many clients that implement the ACME protocol exist (certbot, lego, etc.), [a very long list exist on LE website](https://letsencrypt.org/docs/client-options/). +Finally, certificates can be obtained in exchange of a validation, that can occur over HTTP (HTTP01 challenge) or DNS (DNS01 challenge). +This example will be given for Let's Encrypt with Lego for a DNS01 challenge with Gandi as the DNS provider. + +```bash +GANDIV5_API_KEY=xxx \ +GANDIV5_PERSONAL_ACCESS_TOKEN=xxx \ +lego --email you@example.tld --dns gandiv5 --domains imap.example.tld --domains smtp.example.tld run +``` + +*Note: theoretically only `GANDIV5_PERSONAL_ACCESS_TOKEN` should be required, but it did not work for me.* + +If the command ran successfully, you now have 2 files: + - `.lego/certificates/imap.example.tld.crt` + - `.lego/certificates/imap.example.tld.key` + +You can directly use them in Aerogramme (the first one must be put on `certs` and the second one on `key`).