Ferroma 中的 SMTP#

本文读者： 所有实现、测试或排查 ferroma-smtp 的人，以及任何想弄清远端服务器 为何拒收自己邮件的运维者。

本文覆盖 SMTP 的两个方向。收信侧既包括从其它 MTA 接收邮件的监听器，也包括从你自己 用户的邮件客户端接收邮件的 submission 监听器。发信侧是解析 MX 记录、把你用户的邮件 投递到远端主机的队列工作器。本文规定命令集、会话状态机、每一种失败对应的应答码、 各项限制以及每项限制在哪一层强制执行、Ferroma 前置的 Received: 头字段、重试计划、 4xx 与 5xx 的分类规则，以及退信生成。

状态： 设计规范。ferroma-smtp crate 是照着本文档实现的；标注 (计划中) 的 小节描述的是已经规定但尚未交付的行为。就目前而言，本文件的全部内容都是 _(计划中)_： crates/ferroma-smtp/src/lib.rs 只是一个骨架，声明了 server/client/MX/policy 的 模块边界。它提到的配置键、限制值和错误变体确实已经存在—— config/ferroma.toml 中的 [smtp] 与 [limits]、 crates/ferroma-core/src/limits.rs 中的 Limits、 crates/ferroma-core/src/error.rs 中的 FerromaError，以及 migrations/0001_initial.sql 中的 mail_queue / delivery_attempts 两张表。

1. 端口与监听器角色#

当 smtp.smtps_port != 0 而 tls.enabled = false 时，当两个启用的 SMTP 端口冲突时， 或者当 smtp.port 为 0 时，Config::validate() 会拒绝启动。见 crates/ferroma-core/src/config.rs。

连接到达的是哪个端口属于会话的一部分，而不是另一条代码路径：它选择的是*策略配置档* （认证是否强制，以及未认证的事务是否可以向非本地域投递）。

2. 命令集（§9）#

项目书 §9.1 把命令集拆成两个阶段。

实现额外接受的命令，以及定义它们的 RFC：

其它任何输入都得到 500 5.5.2 Command unrecognized。

命令行#

• 命令行上限：512 个八位组，含 CRLF（RFC 5321 §4.5.3.1.4）。更长
  ⇒ 500 5.5.2 Line too long。该限制在解析之前检查，因此攻击者无法让解析器分配内存。
• 命令不区分大小写（mail from: 合法）。
• MAIL FROM、RCPT TO 和 AUTH 可以携带 ESMTP 参数
  （SIZE=、BODY=8BITMIME、SMTPUTF8、AUTH=），以空格分隔。按照 RFC 5321
  §4.1.1.11，未知参数被忽略。
• 未知动词被拒绝，未知*参数*不会。这个不对称正是 RFC 要求的，也正是它让新客户端
  能继续对着旧服务器工作。

3. 状态机#

项目书 §9.2 给出该枚举；已交付的实现原样使用它，并补上 STARTTLS 需要的加密标志。

/// crates/ferroma-smtp/src/server/state.rs
pub enum SmtpState {
    Connected,      // 已发出问候语，尚未收到任何内容
    Greeted,        // EHLO/HELO 已被接受
    MailFrom,       // MAIL FROM 已被接受，尚无收件人
    RcptTo,         // 至少一个 RCPT TO 已被接受
    Data,           // 已发出 354，正在读取以点号终止的正文
    Authenticated,  // SASL 成功（与上面五个状态正交）
}

