From 02a52d683b32e2670f746d898bd0041954390e7b Mon Sep 17 00:00:00 2001 From: zeripath Date: Sun, 24 May 2020 23:56:18 +0100 Subject: [PATCH] Add warning to mailer documentation about authentication (#11563) * Add warning to mailer documentation about authentication References #7966 Signed-off-by: Andrew Thornton * As per @guillep2k and @mrsdizzie * as per @mrsdizzie Signed-off-by: Andrew Thornton Co-authored-by: guillep2k <18600385+guillep2k@users.noreply.github.com> --- custom/conf/app.ini.sample | 7 +++++-- docs/content/doc/advanced/config-cheat-sheet.en-us.md | 6 +++++- docs/content/doc/usage/email-setup.en-us.md | 6 ++++++ 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/custom/conf/app.ini.sample b/custom/conf/app.ini.sample index c50dd68f1f5..5e150172d5b 100644 --- a/custom/conf/app.ini.sample +++ b/custom/conf/app.ini.sample @@ -627,7 +627,8 @@ SUBJECT_PREFIX = ; Mail server ; Gmail: smtp.gmail.com:587 ; QQ: smtp.qq.com:465 -; Note, if the port ends with "465", SMTPS will be used. Using STARTTLS on port 587 is recommended per RFC 6409. If the server supports STARTTLS it will always be used. +; Using STARTTLS on port 587 is recommended per RFC 6409. +; Note, if the port ends with "465", SMTPS will be used. HOST = ; Disable HELO operation when hostnames are different. DISABLE_HELO = @@ -639,11 +640,13 @@ SKIP_VERIFY = USE_CERTIFICATE = false CERT_FILE = custom/mailer/cert.pem KEY_FILE = custom/mailer/key.pem -; Should SMTP connection use TLS +; Should SMTP connect with TLS, (if port ends with 465 TLS will always be used.) +; If this is false but STARTTLS is supported the connection will be upgraded to TLS opportunistically. IS_TLS_ENABLED = false ; Mail from address, RFC 5322. This can be just an email address, or the `"Name" ` format FROM = ; Mailer user name and password +; Please Note: Authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via STARTTLS) or `HOST=localhost`. USER = ; Use PASSWD = `your password` for quoting if you use special characters in the password. PASSWD = 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 e3ff2deb37d..f0908c22a34 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`: **\**: Disable HELO operation. - `HELO_HOSTNAME`: **\**: Custom hostname for HELO operation. - `HOST`: **\**: 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`: **\**: Mail from address, RFC 5322. This can be just an email address, or the "Name" \ format. - `USER`: **\**: Username of mailing user (usually the sender's e-mail address). - `PASSWD`: **\**: 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`: **\**: Do not verify the self-signed certificates. - **Note:** Gitea only supports SMTP with STARTTLS. - `SUBJECT_PREFIX`: **\**: 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 68351d096d1..2f46b5d6c1e 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: