Add warning to mailer documentation about authentication

[zeripath]

References #7966

Signed-off-by: Andrew Thornton [email protected]

[mrsdizzie]

Hmm weird, I use SMTP fine with user/password without setting IS_TLS_ENABLED=true or localhost set.

Looking at the way Gitea works is that if you set IS_TLS_ENABLED=true or have port 465 then it tries to starts a TLS connection directly:

gitea/services/mailer/mailer.go

Lines 160 to 164 in 5789e60

	isSecureConn := opts.IsTLSEnabled || (strings.HasSuffix(port, "465"))
	// Start TLS directly if the port ends with 465 (SMTPS protocol)
	if isSecureConn {
	conn = tls.Client(conn, tlsconfig)
	}

but if not it still tries StartTLS if supported:

gitea/services/mailer/mailer.go

Lines 185 to 191 in 5789e60

	// If not using SMTPS, always use STARTTLS if available
	hasStartTLS, _ := client.Extension("STARTTLS")
	if !isSecureConn && hasStartTLS {
	if err = client.StartTLS(tlsconfig); err != nil {
	return fmt.Errorf("StartTLS: %v", err)
	}
	}

Which will upgrade the connection to a TLS connection in most cases. So IS_TLS_ENABLED=true is somewhat confusing as you will often end up with a TLS connection anyway since StartTLS will work in many cases -- and since it just works you'll never think to change the default IS_TLS_ENABLED setting because you won't have a TLS problem. In the case of the linked issue it doesn't work because that server happens to not support TLS at all.

So I think it should say you can only use username/password if the SMTP server supports TLS.

[zeripath]

@mrsdizzie - I forgot about that little feature - hopefully I've improved @guillep2k's suggestion.

@guillep2k presumably nota bene has died out in the Americas, I thought it was well-known e.g. i.e. etc.

[silverwind]

Can you also add this to app.ini.sample?

[mrsdizzie]

@zeripath looks good. Maybe while in here we can update the comment forIS_TLS_ENABLED=true that it actually means to just try Implicit TLS first. I can't make a code suggestion since it isn't part of the diff but maybe:

Try an Implicit TLS connection first. WIll fall back to STARTTLS if not supported. Implicit TLS is also implied when using port 465 in the `HOST` value.

Since the name is confusing and the current comment isn't really descriptive of what it does (most people read it as required for any TLS and it is probably wrongly suggested for servers or ports that don't support Implicit TLS).

[zeripath]

@mrsdizzie do you mean explicit rather than implicit here? My understanding is that STARTTLS is opportunistic TLS or implicit - in that the server and the client will upgrade to TLS implicitly without us explicitly telling them to, similarly connecting to a TLS port and detecting it was a TLS connection would be implicit, but saying connect with TLS is being explicit.

[zeripath]

Oh this is a weirdness of the RFC - the implicit here means that at the protocol layer the TLS is implicit. (even though the user has made it very explicit that they want TLS.)

[mrsdizzie]

@zeripath yes agree its all very confusing : (

Most simply, STARTTLS is considered the explicit one because the connection is explicitly upgraded if not secure. Other option is implicit because its implied the connection is already secure.

[zeripath]

OK I've tried to make that a bit clearer.

Fundamentally IS_TLS_ENABLED needs to be changed - it's confusing and should be FORCE_SMTPS_CONNECTION.

[mrsdizzie]

lgtm -- hopefully this will be just as helpful to us in the future as a reminder of how it works : )