迁移：

                    ┌──────────────┐
   connect ────────►│  Connected   │ 220 <smtp.banner>
                    └──────┬───────┘
        EHLO/HELO ─────────┤          250-… / 250 SIZE n
                           ▼
                    ┌──────────────┐
                    │   Greeted    │◄──── RSET (from any state)
                    └──────┬───────┘
      MAIL FROM:<…> ───────┤          250 2.1.0
                           ▼
                    ┌──────────────┐
                    │   MailFrom   │
                    └──────┬───────┘
      RCPT TO:<…> ─────────┤          250 2.1.5  (repeatable)
                           ▼
                    ┌──────────────┐
                    │    RcptTo    │
                    └──────┬───────┘
         DATA ─────────────┤          354 End data with <CR><LF>.<CR><LF>
                           ▼
                    ┌──────────────┐
                    │     Data     │  (body with limits.data_timeout_secs)
                    └──────┬───────┘
        end-of-data ───────┴─────────► 250 2.0.0 Ok: queued as <id>  → Greeted
                                   └──► 4xx / 5xx                    → Greeted

Authenticated 不是该序列中的一个位置；它是一个标志，能跨 RSET 保留，并改变会话 被允许做什么。AUTH 在 Greeted 及之后的状态合法，在 Connected 中永远不合法 （503 5.5.1 Send HELO/EHLO first），在 Data 期间也永远不合法。

各项守卫，以及守卫触发时的应答：

4. 会话结构体#

项目书 §9.3：

/// crates/ferroma-smtp/src/server/session.rs
pub struct SmtpSession {
    /// Unique per accepted connection; also the `connection_id` log field.
    pub connection_id: Uuid,
    /// TCP peer address. Taken from `X-Forwarded-For` only when
    /// `api.trust_proxy_headers` is set and the peer is a trusted proxy.
    pub remote_addr: SocketAddr,
    /// The handler the connection is talking to.
    pub port: SmtpPort,          // Mx | Submission | Smtps
    pub state: SmtpState,
    /// The name the peer announced. Used in `Received:`, never trusted.
    pub helo: Option<String>,
    /// `true` once STARTTLS completed. Gates `require_tls_for_auth`.
    pub encrypted: bool,
    /// Set by a successful `AUTH`; the account whose quota and rate limits apply.
    pub authenticated_user: Option<UserId>,
    /// The session row created by `AuthService::open_session(SessionKind::Smtp)`.
    pub session_id: Option<SessionId>,
    /// `MAIL FROM` reverse-path, empty for a null sender (`<>`, a bounce).
    pub envelope_from: Option<String>,
    /// Accepted recipients, in order, after aliases and catch-all expansion.
    pub recipients: Vec<String>,
    /// `SIZE=` announced on `MAIL FROM`, when the client sent one.
    pub declared_size: Option<u64>,
    /// `BODY=` / `SMTPUTF8` parameters seen on `MAIL FROM`.
    pub body_8bit: bool,
    pub smtp_utf8: bool,
}

每个可以被记录的字段都出现在项目书 §40 列出的结构化字段中（connection_id、 remote_ip、helo、authenticated_user、sender、recipient、message_id、 result、duration）。ferroma-core 的 logging 模块安装携带这些字段的订阅者。

会话是每连接一份的，并且活在一个 Tokio 任务上。它没有任何共享成分，因此状态机无需 加锁；*确实*共享的计数器（连接总数、按 IP 的速率窗口）放在监听器里。

5. 宣告的 EHLO 扩展#

对 EHLO 的应答是每个能力一行，并且整组扩展只在 smtp.advertise_extensions = true 时才发送；当它为 false 时，会话以 250-<hostname> 加一个光秃秃的 250 OK 应答， 这正是那种会因扩展而噎住的远古客户端所需要的。

当 smtp.require_tls_for_auth = true 时，在未加密的连接上完全不给 AUTH。宣告一个 会话会拒绝的机制，比不宣告它更糟：那会让客户端在明文发出了它本不该发出的凭据之后 才失败。

6. 开放中继策略，以及它为何是默认值#

项目书 §9.4 与 §54：

recipient domain is a local domain   →  accept (subject to quota and limits)
recipient domain is anything else    →  require a successful AUTH first

具体到 RCPT TO 的处理中：

