Add warning to mailer documentation about authentication (#11563)

* Add warning to mailer documentation about authentication

References #7966

Signed-off-by: Andrew Thornton <art27@cantab.net>

* As per @guillep2k and @mrsdizzie

* as per @mrsdizzie

Signed-off-by: Andrew Thornton <art27@cantab.net>

Co-authored-by: guillep2k <18600385+guillep2k@users.noreply.github.com>

2 files changed, 11 insertions, 1 deletions

diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md
index e3ff2deb37..f0908c22a3 100644
--- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md
+++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md
@@ -397,10 +397,15 @@ set name for unique queues. Individual queues will default to
 - `DISABLE_HELO`: **\<empty\>**: Disable HELO operation.
 - `HELO_HOSTNAME`: **\<empty\>**: Custom hostname for HELO operation.
 - `HOST`: **\<empty\>**: SMTP mail host address and port (example: smtp.gitea.io:587).
+  - Using opportunistic TLS via STARTTLS on port 587 is recommended per RFC 6409.
+- `IS_TLS_ENABLED` :  **false** : Forcibly use TLS to connect even if not on a default SMTPS port. 
+  - Note, if the port ends with `465` SMTPS/SMTP over TLS will be used despite this setting.
+  - Otherwise if `IS_TLS_ENABLED=false` and the server supports `STARTTLS` this will be used. Thus if `STARTTLS` is preferred you should set `IS_TLS_ENABLED=false`.
 - `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or
    the "Name" \<email@example.com\> format.
 - `USER`: **\<empty\>**: Username of mailing user (usually the sender's e-mail address).
 - `PASSWD`: **\<empty\>**: Password of mailing user.  Use \`your password\` for quoting if you use special characters in the password.
+   - Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or `HOST=localhost`. See [Email Setup]({{< relref "doc/usage/email-setup.en-us.md" >}}) for more information.
 - `SKIP_VERIFY`: **\<empty\>**: Do not verify the self-signed certificates.
    - **Note:** Gitea only supports SMTP with STARTTLS.
 - `SUBJECT_PREFIX`: **\<empty\>**: Prefix to be placed before e-mail subject lines.
@@ -415,7 +420,6 @@ set name for unique queues. Individual queues will default to
 - `SENDMAIL_PATH`: **sendmail**: The location of sendmail on the operating system (can be
    command or full path).
 - `SENDMAIL_TIMEOUT`: **5m**: default timeout for sending email through sendmail
-- ``IS_TLS_ENABLED`` :  **false** : Decide if SMTP connections should use TLS.
 
 ## Cache (`cache`)
 
diff --git a/docs/content/doc/usage/email-setup.en-us.md b/docs/content/doc/usage/email-setup.en-us.md
index 68351d096d..2f46b5d6c1 100644
--- a/docs/content/doc/usage/email-setup.en-us.md
+++ b/docs/content/doc/usage/email-setup.en-us.md
@@ -46,6 +46,12 @@ PASSWD         = `password`
 
 For the full list of options check the [Config Cheat Sheet]({{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}})
 
+- Please note: authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
+  - Via the server supporting TLS through STARTTLS - usually provided on port 587. (Also known as Opportunistic TLS.)
+  - SMTPS connection (SMTP over transport layer security) via the default port 465. 
+  - Forced SMTPS connection with `IS_TLS_ENABLED=true`. (These are both known as Implicit TLS.)
+- This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
+
 ### Gmail
 
 The following configuration should work with GMail's SMTP server: