mirror/docker-mailserver.docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2025-08-04 01:55:29 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

docs: miscellaneous improvements (#3219)

Browse source 
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
This commit is contained in:
Georg Lauterbach 2023-04-08 11:54:16 +02:00 • committed by GitHub
parent a9515b49c2
commit cf8e555212
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
23 changed files with 470 additions and 364 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/content/config/security/mail_crypt.md
View file

@ -3,7 +3,7 @@ title: 'Security | mail_crypt (email/storage encryption)'
---
!!! info
The Mail crypt plugin is used to secure email messages stored in a Dovecot system. Messages are encrypted before written to storage and decrypted after reading. Both operations are transparent to the user.
In case of unauthorized access to the storage backend, the messages will, without access to the decryption keys, be unreadable to the offending party.
@ -34,11 +34,11 @@ Official Dovecot documentation: https://doc.dovecot.org/configuration_manual/mai
3. You then need to [generate your global EC key](https://doc.dovecot.org/configuration_manual/mail_crypt_plugin/#ec-key). We named them `/certs/ecprivkey.pem` and `/certs/ecpubkey.pem` in step #1.
4. The EC key needs to be available in the container. I prefer to mount a /certs directory into the container:
4. The EC key needs to be available in the container. I prefer to mount a /certs directory into the container:
```yaml
services:
mailserver:
image: docker.io/mailserver/docker-mailserver:latest
image: ghcr.io/docker-mailserver/docker-mailserver:latest
volumes:
. . .
- ./certs/:/certs
@ -49,7 +49,7 @@ Official Dovecot documentation: https://doc.dovecot.org/configuration_manual/mai
```yaml
services:
mailserver:
image: docker.io/mailserver/docker-mailserver:latest
image: ghcr.io/docker-mailserver/docker-mailserver:latest
volumes:
. . .
- ./config/dovecot/10-custom.conf:/etc/dovecot/conf.d/10-custom.conf

32
docs/content/config/security/ssl.md
View file

@ -121,7 +121,7 @@ Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store the
!!! example
Add these additions to the `mailserver` service in your [`docker-compose.yml`][github-file-compose]:
```yaml
services:
mailserver:
@ -169,7 +169,7 @@ Obtain a Cloudflare API token:
3. Click "Create Token", and choose the `Edit zone DNS` template (_Certbot [requires the `ZONE:DNS:Edit` permission](https://certbot-dns-cloudflare.readthedocs.io/en/stable/#credentials)_).
!!! warning "Only include the necessary Zone resource configuration"
Be sure to configure "Zone Resources" section on this page to `Include -> Specific zone -> <your zone here>`.
This restricts the API token to only this zone (domain) which is an important security measure.
@ -264,7 +264,7 @@ After completing the steps above, your certificate should be ready to use.
```
You can manually run this service to renew the cert within 90 days:
```sh
docker-compose run certbot-cloudflare-renew
```
@ -274,14 +274,14 @@ After completing the steps above, your certificate should be ready to use.
```log
Saving debug log to /var/log/letsencrypt/letsencrypt.log
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Processing /etc/letsencrypt/renewal/mail.example.com.conf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Account registered.
Simulating renewal of an existing certificate for mail.example.com
Waiting 10 seconds for DNS changes to propagate
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Congratulations, all simulated renewals succeeded:
/etc/letsencrypt/live/mail.example.com/fullchain.pem (success)
@ -640,7 +640,7 @@ This setup only comes with one caveat: The domain has to be configured on anothe
version: '3.8'
services:
mailserver:
image: docker.io/mailserver/docker-mailserver:latest
image: ghcr.io/docker-mailserver/docker-mailserver:latest
container_name: mailserver
hostname: mail
domainname: example.com
@ -696,10 +696,6 @@ Add `SSL_TYPE=self-signed` to your `docker-mailserver` environment variables. Po
#### Generating a self-signed certificate
!!! note
Since `docker-mailserver` v10, support in `setup.sh` for generating a _self-signed SSL certificate_ internally was removed.
One way to generate self-signed certificates is with [Smallstep's `step` CLI](https://smallstep.com/docs/step-cli). This is exactly what [`docker-mailserver` does for creating test certificates][github-file::tls-readme].
For example with the FQDN `mail.example.test`, you can generate the required files by running:
@ -821,15 +817,13 @@ These options in conjunction mean:
If you have another source for SSL/TLS certificates you can import them into the server via an external script. The external script can be found here: [external certificate import script][hanscees-renewcerts].
!!! attention "Only compatible with `docker-mailserver` releases < `v10.2`"
This is a community contributed script, and in most cases you will have better support via our _Change Detection_ service (_automatic for `SSL_TYPE` of `manual` and `letsencrypt`_) - Unless you're using LDAP which disables the service.
The script expects `/etc/postfix/ssl/cert` and `/etc/postfix/ssl/key` files to be configured paths for both Postfix and Dovecot to use.
!!! warning "Script Compatibility"
Since the `docker-mailserver` 10.2 release, certificate files have moved to `/etc/dms/tls/`, and the file name may differ depending on provisioning method.
This third-party script also has `fullchain.pem` and `privkey.pem` as hard-coded, thus is incompatible with other filenames.
Additionally it has never supported handling `ALT` fallback certificates (for supporting dual/hybrid, RSA + ECDSA).
- Relies on private filepaths `/etc/dms/tls/cert` and `/etc/dms/tls/key` intended for internal use only.
- Only supports hard-coded `fullchain.key` + `privkey.pem` as your mounted file names. That may not align with your provisioning method.
- No support for `ALT` fallback certificates (_for supporting dual/hybrid, RSA + ECDSA_).
The steps to follow are these:
@ -864,7 +858,7 @@ export SITE_URL="mail.example.com"
export SITE_IP_URL="192.168.0.72" # can also use `mail.example.com`
export SITE_SSL_PORT="993" # imap port dovecot
##works: check if certificate will expire in two weeks
##works: check if certificate will expire in two weeks
#2 weeks is 1209600 seconds
#3 weeks is 1814400
#12 weeks is 7257600
@ -921,7 +915,7 @@ if [ "$certcheck_2weeks" = "Certificate will not expire" ]; then
echo "Cert seems to be expiring pretty soon, within two weeks: $certcheck_2weeks"
echo "we will send an alert email and log as well"
logger Certwatch: cert $SITE_URL will expire in two weeks
echo "Certwatch: cert $SITE_URL will expire in two weeks" | mail -s "cert $SITE_URL expires in two weeks " $ALERT_EMAIL_ADDR
echo "Certwatch: cert $SITE_URL will expire in two weeks" | mail -s "cert $SITE_URL expires in two weeks " $ALERT_EMAIL_ADDR
fi
```

111
docs/content/config/security/understanding-the-ports.md
View file

@ -4,20 +4,31 @@ title: 'Security | Understanding the Ports'
## Quick Reference
Prefer Implicit TLS ports, they're more secure and if you use a Reverse Proxy, should be less hassle (although it's probably wiser to expose these ports directly to `docker-mailserver`).
Prefer ports with Implicit [TLS][wikipedia-tls] ports, they're more secure than ports using Explicit TLS, and if you use a Reverse Proxy should be less hassle.
## Overview of Email Ports
| Protocol | Explicit TLS<sup>1</sup> | Implicit TLS | Purpose |
|----------|--------------------------|-----------------|----------------------|
| SMTP | 25 | N/A | Transfer<sup>2</sup> |
| ESMTP | 587 | 465<sup>3</sup> | Submission |
| POP3 | 110 | 995 | Retrieval |
| IMAP4 | 143 | 993 | Retrieval |
| Protocol | Explicit TLS<sup>1</sup> | Implicit TLS | Purpose | Enabled by Default |
|--------------------------|--------------------------|-----------------|----------------------|--------------------|
| [ESMTP][wikipedia-esmtp] | 25 | N/A | Transfer<sup>2</sup> | Yes |
| ESMTP | 587 | 465<sup>3</sup> | Submission | Yes |
| POP3 | 110 | 995 | Retrieval | No |
| IMAP4 | 143 | 993 | Retrieval | Yes |
1. A connection _may_ be secured over TLS when both ends support `STARTTLS`. On ports 110, 143 and 587, `docker-mailserver` will reject a connection that cannot be secured. Port 25 is [required][ref-port25-mandatory] to support insecure connections.
2. Receives email, `docker-mailserver` additionally filters for spam and viruses. For submitting email to the server to be sent to third-parties, you should prefer the _submission_ ports (465, 587) - which require authentication. Unless a relay host is configured (eg: SendGrid), outgoing email will leave the server via port 25 (_thus outbound traffic must not be blocked by your provider or firewall_).
3. A _submission_ port since 2018 ([RFC 8314][rfc-8314]).
??? warning "Beware of outdated advice on port 465"
There is a common misconception of this port due to it's history detailed by various communities and blogs articles on the topic (_including by popular mail relay services_).
Port 465 was [briefly assigned the role of SMTPS in 1997][wikipedia-smtps] as an secure alternative to Port 25 between MTA exchanges. Then RFC 2487 (`STARTTLS`) [while still in a draft status in late 1998 had IANA revoke the SMTPS assignment][history-465-revoked]. The [draft history was modified to exclude all mention of port 465 and SMTPS][history-465-politics].
In 2018 [RFC 8314][rfc-8314] was published which revives Port 465 as an Implicit TLS alternative to Port 587 for mail submission. It details very clearly that gaining adoption of 465 as the preferred port will take time. IANA reassigned [port 465 as the `submissions` service][iana-services-465]. Any unofficial usage as **SMTPS is legacy and has been for over two decades**.
Understand that port 587 is more broadly supported due to this history and that lots of software in that time has been built or configured with that port in mind. [`STARTTLS` is known to have various CVEs discovered even in recent years][starttls-vulnerabilities], do not be misled by any advice implying it should be preferred over implicit TLS. Trust in more official sources, such as the [config Postfix has][postfix-upstream-config-mastercf] which acknowledges the `submissions` port (465).
1. A connection *may* be secured over TLS when both ends support `STARTTLS`. On ports 110, 143 and 587, `docker-mailserver` will reject a connection that cannot be secured. Port 25 is [required][ref-port25-mandatory] to support insecure connections.
2. Receives email, `docker-mailserver` additionally filters for spam and viruses. For submitting email to the server to be sent to third-parties, you should prefer the *submission* ports(465, 587) - which require authentication. Unless a relay host is configured(eg SendGrid), outgoing email will leave the server via port 25(thus outbound traffic must not be blocked by your provider or firewall).
3. A *submission* port since 2018 ([RFC 8314][rfc-8314]). Previously a secure variant of port 25.
### What Ports Should I Use? (SMTP)
@ -52,49 +63,101 @@ flowchart LR
#### Inbound Traffic (On the left)
- **Port 25:** Think of this like a physical mailbox, it is open to receive email from anyone who wants to. `docker-mailserver` will actively filter email delivered on this port for spam or viruses and refuse mail from known bad sources. While you could also use this port internally to send email outbound without requiring authentication, you really should prefer the *Submission* ports(587, 465).
- **Port 465(*and 587*):** This is the equivalent of a post office box where you would send email to be delivered on your behalf(`docker-mailserver` is that metaphorical post office, aka the MTA). Unlike port 25, these two ports are known as the *Submission* ports and require a valid email account on the server with a password to be able to send email to anyone outside of the server(an MTA you do not control, eg Outlook or Gmail). Prefer port 465 which provides Implicit TLS.
Mail arriving at your server will be processed and stored in a mailbox, or sent outbound to another mail server.
- **Port 25:**
- Think of this like a physical mailbox, anyone can deliver mail to you here. Typically most mail is delivered to you on this port.
-`docker-mailserver` will actively filter email delivered on this port for spam or viruses, and refuse mail from known bad sources.
- Connections to this port may be secure through STARTTLS, but is not mandatory as [mail is allowed to arrive via an unencrypted connection][ref-port25-mandatory].
- It is possible for internal clients to submit mail to be sent outbound (_without requiring authentication_), but that is discouraged. Prefer the _submission_ ports.
- **Port 465 and 587:**
- This is the equivalent of a post office box where you would send email to be delivered on your behalf (_`docker-mailserver` is that metaphorical post office, aka the MTA_).
- These two ports are known as the _submission_ ports, they enable mail to be sent outbound to another MTA (eg: Outlook or Gmail) but require authentication via a [mail account][docs-accounts].
- For inbound traffic, this is relevant when you send mail from your MUA (eg: ThunderBird). It's also used when `docker-mailserver` is configured as a mail relay, or when you have a service sending transactional mail (_eg: order confirmations, password resets, notifications_) through `docker-mailserver`.
- _**Prefer port 465**_ over port 587, as 465 provides Implicit TLS.
!!! note
When submitting mail (inbound) to be sent (outbound), this involves two separate connections to negotiate and secure. There may be additional intermediary connections which `docker-mailserver` is not involved in, and thus unable to ensure encrypted transit throughout delivery.
#### Outbound Traffic (On the Right)
- **Port 25:** Send the email directly to the given email address MTA as possible. Like your own `docker-mailserver` port 25, this is the standard port for receiving email on, thus email will almost always arrive to the final MTA on this port. Note that, there may be additional MTAs further in the chain, but this would be the public facing one representing that email address.
- **Port 465(*and 587*):** SMTP Relays are a popular choice to hand-off delivery of email through. Services like SendGrid are useful for bulk email(marketing) or when your webhost or ISP are preventing you from using standard ports like port 25 to send out email(which can be abused by spammers).
`docker-mailserver` can serve as a relay too, but the difference between a DIY relay and a professional service is reputation, which is referenced by MTAs you're delivering to such as Outlook, Gmail or others(perhaps another `docker-mailserver` server!), when deciding if email should be marked as junked or potentially not delivered at all. As a service like SendGrid has a reputation to maintain, relay is restricted to registered users who must authenticate(even on port 25), they do not store email, merely forward it to another MTA which could be delivered on a different port like 25.
Mail being sent from your server is either being relayed through another MTA (eg: SendGrid), or direct to an MTA responsible for an email address (eg: Gmail).
- **Port 25:**
- As most MTA use port 25 to receive inbound mail, when no authenticated relay is involved this is the outbound port used.
- Outbound traffic on this port is often blocked by service providers (eg: VPS, ISP) to prevent abuse by spammers. If the port cannot be unblocked, you will need to relay outbound mail through a service to send on your behalf.
- **Port 465 and 587:**
- Submission ports for outbound traffic establish trust to forward mail through a third-party relay service. This requires [authenticating to an account on the relay service][docs-relays]. The relay will then deliver the mail through port 25 on your behalf.
- These are the two typical ports used, but smart hosts like SendGrid often document support for additional non-standard ports as alternatives if necessary.
- Usually you'll only use these outbound ports for relaying. It is possible to deliver directly to the relevant MTA for email address, but requires having credentials for each MTA.
!!! tip
`docker-mailserver` can function as a relay too, but professional relay services have a trusted reputation (_which increases success of delivery_).
An MTA with low reputation can affect if mail is treated as junk, or even rejected.
!!! note
At best, you can only ensure a secure connection between the MTA you directly connect to. The receiving MTA may relay that mail to another MTA (_and so forth_), each connection may not be enforcing TLS.
### Explicit vs Implicit TLS
#### Explicit TLS (aka Opportunistic TLS) - Opt-in Encryption
Communication on these ports begin in [cleartext][ref-clear-vs-plain], indicating support for `STARTTLS`. If both client and server support `STARTTLS` the connection will be secured over TLS, otherwise the connection is unable to use encryption to secure it. By default, `docker-mailserver` is configured to reject connections that fail to establish a secure connection when authentication is required, rather than allow an insecure connection (_Port 25 will allow receiving unencrypted deliveries which doesn't require authentication_).
Communication on these ports begin in [cleartext][ref-clear-vs-plain]. Upgrading to an encrypted connection must be requested explicitly through the `STARTTLS` protocol **and** successfully negotiated.
Support for `STARTTLS` is not always implemented correctly, which can lead to leaking credentials(client sending too early) prior to a TLS connection being established. Third-parties such as some ISPs have also been known to intercept the `STARTTLS` exchange, modifying network traffic to prevent establishing a secure connection.
Sometimes a reverse-proxy is involved, but is misconfigured or lacks support for the `STARTTLS` negotiation to succeed.
!!! note
- By default, `docker-mailserver` is configured to reject connections that fail to establish a secure connection (_when authentication is required_), rather than allow an insecure connection.
- Port 25 does not require authentication. If `STARTTLS` is unsuccessful, mail can be received over an unencrypted connection. You can better secure this port between trusted parties with the addition of MTA-STS, [STARTTLS Policy List][starttls-policy-list], DNSSEC and DANE.
!!! warning
`STARTTLS` [continues to have vulnerabilities found][starttls-vulnerabilities] (Nov 2021 article), as per [RFC 8314 (Section 4.1)][rfc-8314-s41] you are encouraged to **prefer Implicit TLS where possible**.
Support for `STARTTLS` is not always implemented correctly, which can lead to leaking credentials (like a client sending too early) prior to a TLS connection being established. Third-parties such as some ISPs have also been known to intercept the `STARTTLS` exchange, modifying network traffic to prevent establishing a secure connection.
Due to these security concerns, [RFC 8314 (Section 4.1)][rfc-8314-s41] encourages you to **prefer Implicit TLS ports where possible**.
#### Implicit TLS - Enforced Encryption
Communication is always encrypted, avoiding the above mentioned issues with Explicit TLS.
Communication on these ports are always encrypted (_enforced, thus implicit_), avoiding the potential risks with `STARTTLS` (Explicit TLS).
You may know of these ports as **SMTPS, POP3S, IMAPS**, which indicate the protocol in combination with a TLS connection. However, Explicit TLS ports provide the same benefit when `STARTTLS` is successfully negotiated; Implicit TLS better communicates the improved security to all three protocols (SMTP/POP3/IMAP over Implicit TLS).
While Explicit TLS can provide the same benefit (_when `STARTTLS` is successfully negotiated_), Implicit TLS more reliably avoids concerns with connection manipulation and compatibility.
Additionally, referring to port 465 as *SMTPS* would be incorrect, as it is a submissions port requiring authentication to proceed via *ESMTP*, whereas ESMTPS has a different meaning(STARTTLS supported). Port 25 may lack Implicit TLS, but can be configured to be more secure between trusted parties via MTA-STS, STARTTLS Policy List, DNSSEC and DANE.
## Security
!!! todo
This section should provide any related configuration advice, and probably expand on and link to resources about DANE, DNSSEC, MTA-STS and STARTTLS Policy list, with advice on how to configure/setup these added security layers.
!!! todo
A related section or page on ciphers used may be useful, although less important for users to be concerned about.
### TLS connections for a Mail-Server, compared to web browsers
Unlike with HTTP where a web browser client communicates directly with the server providing a website, a secure TLS connection as discussed below is not the equivalent safety that HTTPS provides when the transit of email (receiving or sending) is sent through third-parties, as the secure connection is only between two machines, any additional machines (MTAs) between the MUA and the MDA depends on them establishing secure connections between one another successfully.
Unlike with HTTP where a web browser client communicates directly with the server providing a website, a secure TLS connection as discussed below does not provide the equivalent safety that HTTPS does when the transit of email (receiving or sending) is sent through third-parties, as the secure connection is only between two machines, any additional machines (MTAs) between the MUA and the MDA depends on them establishing secure connections between one another successfully.
Other machines that facilitate a connection that generally aren't taken into account can exist between a client and server, such as those where your connection passes through your ISP provider are capable of compromising a cleartext connection through interception.
Other machines that facilitate a connection that generally aren't taken into account can exist between a client and server, such as those where your connection passes through your ISP provider are capable of compromising a `cleartext` connection through interception.
[docs-accounts]: ../user-management/accounts.md
[docs-relays]: ../advanced/mail-forwarding/relay-hosts.md
[iana-services-465]: https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=465
[starttls-policy-list]: https://github.com/EFForg/starttls-everywhere#email-security-database-starttls-policy-list
[starttls-vulnerabilities]: https://blog.apnic.net/2021/11/18/vulnerabilities-show-why-starttls-should-be-avoided-if-possible/
[ref-clear-vs-plain]: https://www.denimgroup.com/resources/blog/2007/10/cleartext-vs-pl
[ref-port25-mandatory]: https://serverfault.com/questions/623692/is-it-still-wrong-to-require-starttls-on-incoming-smtp-messages
[rfc-8314]: https://tools.ietf.org/html/rfc8314
[rfc-8314-s41]: https://tools.ietf.org/html/rfc8314#section-4.1
[history-465-revoked]: https://web.archive.org/web/20150603202057/http://www.imc.org/ietf-apps-tls/mail-archive/msg00204.html
[history-465-politics]: https://mailing.postfix.users.narkive.com/F3ACwg2F/which-port-to-use-for-ssl-tls#post21
[postfix-upstream-config-mastercf]: https://github.com/vdukhovni/postfix/blob/62931e5b1f9f1e80d02a496c7fd0062a5aae1d25/postfix/conf/master.cf#L38-L41
[wikipedia-smtps]: https://en.wikipedia.org/wiki/SMTPS#History
[wikipedia-esmtp]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol#Modern_SMTP
[wikipedia-tls]: https://en.wikipedia.org/wiki/Transport_Layer_Security