为什么默认值就是它。 开放中继不是一处配置上的不便；它是一台洗白垃圾邮件的机器， 几小时内就会被列入黑名单，并把运维者自己的正常邮件一起拖下水。每一位邮件管理员都 见过它发生，损害是以数月的投递率来计量的，而不是以分钟的停机。因此，让安全的行为 成为默认值、让不安全的行为因打错字而不可达，值得多花那一点点配置：没有任何 allow_relay = true 键可以被偶然找到并设置，而 [../AGENTS.md](../../AGENTS.md) §4.6 把这条规则列为不可协商。

由同一套推理得出的两个相邻策略决定：

• 本地投递不要求认证。 否则任何其它 MTA 都无法向你用户投递邮件，而运行一台 MX
  的全部意义正在于此。
• AUTH 不会让你对任意 MAIL FROM 变得可信。 已认证用户只能设置自己拥有的本地
  From 地址（mailboxes 表中 user_id 等于他的那些行）；在自己的提交中使用
  外来 From 会得到 550 5.7.1 Sender address rejected: not owned by user。

7. 各项限制及其强制执行位置#

每一项限制都在协议边缘强制执行，并且在邮件核心中复查，因此改用 API 而不是 SMTP 也无法绕过它。crates/ferroma-core/src/limits.rs 是唯一定义处； config/ferroma.toml 中的 [limits] 是唯一的取值来源。

当 max_connections_per_ip > max_connections 时，当 max_attachment_size > max_message_size 时，当 max_message_size 为 0 时，或者当 max_mime_depth 落在 1–100 之外时，Limits::validate() 会拒绝启动。因此 [limits] 里的一个错字会在启动时 让服务器停下，而不是悄悄禁用一项限制。

按账号的限制才是对滥用真正要紧的那些：否则一个被攻陷的已认证账号就能被当作垃圾邮件 加农炮，速率只受主机上行带宽制约。submission_rate_limit 和 daily_send_limit 在 接受时检查，并且每日计数取自 mail_queue 的行而不是内存计数器，因此重启不会把它 清零。

8. AUTH PLAIN 与 AUTH LOGIN#

项目书 §15 规定口令存储使用 Argon2id，SMTP 使用 AUTH PLAIN / AUTH LOGIN。

初始应答 =（RFC 4954 §4）表示「空」，对两种机制都是解析错误： 501 5.5.4 Invalid base64 data。

认证成功：

1. 会话解码凭据并调用
   AuthService::login(email, password, SessionKind::Smtp, ip, user_agent, None)。
2. AuthService 对着存储的 Argon2id PHC 字符串校验
   （PasswordHasher::verify），当 PasswordHasher::needs_rehash 判断存储参数已过期时
   透明地重新哈希，并通过 LoginAttemptsRepository 记录本次尝试。
3. 成功后会话获得 authenticated_user，以及来自 sessions 表、kind = 'smtp' 的
   一个 SessionId。
4. 应答为 235 2.7.0 Authentication successful。

失败应答——在「无此用户」与「口令错误」之间刻意不可区分，正如 AuthService::login 所做的那样：

require_tls_for_auth#

在 config/ferroma.toml 中默认为 false，这样一次裸 cargo run 无需证书即可工作。 docker-compose.prod.yml 设置 FERROMA__SMTP__REQUIRE_TLS_FOR_AUTH: 'true'，生产 MX 应当保持这一设置：AUTH PLAIN 与 AUTH LOGIN 都用 base64 发送口令，而那是编码， 不是加密。在明文 587 端口上，被动观察者能读到明文口令。开启该标志后，在 STARTTLS 完成之前，AUTH 既不被宣告也不被接受。

Config::allows_plaintext_auth() 的存在，是为了让调用方无需从 TLS 标志再推导一遍 就能问出这个问题。

9. STARTTLS、SMTPS 与 submission 角色#

那些容易弄错、因此被明确规定的细节：

• STARTTLS 之后状态被重置。 helo、envelope_from、recipients、
  declared_size 以及 AUTH 标志全部清空；只有 connection_id 和
  remote_addr 留存。在 STARTTLS 之前完成认证的客户端必须重新认证——否则攻击者
  可以向明文会话中注入命令，并让它们作用于加密会话。
