RPJosh
/
authelia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: fix reference info to smtps (#3950) 

This PR aligns some information missed in a previous update.
pull/3969/head
Brennan Kinney 2022-09-06 14:01:46 +12:00 committed by GitHub
parent 9a71501b03
commit 97faa0beea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 48 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/content/en/configuration/notifications/smtp.md
View File

@ -56,9 +56,14 @@ host: "[fd00:1111:2222:3333::1]"
{{< confkey type="integer" required="yes" >}} {{< 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 The port the SMTP service is listening on.
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. 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 ### timeout

52
docs/content/en/overview/security/measures.md
View File

@ -152,8 +152,8 @@ values.
As such all SMTP connections require the following: As such all SMTP connections require the following:
1. TLS Connection (STARTTLS or SMTPS) has been negotiated before authentication or sending emails (unauthenticated 1. A TLS Connection (STARTTLS or implicit) has been negotiated before authentication or sending emails (_unauthenticated
connections require it as well) connections require it as well_)
2. Valid X509 Certificate presented to the client during the TLS handshake 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__. There is an option to disable both of these security measures however they are __not recommended__.
@ -163,14 +163,16 @@ preferable:
### Configuration Option: certificates_directory ### 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 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 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 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 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. 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 ### 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 ### Configuration Option: disable_require_tls
Authelia by default ensures that the SMTP server connection is secured via STARTTLS or SMTPS prior to sending sensitive Authelia by default ensures that the SMTP server connection is secured via TLS prior to sending sensitive information.
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 The [disable_require_tls](../../configuration/notifications/smtp.md#disable_require_tls) option disables this
of SMTP certificates and removes the encryption offered by the STARTTLS/SMTPS connection all together. 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.
This means not only can the vulnerabilities of the [skip_verify](#configuration-option-tlsskip_verify) option be 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 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 exploit the cleartext nature of the connection to manipulate the email in transit.
password) and as such is only an option for SMTP servers that allow unauthenticated relay (bad practice).
### SMTPS vs STARTTLS 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).
All connections start as plain text and are upgraded via STARTTLS. SMTPS is an exception to this rule where the ### SMTP Ports
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 All SMTP connections begin as [cleartext], and then negotiate to upgrade to a secure TLS connection via STARTTLS.
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. 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 ## Protection against open redirects