Make MAIL_ENCRYPTION variable less confusing

[b2ag]

Describe the feature you'd like

Hi,

when first looking at the variable MAIL_ENCRYPTION I thought "why do you have GPG for mails?" only to discover it's just refering to encrypting SMTP traffic. I wouldn't call that mail encryption (but who am I to judge).

Next I tried to figure why there is only "null", "tls" and "ssl" as options. And what authors think the difference between "tls" and "ssl" might be. I guess no one wants SSL anymore. So I highly doubt "ssl" means lower or equal to SSLv3 ciphers. Now I have this gut feeling "tls" means "STARTTLS" and not just "TLS" but couldn't prove it with source code. So I'm still just guessing.

The whole thing is quite confusing to me and I guess I have to try and error to configure this.

So can you please update those options to clarify what they actually do?

To clarify:

• TLS is the successor (or a continuation) of SSL
• no one wants to use SSL ciphers in 2023
• STARTTLS is a method of upgrading an insecure socket to use encryption
• STARTTLS works with TLS and SSL ciphers

BR

Describe the benefits this would bring to existing BookStack users

I guess there is no benefit for existing users if they are not trying to configure encrypted outgoing SMTP traffic.

Can the goal of this request already be achieved via other means?

Better documentation could work around using better names for those options.

Have you searched for an existing open/closed issue?

• I have searched for existing issues and none cover my fundemental request

How long have you been using BookStack?

Not using yet, just scoping

Additional context

No response

[b2ag]

MAIL_VERIFY_SSL could also be called MAIL_VERIFY_TLS but isn't that confusing because it reduces to something like "mail verify certificates".

[ssddanbrown]

Thanks for raising @b2ag. I agree the current state of things is quite confusing, I've just spent a couple of hours trying to fully understand exactly what's going on, and the changes made over time in terms of mail encryption at the framework and library level.

Current State

Overall, it looks like MAIL_ENCRYPTION was not actually doing anything in the latest releases.
SSL encryption is no longer used (and supported in the framework libraries), since we updated the framework earlier this year.
The framework would force TLS usage when MAIL_ENCRYPTION=tls and MAIL_PORT=465, but this would occur with any MAIL_ENCRYPTION value anyway since the underlying mailer library would force TLS over port 465.
In non-465-port cases, STARTTLS is attempted.

Functionality Changes

I've just applied dbb6c87 to force-enable TLS usage when MAIL_ENCRYPTION=tls or MAIL_ENCRYPTION=ssl, the latter of which for some level of secure-minded backwards compatibility since, although SSL is no longer specifically supported, we can infer it to mean the user wants encrypted mail communication. This technically could cause a breaking change, so will be something I'd need to add in update notes, but I think the best approach.
Again, STARTTLS will remain to be active where where no MAIL_ENCRYPTION is set, unless port 465 is used in which case TLS will be required.

These changes will be part of the next feature release.

Documentation Changes

On the documentation side of things I've made a set of changes to the docs site and default env files.
Our web documentation now has a fair bit more info on exactly how these settings are used, and the env files within BookStack now refer to our web docs for easier discovery where needed.
I've removed 'ssl' from the displayed MAIL_ENCRYPTION options, since it's now really redundant, doing the same as tls.

I've also tweaked the cert verification docs to refer to the connection and mention TLS/SSL so it doesn't seem so SSL specific. I still mention SSL since it's a still a common term for general encryption, and is still common used within the underlying PHP code.

On a related note, I appreciate the options themselves are named badly or awkwardly, but they are based upon, or reflect, underling framework code and I'd prefer to keep them named the same for backwards compat/consistency, but hopefully the other changes (specifically the improved guidance) makes these names a non-issue.

---

I'll therefore close this off since changes have been applied, but feel free to comment if anything is unclear or if I've made some mistakes somewhere.

---

Release Docs Todo

• Revert this commit
• Note (low) potential for mail to be affected (Primarily for instance that had MAIL_ENCRYPTION=ssl).

[ssddanbrown]

Just to follow this up with post-release findings, I made some incorrect assumptions in my thoughts and changes I made above.

I had assumed that services would support TLS and STARTTLS equally at specific SMTP endpoints, but it turns out that is not the case, and there can be SMTP endpoints that expect STARTTLS but won't accept up-front TLS.
Opened as separate issue in #4358.