• 任何命令都不得跨 STARTTLS 流水线化。 按照 RFC 3207 §6，一个 STARTTLS
  命令行之后在同一 TCP 报文段里还有任何内容都是错误。应答：`554 5.5.1 Pipelining
  violated`，随后关闭。
• tls.enabled = false 时的 STARTTLS 应答为
  502 5.5.1 Command not implemented，且它也不会被宣告。
• 已经加密时的 STARTTLS 是 503 5.5.1 TLS already active。
• TLS 握手失败会关闭连接，不给应答；没有明文回退，这正是阻止降级攻击的原因。
• 证书材料来自 tls.cert_path / tls.key_path（一个 PEM 包：叶证书后跟中间
  证书，以及一把 PKCS#8 或 PKCS#1 私钥）。tls.self_signed_fallback 在启动时用
  rcgen 生成证书，仅供开发使用——还要求 tls.allow_insecure_dev_mode 为真，
  并由 Config::validate() 强制这一配对。
• 最低协议版本是 tls.min_version，默认 "1.2"；"1.3" 也被接受。其它任何值
  都会拒绝启动。
• 只用 rustls。 不用 native-tls，不用 OpenSSL，不用 schannel——见
  architecture.md §8 与 ../AGENTS.md §1.1。

10. Received: 头字段#

当 smtp.add_received_header = true（默认值）时，收信邮件会被前置一个 Received: 头字段。它是前置而不是后置：Received: 头字段按最新在前的顺序累积，最上面的那条 是 Ferroma 知道的第一跳。

Received: from <helo> (<reverse-dns> [<remote-ip>])
        by <server.hostname> (Ferroma <version>)
        with ESMTPS id <connection_id>
        for <recipient>
        ; <date>

渲染示例（示意输出）：

Received: from mail.example.net (mail.example.net [203.0.113.25])
        by mail.example.com (Ferroma 0.1.0)
        with ESMTPS id 0f4c9a12-6b1e-4d3f-9a77-2c1f0e5b8d41
        for <[email protected]>
        ; Tue, 16 Sep 2026 09:12:31 +0000

逐字段规则：

该头字段绝不包含两样东西：对等端的 IP 取自套接字，而不是对等端发来的任何头字段； 并且对等端发来的任何头字段都绝不会被复制进生成的那一行。

当设置了 policy.add_auth_results 或 policy.add_auth_results 时， Authentication-Results 会被单独加入；见 security.md §8。

11. 发信投递#

项目书 §10 给出流水线；项目书 §11 给出队列状态与重试计划。

 SMTP submission / Webmail / Client API
                │
                ▼
            Mail Core                renders RFC 5322, signs DKIM,
                │                    writes the Sent copy
                ▼
            mail_queue                one row per recipient
                │
                ▼
        QueueRepository::claim_due()  status pending|retry → delivering
                │
                ▼
            DNS MX                    per recipient domain
                │
                ▼
       remote MX hosts, in preference order, :25
                │
                ▼
        SMTP client (EHLO → STARTTLS if offered → MAIL → RCPT → DATA)
                │
                ├── success  ──► delivered   + delivery_attempts row
                └── failure  ──► retry | failed, per §12

11.1 队列状态及承载它们的列#

mail_queue.status 带有一个 CHECK 约束，恰好列出这些取值： pending、delivering、delivered、retry、failed、cancelled。

  pending ──► delivering ──┬──► delivered
     ▲                     │
     │                     ├──► retry ──► delivering ──► …
     └─────────────────────┘
                           └──► failed   (attempts exhausted, or a 5xx)

每次尝试还会写入一行 delivery_attempts（queue_id、attempt、remote_mx、 status_code、status_text、error、duration_ms），Admin 的「Delivery Logs」 界面读的就是它。尝试是历史；队列行是状态。

