Skip to content

[feature] add SSL certificate verification toggle for email server - #4327

Open
orangeCatDeveloper wants to merge 1 commit into
apache:masterfrom
orangeCatDeveloper:feat/4323-mail-ssl-cert-verify
Open

[feature] add SSL certificate verification toggle for email server#4327
orangeCatDeveloper wants to merge 1 commit into
apache:masterfrom
orangeCatDeveloper:feat/4323-mail-ssl-cert-verify

Conversation

@orangeCatDeveloper

@orangeCatDeveloper orangeCatDeveloper commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Fixes #4323

Companies often run their own mail server on an internal network — reached by IP, with a self-signed certificate. Pointing HertzBeat's email notification at such a server simply fails: the TLS handshake is rejected, and there is no setting to get past it.

Why it fails: before trusting a TLS connection, Java checks the server's certificate twice — check 1: was it issued by a well-known CA? (a self-signed cert wasn't) — check 2: does the name on the cert match the address you dialed? (a cert without your IP in it doesn't). Failing either check kills the connection, and internal mail servers usually fail both. The error quoted in the issue (No subject alternative names matching IP address ... found) is check 2 speaking.

The fix: a new "Verify SSL Certificate" switch in the email server settings.

  • Default on → behavior identical to today; existing setups unaffected.
  • Switched off → both checks are skipped (mail.smtp.ssl.trust=* for check 1, mail.smtp.ssl.checkserveridentity=false for check 2) and the mail goes through.

One subtlety: the mail sender object is shared, so flipping the switch back on must also remove those two properties — otherwise "skip" would stick forever. EmailAlertNotifyHandlerImplTest covers both directions.

Boundary: the yml fallback path (no config saved in UI) always verifies. Anyone who previously worked around this by hand-writing mail.smtp.ssl.trust in application.yml should use the new switch instead.

Before / after — real JavaMail handshake against a local self-signed SMTPS server; the "before" error matches the issue word for word:

before (verify on, the default):
[Email Notify Error] Mail server connection failed. Failed messages: jakarta.mail.MessagingException:
Could not connect to SMTP host: 127.0.0.1, port: 62415; nested exception is:
javax.net.ssl.SSLHandshakeException: (certificate_unknown) No subject alternative names matching IP address 127.0.0.1 found

after (verify off):
[AFTER] verify-off sent mail successfully through self-signed TLS

UI — the switch appears only when SSL or STARTTLS is enabled:
pr4323-ui-verify-toggle

@orangeCatDeveloper
orangeCatDeveloper force-pushed the feat/4323-mail-ssl-cert-verify branch 3 times, most recently from f33bb63 to 4b0727f Compare August 17, 2026 11:42

@Aias00 Aias00 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

评审结论:APPROVE

实用的邮件 TLS 校验开关,默认安全、双向状态清理正确。

修复点确认:

  • MailServerConfig 与前端 EmailNoticeSender.ts 均新增 emailSslCertVerify默认 true,存量配置不受影响(安全默认)。
  • applySslCertVerify(props, verify) 逻辑正确:
    • 开启校验时 移除 mail.smtp.ssl.trustmail.smtp.ssl.checkserveridentity——这点很关键,因为 JavaMailSender 是单例,不显式 remove 会导致"跳过校验"状态永久残留;
    • 关闭校验时设置 mail.smtp.ssl.trust=* + mail.smtp.ssl.checkserveridentity=false
  • yml 回退路径硬编码 true(始终校验),符合"未在 UI 保存配置时按最严格处理"的预期。
  • i18n 六个语言文件(en/ja/ko/pt/zh-CN/zh-TW)均补了 ssl-cert-verify 文案,UI 开关仅在 SSL 或 STARTTLS 开启时显示。

测试: EmailAlertNotifyHandlerImplTest 覆盖双向——关闭时两属性设为跳过值、开启时从已污染的 props 中正确清除。

安全备注(非阻塞): 开启 verify-off 后 mail.smtp.ssl.trust=* 会信任任意主机、并关闭服务器身份校验。这是管理员显式 opt-in 行为,面向内网自签名证书场景,属预期功能而非漏洞。

无阻塞问题,批准。

Self-hosted mail servers reached by IP or with self-signed certs fail
the TLS handshake with no way to opt out. Adds a verify toggle
(default on) that sets mail.smtp.ssl.trust=* and disables the server
identity check when off.
@orangeCatDeveloper
orangeCatDeveloper force-pushed the feat/4323-mail-ssl-cert-verify branch from 4b0727f to e3f92c2 Compare August 18, 2026 06:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] 希望邮件增加是否验证证书功能

2 participants