From 97faa0beead9bc57f4efb8e8ff4ca68609d92d53 Mon Sep 17 00:00:00 2001 From: Brennan Kinney <5098581+polarathene@users.noreply.github.com> Date: Tue, 6 Sep 2022 14:01:46 +1200 Subject: [PATCH] docs: fix reference info to smtps (#3950) This PR aligns some information missed in a previous update. --- .../en/configuration/notifications/smtp.md | 11 +++- docs/content/en/overview/security/measures.md | 60 ++++++++++++------- 2 files changed, 48 insertions(+), 23 deletions(-) diff --git a/docs/content/en/configuration/notifications/smtp.md b/docs/content/en/configuration/notifications/smtp.md index db26db884..c29dede50 100644 --- a/docs/content/en/configuration/notifications/smtp.md +++ b/docs/content/en/configuration/notifications/smtp.md @@ -56,9 +56,14 @@ host: "[fd00:1111:2222:3333::1]" {{< confkey type="integer" required="yes" >}} -The port the SMTP service is listening on. Port 465 is treated as a special port where the entire connection is over -TLS. This port was formerly known as the SMTPS port but is now known as the SUBMISSIONS port i.e. SUBMISSION Secure. All -other ports expect to perform a STARTTLS negotiation. +The port the SMTP service is listening on. + +A connection is securely established with TLS after a succesful STARTTLS negotiation. + +[Port 465 is an exception][docs-security-smtp-port] when supported by the mail server as a `submissions` service port. +STARTTLS negotiation is not required for this port, the connection is implicitly established with TLS. + +[docs-security-smtp-port]: ../../overview/security/measures.md#smtp-ports ### timeout diff --git a/docs/content/en/overview/security/measures.md b/docs/content/en/overview/security/measures.md index c758e9d9c..17d9dc17b 100644 --- a/docs/content/en/overview/security/measures.md +++ b/docs/content/en/overview/security/measures.md @@ -147,30 +147,32 @@ If you wish to change your encryption key for any reason you can do so using the ## Notifier security measures (SMTP) -The SMTP Notifier implementation does not allow connections that are not secure without changing default configuration +The SMTP Notifier implementation does not allow connections that are not secure without changing default configuration values. As such all SMTP connections require the following: -1. TLS Connection (STARTTLS or SMTPS) has been negotiated before authentication or sending emails (unauthenticated -connections require it as well) +1. A TLS Connection (STARTTLS or implicit) has been negotiated before authentication or sending emails (_unauthenticated + connections require it as well_) 2. Valid X509 Certificate presented to the client during the TLS handshake There is an option to disable both of these security measures however they are __not recommended__. -The following configuration options exist to configure the security level in order of most preferable to least +The following configuration options exist to configure the security level in order of most preferable to least preferable: ### Configuration Option: certificates_directory -You can [configure a directory](../../configuration/miscellaneous/introduction.md#certificates_directory) of certificates for Authelia +You can [configure a directory](../../configuration/miscellaneous/introduction.md#certificates_directory) of +certificates for Authelia to trust. These certificates can either be CA's or individual public certificates that should be trusted. These are added in addition to the environments PKI trusted certificates if available. This is useful for trusting a certificate that is self-signed without drastically reducing security. This is the most recommended workaround to not having a valid PKI trusted certificate as it gives you complete control over which ones are trusted without disabling critically needed validation of the identity of the target service. -Read more in the [documentation](../../configuration/miscellaneous/introduction.md#certificates_directory) for this option. +Read more in the [documentation](../../configuration/miscellaneous/introduction.md#certificates_directory) for this +option. ### Configuration Option: tls.skip_verify @@ -181,23 +183,41 @@ attacks could intercept emails from Authelia compromising a user's security with ### Configuration Option: disable_require_tls -Authelia by default ensures that the SMTP server connection is secured via STARTTLS or SMTPS prior to sending sensitive -information. The [disable_require_tls](../../configuration/notifications/smtp.md#disable_require_tls) disables this requirement -which means the emails are sent in plain text. This is the least secure option as it effectively removes the validation -of SMTP certificates and removes the encryption offered by the STARTTLS/SMTPS connection all together. +Authelia by default ensures that the SMTP server connection is secured via TLS prior to sending sensitive information. -This means not only can the vulnerabilities of the [skip_verify](#configuration-option-tlsskip_verify) option be -exploited, but any router or switch along the route of the email which receives the packets could be used to silently -exploit the plain text nature of the email. This is only usable currently with authentication disabled (comment out the -password) and as such is only an option for SMTP servers that allow unauthenticated relay (bad practice). +The [disable_require_tls](../../configuration/notifications/smtp.md#disable_require_tls) option disables this +requirement which means the emails may be sent in cleartext. This is the least secure option as it effectively removes +the validation of SMTP certificates and makes using an encrypted connection with TLS optional. -### SMTPS vs STARTTLS +This means not only can the vulnerabilities of the [skip_verify](#configuration-option-tlsskip_verify) option be +exploited, but any router or switch along the route of the email which receives the packets could be used to silently +exploit the cleartext nature of the connection to manipulate the email in transit. -All connections start as plain text and are upgraded via STARTTLS. SMTPS is an exception to this rule where the -connection is over TLS. As SMTPS is deprecated, the only way to configure this is to set the SMTP -[port](../../configuration/notifications/smtp.md#port) to the officially recognized SMTPS port of 465 which will cause Authelia -to automatically consider it to be a SMTPS connection. As such your SMTP server, if not offering SMTPS, should not be -listening on port 465 which is bad practice anyway. +This is only usable currently with authentication disabled (_comment out the password_), and as such is only an option +for SMTP servers that allow unauthenticated relaying (bad practice). + +### SMTP Ports + +All SMTP connections begin as [cleartext], and then negotiate to upgrade to a secure TLS connection via STARTTLS. + +The [`submissions` service][service-submissions] (_typically port 465_) is an exception to this rule, where the +connection begins immediately secured with TLS (_similar to HTTPS_). When the configured [port for +SMTP][docs-config-smtp-port] is set to `465`, Authelia will initiate TLS connections without requiring STARTTLS +negotiation. + +When the `submissions` service port is available, it [should be preferred][port-465] over any STARTTLS port for +submitting mail. + +**NOTE:** Prior to 2018, port 465 was previously assigned for a similar purpose known as [`smtps`][port-465] (_A TLS +only equivalent of the `smtp` port 25_), which it had been deprecated for. Port 465 has since been re-assigned for only +supporting mail submission (_which unlike SMTP transfers via port 25, [requires authentication][smtp-auth]_), similar +to port 587 (_the `submission` port, a common alternative that uses STARTTLS instead_). + +[docs-config-smtp-port]: ../../configuration/notifications/smtp.md#port +[cleartext]: https://cwe.mitre.org/data/definitions/312.html +[service-submissions]: https://www.rfc-editor.org/rfc/rfc8314#section-7.3 +[port-465]: https://www.rfc-editor.org/rfc/rfc8314#section-3.3 +[smtp-auth]: https://www.rfc-editor.org/rfc/rfc6409#section-4.3 ## Protection against open redirects