11.2 MX 解析#

(计划中) ferroma-smtp::mx::MxResolver 使用 hickory-resolver（由 [dns] 配置）。

1. 查询收件域的 MX。
2. 按 preference 升序排序，相同 preference 内部用稳定的随机次序打破平局，这样重复
   尝试不会总是先打同一台主机——这也是 RFC 5321 §5.1 所推荐的，并且能防止一台死掉的
   MX 吸走所有重试。
3. 按顺序尝试主机。 连接失败、4xx 问候语或 TLS 失败都会在同一次尝试内转向下一
   台主机。只有当每一台主机都失败时，这次尝试才被记为失败。
4. Null MX。 单条 MX 0 . 表示该域不接受任何邮件。这是永久性失败（failed，
   并且退信）：在本地等价于 556 5.1.10，即 FerromaError::Invalid。
5. 没有 MX，但有 A/AAAA 记录。 按照 RFC 5321 §5.1 回退到地址本身。只有当
   回退也失败时，该域才不可投递。
6. 既没有 MX 也没有地址。 FerromaError::Dns——按 §12.5 分类，会被归为临时性：
   一个域可能正处于注册过程中。
7. CNAME 链由解析器跟进，受 dns.attempts 限制。
8. 超时取自 [dns]（timeout_secs、attempts、tcp_fallback）。

对单一主机的连接并发数由 queue.max_connections_per_host（4）封顶：用四百条并行连接 猛砸一台远端 MX，正是一台邮件服务器把自己搞进黑名单的方式。

11.3 重试计划（§11）#

queue.retry_schedule_secs = [60, 300, 900, 3600, 21600, 86400]——一分钟、五分钟、 十五分钟、一小时、六小时、二十四小时。最后一项会一直重复，直到 attempts 达到 queue.max_attempts（12）。

QueueConfig::backoff_for_attempt(attempt) 就是该规则的实现：它把索引钳制到计划末尾， 因此第 7、8、… 次尝试都等待 86 400 秒，并在计划为空时返回 60。

尝试四天半是 MTA 的常规姿态：长到远端服务器周末的一次故障不会退掉你用户的邮件， 又短到发件人最终会知道邮件没送到。queue.retention_days（30）管辖 delivered 行在 那之后保留多久；它与重试窗口无关。

调度器以 queue.poll_interval_secs（10）轮询，并发运行 queue.workers（4）条投递。

12. 4xx 与 5xx，以及 FerromaError::is_temporary()#

分类不是在 SMTP 层决定的。它就是 FerromaError::is_temporary()——crates/ferroma-core/src/error.rs 中的一个函数——它是 SMTP 应答类别与队列「重试还是失败」决定背后的唯一真相来源。

pub fn is_temporary(&self) -> bool {
    matches!(
        self,
        FerromaError::Io(_)
            | FerromaError::Network(_)
            | FerromaError::Dns(_)
            | FerromaError::RateLimited
            | FerromaError::Timeout(_)
            | FerromaError::Storage(_)
            | FerromaError::Internal(_)
    )
}

一句话规则：is_temporary() == true ⇒ 4xx 并重新入队； is_temporary() == false ⇒ 5xx 并失败。 一个协议层如果靠字符串匹配错误消息来 自行分类错误，那就是 bug；请新增变体或修正 is_temporary()。

12.1 收信：Ferroma 对某对等端应答什么#

对上文直觉的两处更正，都是刻意的：

• 超配额是 452，不是 550。 邮箱满了是*收件人*的临时状况，不是该地址的永久
  属性。550 会让发件人的 MTA 立即退信，用户就会丢掉那些在他超配额期间到达的邮件。
  RFC 3463 把 4.2.2 编码为「mailbox full」正是出于这个原因。因此存储层的
  StorageError::QuotaExceeded 只在 SMTP 应答中映射为临时类别——在队列层面它仍然是
  is_temporary() == false，因为在那一层过错确实属于邮件本身。
