From af767cdbf19f086f361d158fac39b61e8e4b954c Mon Sep 17 00:00:00 2001
From: Ihor Rusyn <0kaba0@gmail.com>
Date: Thu, 5 Nov 2026 12:30:27 +0100
Subject: [PATCH] docs(services): ssl_mode required, and ManageSieve on the
 general PROXY keys

Follows yarilomail/yarilo#2524.
---
 data/settings.yaml     | 28 ++++++++++++++++++++++++----
 docs/reference/rfcs.md |  4 ++--
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/data/settings.yaml b/data/settings.yaml
index 74938d17..fd962899 100644
--- a/data/settings.yaml
+++ b/data/settings.yaml
@@ -2847,10 +2847,27 @@ services.*.port:
 services.*.ssl_mode:
   type: string
   default: ""
-  values: [ssl, starttls, "no"]
+  values: [ssl, starttls, required, "no"]
   description: |
     TLS mode: `ssl` is implicit TLS; `starttls` is plain with a STARTTLS
-    upgrade; `no` is plain only.
+    upgrade; `required` is `starttls` with no authentication before TLS;
+    `no` is plain only. `required` applies to `imap_login`, `pop3_login`,
+    `submission_login` and `managesieve_login`, needs a certificate and
+    `auth_allow_cleartext: false`; the server refuses to start otherwise.
+    Under `required` a connection is secured by TLS, a local peer, or a PROXY
+    header whose `PP2_TYPE_SSL` TLV carries `PP2_CLIENT_SSL`; a peer in
+    `general.xclient.trusted_nets` and a plain PROXY header are not. Before
+    that no mechanism is offered, SCRAM included: IMAP advertises
+    `LOGINDISABLED` and no `AUTH=`, POP3 neither `USER` nor `SASL`,
+    ManageSieve no `SASL`, EHLO no `AUTH`. `AUTHENTICATE`/`AUTH` get
+    "Authentication disallowed on non-secure (SSL/TLS) connections." (IMAP
+    `NO [PRIVACYREQUIRED]`, POP3 `-ERR [AUTH]`, ManageSieve
+    `NO (ENCRYPT-NEEDED)`), logged as `Login failed: SSL required for
+    authentication`; `LOGIN` and `USER`/`PASS` get the
+    `auth_allow_cleartext` refusal. Submission answers every command but
+    EHLO, STARTTLS, NOOP and QUIT with `530 5.7.0 TLS required.` In the
+    chart: `components.<login>.listeners.<listener>.ssl_mode`, `starttls` by
+    default.
 
 services.*.haproxy_protocol:
   type: boolean
@@ -2859,6 +2876,10 @@ services.*.haproxy_protocol:
   description: |
     Extract the real client IP from the HAProxy PROXY header. Uses
     `general.haproxy` for the timeout and trusted nets.
+    yarilo-managesieve-login reads it and the general trusted networks like
+    the other login proxies; its pre-2.4.7 `managesieve_login_service.haproxy_protocol`
+    and `managesieve_login_service.haproxy_trusted_nets` are still accepted
+    with a warning, and when both nets keys are set the general one is used.
 
 services.*.xclient_protocol:
   type: boolean
@@ -2880,8 +2901,7 @@ services.*.auth_allow_cleartext:
     secured by TLS (implicit or after STARTTLS/STLS), by a local peer (same
     IP on both ends of the socket), by a peer in
     `general.xclient.trusted_nets`, or by a PROXY header accepted from
-    `general.haproxy.haproxy_trusted_networks` (ManageSieve:
-    `managesieve_login_service.haproxy_trusted_nets`). While refused, IMAP
+    `general.haproxy.haproxy_trusted_networks`. While refused, IMAP
     advertises `LOGINDISABLED` instead of `AUTH=PLAIN AUTH=LOGIN`, sends
     `* BAD [ALERT]` when the password was already sent, and answers
     `LOGIN`/`AUTHENTICATE` with `NO [PRIVACYREQUIRED]`; POP3 drops `USER` and
diff --git a/docs/reference/rfcs.md b/docs/reference/rfcs.md
index bd57d3b4..07be23be 100644
--- a/docs/reference/rfcs.md
+++ b/docs/reference/rfcs.md
@@ -20,7 +20,7 @@ Served by `yarilo-imap`, through `yarilo-imap-login`. Extensions marked *after l
 
 | RFC | Title | State | Notes |
 |:---|:---|:---|:---|
-| [9051](https://www.rfc-editor.org/rfc/rfc9051) | IMAP4rev2 | yes | after `ENABLE IMAP4rev2`, no `RECENT` response and no `\Recent` flag; see [Recent messages](/protocols/imap#recent-messages). `LOGINDISABLED` before STARTTLS while [`auth_allow_cleartext`](/architecture/services) refuses cleartext |
+| [9051](https://www.rfc-editor.org/rfc/rfc9051) | IMAP4rev2 | yes | after `ENABLE IMAP4rev2`, no `RECENT` response and no `\Recent` flag; see [Recent messages](/protocols/imap#recent-messages). `LOGINDISABLED` before STARTTLS while [`auth_allow_cleartext`](/architecture/services) refuses cleartext, and always under `ssl_mode: required` |
 | [3501](https://www.rfc-editor.org/rfc/rfc3501) | IMAP4rev1 | yes | `\Recent` held by the first session that selects the folder; see [Recent messages](/protocols/imap#recent-messages) |
 | [2180](https://www.rfc-editor.org/rfc/rfc2180) | IMAP4 multi-accessed mailbox practice | partial | a `COPY` that meets a message another session expunged copies nothing and answers `NO [EXPUNGEISSUED]` (§4.4.1) |
 | [2177](https://www.rfc-editor.org/rfc/rfc2177) | IDLE | yes | |
@@ -88,7 +88,7 @@ Served by `yarilo-submission`, through `yarilo-submission-login`, which answers
 |:---|:---|:---|:---|
 | [5321](https://www.rfc-editor.org/rfc/rfc5321) | SMTP | yes | |
 | [6409](https://www.rfc-editor.org/rfc/rfc6409) | Message submission | yes | relayed to an external MTA |
-| [3207](https://www.rfc-editor.org/rfc/rfc3207) | STARTTLS | yes | port 587 |
+| [3207](https://www.rfc-editor.org/rfc/rfc3207) | STARTTLS | yes | port 587; with [`ssl_mode: required`](/architecture/services), `530 5.7.0` to every command but EHLO, STARTTLS, NOOP and QUIT before TLS (§4) |
 | [8314](https://www.rfc-editor.org/rfc/rfc8314) | Implicit TLS | yes | port 465 |
 | [4954](https://www.rfc-editor.org/rfc/rfc4954) | AUTH | yes | |
 | [6152](https://www.rfc-editor.org/rfc/rfc6152) | 8BITMIME | yes | |