强制超级管理员配置安全验证并保护本机密码重置
Security Checks / security (push) Waiting to run

This commit is contained in:
xuans committed 2026-09-19 00:24:27 +08:00
1 parent de8c298bd5
commit 67931eab5d
38 files changed
+1128 -135

No files matched your search

@@ -22,7 +22,7 @@
### 1.2 当前安全结论
- 超级管理员自身的密码重置只有部署端本机 IPC 链路,HTTP 路由不提供该能力;`smail-admin` 不直接访问数据库。
- 超级管理员不能通过登录页恢复密码;本人安全中心保留已认证操作,部署端重置使用本机 IPC;`smail-admin` 不直接访问数据库。
- Linux 使用权限受限的 Unix Domain Socket 和对端 UID 校验;Windows 使用安全描述符限制的 Named Pipe,并校验客户端进程令牌是否为 SYSTEM 或提升后的管理员。
- IPC 使用一次性 nonce、有效期、单帧大小上限、协议版本和未知字段拒绝;nonce 在消费时原子删除,不能跨连接复用。
- 邮箱验证码只保存在签发认证进程内存,验证码只以 HMAC-SHA-256 校验值保存;进程重启后内存任务和临时密钥失效。
@@ -98,7 +98,7 @@ flowchart LR
| 外部安全邮箱 | 绑定/登录/恢复服务 | 解密后用于匹配、投递和脱敏返回 | AES-GCM 加密密文 + 独立 HMAC 指纹 | 未验证绑定失败回滚;停用后不可用于认证;解密明文只短暂存在 |
| WebAuthn 凭据 | 浏览器 ceremony | WebAuthn 请求和服务端验证 | 独立凭据密钥保护的序列化凭据 | ceremony 会话限时一次;凭据可撤销;恢复或重置按权限撤销 |
| 登录二次验证状态 | `loginVerificationState` 和验证码 Store | 登录密码成功后到验证码验证完成 | 仅内存 | 十分钟过期、成功消费、密码/会话版本变化时删除 |
| IPC nonce | `SessionGuard` | 管理进程和主服务之间一轮连接 | 仅内存 | 两分钟默认有效;消费、断开或过期删除 |
| IPC nonce | `SessionGuard` | 管理进程和主服务之间一轮连接 | 仅内存 | 生产重置连接五分钟有效;消费、断开或过期删除 |
| SMTP 认证密码 | 配置装载到 SMTP 投递 | SMTP 建连和认证 | 受配置 Secret 管理约束,不进入验证码事件 | 由配置 Secret 生命周期管理;不得进入邮件正文、日志或响应 |
| 临时进程密钥 | 验证码 Store、邮箱 Vault、审计指纹服务 | 进程内加密、HMAC 和校验 | 验证码临时密钥禁止持久化;外部邮箱和审计密钥按密钥管理策略保存 | 进程退出后验证码密钥失效;其他密钥不得通过诊断导出 |
@@ -106,14 +106,14 @@ flowchart LR
### 4.1 部署端超级管理员重置
1. 部署人员在受控主机上按正式部署命令启动 `smail-admin`,新密码从无回显安全交互读取,不通过命令行参数、环境变量、服务名或普通文件传递。
1. 部署人员在受控主机上按正式部署命令启动 `smail-admin`,安全凭据与新密码从无回显交互读取,不通过命令行参数、环境变量、服务名或普通文件传递。
2. `smail-admin` 连接固定本机 IPC 地址:Linux 为 Unix Domain Socket,Windows 为 Named Pipe。
3. 主服务先校验对端身份,再签发一次性 nonce;客户端只能在当前连接返回同一 nonce 和新密码。
3. 主服务先校验对端身份,再签发一次性 nonce 和可用安全方式;客户端依次选择方式、验证邮箱验证码或 TOTP 或安全码,最后才提交新密码。选择邮箱前不发送验证码。
4. 主服务校验协议版本、单帧大小、字段集合、密码长度、nonce 一致性和 nonce 未过期/未消费。
5. 主服务在同一数据库事务中定位唯一超级管理员、更新 Argon2id 密码哈希、递增 `session_version`、撤销其恢复凭据,然后提交事务。
5. 主服务在同一数据库事务中定位唯一超级管理员、复核账号及所选凭据版本、核销所选安全码、更新 Argon2id 密码哈希、递增会话和安全版本、撤销其恢复凭据,然后提交事务。
6. 提交成功后仅在内存中撤销该用户的会话、验证码、恢复票据和 WebAuthn 状态;客户端获得不含数据库细节的结果。
明确禁止:HTTP 路由、浏览器页面、远程 TCP、离线恢复码或外部邮箱验证码触发超级管理员自身重置。
明确禁止:登录页恢复超级管理员、通过 HTTP 或远程 TCP 暴露本机重置通道、未验证账号安全凭据就提交本机重置。邮箱、TOTP、安全码可用于受保护本机通道的身份验证。当前操作规则见《超级管理员安全验证与本机重置》。
### 4.2 外部安全邮箱绑定
@@ -199,7 +199,7 @@ flowchart LR
| T-13 | 未验证、已停用或他人外部邮箱被用于恢复/登录 | 查询只接受 verified 状态;资源 ID 和 UserID 双重绑定;停用时失效验证码、恢复票据和登录状态 | `externalemail.TestRepositoryBindsVerifiesAndScopesByUser`;`externalemail.TestRepositoryAbandonsOnlyOwnedPendingBinding`;`backend/controllers/security.go` 中 `DisableExternalEmail` 的状态失效代码审查 |
| T-14 | 数据库读取者通过运营数据还原账号、邮箱或 IP | 运营字段使用独立 HMAC 指纹;限流维度键哈希;不保存完整值;按期限清理 | `verification.TestEventStorePersistsOnlyOperationalFingerprintsAndCleansAfterRetention`;`verification.TestPersistentRateLimiterDoesNotPersistSensitiveValues` |
| T-15 | 主服务重启后旧验证码或恢复流程被恢复使用 | 验证码 Store 的临时密钥和任务只在内存;恢复票据、诱饵挑战和 WebAuthn ceremony 不从数据库恢复 | `verification.TestStoreRestartInvalidatesAllChallenges`;`recovery.TestRecoveryStoresOnlyTicketDigestAndLimitsCapacity`;`webauthn.TestCeremonySessionCapacityAndExpiredPruning` |
| T-16 | 超级管理员通过 Web、外部邮箱或恢复码重置自身密码 | 恢复用户加载明确拒绝 `super_admin`;部署端重置单独走 IPC;没有 Web 路由调用 `ResetSuperAdmin` | `recovery.TestRecoveryDeniesSuperAdministrator`;`controllers.TestRecoveryRejectsWhenDisabled`;路由审计:`backend/listen/http_server/http_server.go` 未注册网络超级管理员重置入口 |
| T-16 | 超级管理员通过登录页恢复或绕过本机身份验证 | 登录页恢复拒绝 `super_admin`;部署端单独走受保护 IPC 并强制验证账号安全凭据 | `recovery.TestRecoveryDeniesSuperAdministrator`;`controllers.TestRecoveryRejectsWhenDisabled`;`services/adminreset/verification_test.go`;本机用途不对 HTTP 验证接口开放 |
| T-17 | 恶意请求超过协议帧、JSON 或 SMTP 头字段限制 | IPC 最大帧 16 KiB、JSON unknown field 拒绝;邮箱和 SMTP Host/From 禁止换行和非法格式;HTTP JSON 单值解析 | `adminreset.TestProtocolRejectsOversizedFrame`;`controllers.TestDecodeJSONRequestRejectsUnsafeBodies`;`verification.TestSMTPHostValidation` |
| T-18 | 外部错误把数据库细节或秘密返回给调用方 | IPC 统一返回 `RESET_FAILED`;HTTP 使用稳定业务错误;日志只记录内部错误上下文,不拼接密码、验证码和完整邮箱 | `adminreset.TestWindowsNamedPipeReturnsSafeHandlerFailure`;`controllers.TestSecurityHandlersRejectUnauthenticatedRequests`;安全响应形状测试 |
@@ -0,0 +1,41 @@
# 超级管理员安全验证与本机重置
## 登录后的强制设置
超级管理员必须至少配置以下一种方式:
- 外部邮箱:完成绑定验证码验证,待验证邮箱不计入。
- 手机动态码:完成 TOTP 绑定并启用,已撤销或未确认绑定不计入。
- 安全码:生成并保存,至少保留一个未使用的有效安全码。
三种方式均未配置时,登录后只能进入安全设置或注销,不能跳过进入业务页面,后端业务接口也会拒绝请求。完成任意一种后解除限制;撤销最后一种时恢复限制。已有有效方式的账号无需重复设置。
管理员和普通用户仍按原规则提示设置安全码和邮箱,本次不强制要求所有账号启用 TOTP。
## 部署主机重置流程
在部署主机以 root 执行:
```sh
systemctl start smail-admin
```
1. 输入可用验证方式的序号。仅显示已配置且有效的方式。
2. 选择邮箱后才发送验证码;选择动态码或安全码不发邮件。
3. 输入邮箱验证码、手机验证器动态码或一个安全码。
4. 验证通过后,输入两次新密码。
5. 事务成功后旧会话失效,旧安全码和协议凭据撤销。已绑定邮箱和 TOTP 保留。
未绑定邮箱时可以使用 TOTP 或安全码。若唯一方式是安全码,重置后重新登录会要求再次配置安全方式。新安全码只展示一次,请妥善保存。
每轮连接最多五分钟,本机验证每十五分钟最多尝试五次,重新启动客户端不会刷新次数。失败后重新启动命令;不能跳过验证直接提交密码。若命令失败,可用 `journalctl -u smail-admin -n 20 --no-pager` 查看中文原因。
尚无任何安全凭据时,请先用现有密码登录安全中心配置。已经无法登录且没有任何有效凭据时,本通道不会免验证重置。
## 通道边界与升级
登录页继续禁止重置超级管理员。本人已登录的安全中心操作遵守现有认证要求;部署端重置只使用受保护的本机 IPC,不新增 HTTP 或 TCP 入口。
Linux 使用 Unix Domain Socket 及对端身份校验,Windows 使用受限 Named Pipe。邮箱验证码使用独立的本机重置用途,不能经公开验证码接口申请或验证。验证会绑定当前账号与凭据版本,更换或撤销所选凭据后不能继续重置。
本次协议升级到第二版,部署时必须同时替换主程序和 `smail-admin`,并同步更新 systemd 单元的超时时间。第一版客户端不能跳过新验证流程。