• 任何存储失败都用 451 4.3.0，包括数据库中断。收到 451 的远端服务器会重试
  好几天；而 550 会因为我们的磁盘满了十秒钟就永久退掉这封邮件。

12.2 发信：远端应答对队列意味着什么#

12.3 增强状态码#

宣告了 ENHANCEDSTATUSCODES（RFC 3463），因此每个应答在基本码之后都带一个 x.y.z 类别。Ferroma 发出的类别：

当 smtp.advertise_extensions = false 时，增强码被省略，应答是光秃秃的三位数字码 加上没有类别的文本。

12.4 DSN#

DSN（RFC 3461）会被宣告 _(计划中)_，并且 MAIL FROM 上的参数 （RET=FULL|HDRS、ENVID=）与 RCPT TO 上的参数（NOTIFY=、ORCPT=）会记录到 队列行上。对某个收件人设置 NOTIFY=NEVER 会抑制该收件人的退信。在它实现之前， DSN 不会被宣告，那些参数也会被忽略，这正是 RFC 5321 §4.1.1.11 对不支持它们的 服务器所要求的做法。

12.5 完整的收信应答表#

13. 退信生成#

当一次投递以 failed 结束且 queue.bounce_on_failure = true 时，Ferroma 会向信封 发件人回发一封投递状态通知。项目书 §11 没有写明格式，因此本节就是规范。

13.1 退给谁#

空发件人规则很要紧：RFC 5321 §6.1 与 RFC 3464 都要求通知的反向路径为空，而一台 会给退信再退信的服务器，会乐于在两台配置错误的 MTA 之间制造无限环路。

13.2 退信是一封 DSN#

multipart/report; report-type=delivery-status（RFC 3462/3464），包含：

用 ferroma_mail::MessageBuilder 构建；原始字节按 messages.storage_path 取自 Maildir。Status: 字段携带 §12.3 的*增强*码，这样发件人的客户端可以依据类别而不是 文字描述来行动。

13.3 何时生成退信#

退信在 In-Reply-To 与 References 中携带原 Message-ID，因此客户端可以把 「Undelivered Mail Returned to Sender」与用户实际发出的那封邮件串在一起。

14. 手工诊断 SMTP#

项目书 §44 列出了工具。以下全部都可对本地运行的服务器使用；25 端口是收信监听器， 587 是 submission 监听器。

# Greeting, capabilities and a full transaction, unencrypted.
swaks --server 127.0.0.1 --port 25 --from [email protected] --to [email protected] --body "test"

# The same, forcing STARTTLS.
swaks --server 127.0.0.1 --port 587 --tls --auth PLAIN --auth-user [email protected] --auth-password '…'

# By hand: type EHLO, MAIL FROM, RCPT TO, DATA.
nc 127.0.0.1 25

# Which capabilities does the submission port advertise, and does it offer STARTTLS?
openssl s_client -starttls smtp -connect 127.0.0.1:587 -crlf

# Implicit TLS on 465.
openssl s_client -connect 127.0.0.1:465

# Is the MX record the one Ferroma will use?
dig +short MX example.com

问候语与能力交换的示意输出：

220 mail.example.com Ferroma ESMTP ready
EHLO client.example.net
250-mail.example.com
250-PIPELINING
250-SIZE 26214400
250-8BITMIME
250-ENHANCEDSTATUSCODES
250-SMTPUTF8
250-STARTTLS
250-AUTH PLAIN LOGIN
250 HELP
MAIL FROM:<[email protected]>
250 2.1.0 Ok
RCPT TO:<[email protected]>
250 2.1.5 Ok
DATA
354 End data with <CR><LF>.<CR><LF>
Subject: test

hello
.
250 2.0.0 Ok: queued as 4821
QUIT
221 2.0.0 Bye

关于「邮件送不到」和「队列在不断增长」，见 deployment.md §11 中 按症状编排的命令清单。

15. 相关文档#