Make MAIL_ENCRYPTION variable less confusing #3883

New Issue

OVERLORD · 2026-02-05T07:45:56+03:00

OVERLORD commented

2026-02-05 07:45:56 +03:00

Originally created by @b2ag on GitHub (Jun 24, 2023).

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

Originally created by @b2ag on GitHub (Jun 24, 2023). ### 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? - [X] 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_

OVERLORD added the 🔨 Feature Request 📖 Docs Update labels 2026-02-05 07:45:56 +03:00

OVERLORD closed this issue

2026-02-05 07:45:59 +03:00

OVERLORD commented

2026-02-05 07:46:02 +03:00

@b2ag commented on GitHub (Jun 24, 2023):

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

@b2ag commented on GitHub (Jun 24, 2023): `MAIL_VERIFY_SSL` could also be called `MAIL_VERIFY_TLS` but isn't that confusing because it reduces to something like "mail verify certificates".

OVERLORD commented

2026-02-05 07:46:10 +03:00

@ssddanbrown commented on GitHub (Jun 24, 2023):

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 dbb6c87580 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 commented on GitHub (Jun 24, 2023): 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 dbb6c87580fba98686076d4351b17987bd2710bf 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](https://github.com/BookStackApp/website/commit/5e6e6d8bf4c9fa0075df6d5eb230f9ebdb93c60d) and [default env files](https://github.com/BookStackApp/BookStack/commit/dbb6c87580fba98686076d4351b17987bd2710bf). 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 - [x] [Revert this commit](https://github.com/BookStackApp/website/commit/bb27f3a3fa9201ece21b5b7f72cefc24393dd87e) - [x] Note (low) potential for mail to be affected (Primarily for instance that had `MAIL_ENCRYPTION=ssl`).

OVERLORD commented

2026-02-05 07:46:11 +03:00

@ssddanbrown commented on GitHub (Jul 3, 2023):

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.

@ssddanbrown commented on GitHub (Jul 3, 2023): 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.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#3883