mailcow-dockerized 中的 TOTP 二次验证RobThree TwoFactorAuth 库快速上手指南【免费下载链接】mailcow-dockerizedmailcow: dockerized - 项目地址: https://gitcode.com/GitHub_Trending/ma/mailcow-dockerized导读本文以 mailcow-dockerized 仓库内置的第三方依赖 RobThree TwoFactorAuth 官方文档getting-started.md为主体系统讲解在 PHP 项目中接入基于 TOTP基于时间的一次性密码的双因素认证2FA的完整流程从 Composer 安装、创建TwoFactorAuth实例到生成共享密钥、展示给用户、以及安全地验证动态验证码。同时结合 mailcow 自身的实际接入代码管理后台 TOTP 注册与登录校验帮助你理解这一经典库在真实邮件网关项目中的落地方式。读完本文你将能独立在自己的 PHP 项目中复刻扫码绑定 动态码登录的完整 2FA 闭环。1. 安装通过 Composer 引入依赖该库的官方推荐安装方式是通过 Composer。在当前 mailcow-dockerized 仓库中它正是作为 Composer 依赖被引入的你可以通过 composer.json 与 composer.lock 确认其锁定版本。如果你在本地项目中使用本地下载的 Composer 可执行文件php composer.phar require robthree/twofactorauth如果 Composer 已全局安装composer require robthree/twofactorauth安装完成后库的代码会出现在vendor/robthree/twofactorauth目录下与本仓库中的 data/web/inc/lib/vendor/robthree/twofactorauth 目录结构一致。注意如果你的项目没有使用任何基于 Composer 的框架需要自行引入 Composer 自动加载器vendor/autoload.php否则无法使用该库。在 mailcow 中这一步骤由 prerequisites.inc.php 中的require_once $_SERVER[DOCUMENT_ROOT] . /inc/lib/vendor/autoload.php;完成之后便可以在全局使用RobThree\Auth\TwoFactorAuth类。2. 创建实例new TwoFactorAuth()引入自动加载后即可创建用于后续所有操作的实例use RobThree\Auth\TwoFactorAuth; $tfa new TwoFactorAuth();这是最简形式所有参数都使用默认值。从源码 lib/TwoFactorAuth.php 可以看到构造函数签名如下public function __construct( $issuer null, // 签发方名称扫码时展示在用户 App 中 $digits 6, // 验证码位数默认 6 位 $period 30, // 每个验证码的有效秒数默认 30 秒 $algorithm sha1, // 哈希算法sha1 / sha256 / sha512 / md5 IQRCodeProvider $qrcodeprovider null, // QR 码生成器 IRNGProvider $rngprovider null, // 随机数生成器 ITimeProvider $timeprovider null // 时间源 )构造函数会对参数做严格校验$digits与$period必须是正整数$algorithm必须在受支持的算法列表[sha1, sha256, sha512, md5]内否则抛出TwoFactorAuthException。这一点在 tests/TwoFactorAuthTest.php 中有对应的异常测试覆盖。mailcow 的实际实例化方式见 prerequisites.inc.php$qrprovider new RobThree\Auth\Providers\Qr\BaconQrCodeProvider(); $tfa new RobThree\Auth\TwoFactorAuth($OTP_LABEL, 6, 30, sha1, $qrprovider);其中$OTP_LABEL在 vars.inc.php 中定义为mailcow UI即用户扫码后在其认证器 App 中看到的账户标签6 位数字、30 秒周期、sha1 算法这三项默认值保证了与 Google Authenticator 等主流 App 的最大兼容性。同时 mailcow 显式注入了BaconQrCodeProvider作为离线 QR 码生成器原因见第 5 节。3. 共享密钥Shared Secrets创建与展示当用户在你的项目中开启双因素或多因素认证时第一步是为该用户创建一个专属密钥$secret $tfa-createSecret();3.1 密钥生成的底层原理从源码 createSecret 实现 可以看到createSecret($bits 80, $requirecryptosecure true)的工作过程是根据$bits默认 80 位计算需要的字节数ceil($bits / 5)——因为 Base32 字母表有 32 个字符每个字符恰好编码 5 位调用 RNG 提供器生成对应长度的随机字节若$requirecryptosecure为true默认且当前 RNG 提供器不是加密安全级别会直接抛出TwoFactorAuthException对每个字节执行ord($rnd[$i]) 31掩码取低 5 位映射到 Base32 字母表ABCDEFGHIJKLMNOPQRSTUVWXYZ234567最终得到一个大小写统一、无歧义字符的密钥字符串。默认 80 位对应 16 个 Base32 字符。若需要更高安全性可传createSecret(160)或更高推荐 160 及以上且应为 8 的倍数参考 RFC 4226 的算法要求测试 IRNGProviderTest.php 展示了不同$bits下密钥长度的对应关系。3.2 将密钥告知用户拿到密钥后可以用任何你希望的方式展示给用户例如直接以文本形式让用户手动输入到认证器 Appp请在您的应用中输入以下代码: ?php echo $secret; ?/p更常见的做法是生成二维码供用户扫码详见第 5 节避免手动输入出错。安全要点官方文档明确强调在确认用户能正确使用该密钥之前应当把密钥保存在当前会话Session中而不是立刻写入用户记录。mailcow 正是这样实现的——在 footer.inc.php 中totp_secret由$tfa-createSecret()生成后作为 Twig 全局变量注入页面而密钥的持久化只发生在用户提交的验证码校验成功之后见 functions.inc.php 的totp分支。4. 验证verifyCode()将密钥展示给用户后最佳实践是立即验证用户的认证器 App 是否已正确录入该密钥并生成了正确的动态码$result $tfa-verifyCode($secret, $_POST[verification]);若$result为true说明用户已成功将$secret录入其认证器 App且 App 生成了正确的动态码此时你才可以把$secret保存到用户记录中并在用户每次登录时用同一个verifyCode方法校验。4.1 验证的算法细节verifyCode($secret, $code, $discrepancy 1, $time null, $timeslice 0)的完整实现在 lib/TwoFactorAuth.php。其内部逻辑为用当前时间除以$period默认 30 秒取整得到当前时间片timeslice在-discrepancy到discrepancy的窗口内逐一计算每个时间片对应的 TOTP 码并比较刻意遍历窗口内所有时间片即使已匹配成功也继续循环以保持恒定执行时间防范计时侧信道攻击两个验证码的比较使用hash_equals()不存在时退化为逐字节异或比较同样是防时序攻击的常量时间比较见 codeEquals 实现。getCode()则完整实现了 RFC 6238 的 TOTP 计算将时间戳打包为 8 字节二进制串用密钥做 HMAC 哈希取结果末字节低 4 位作为偏移截取 4 字节并按 0x7FFFFFFF保留 31 位最后对10^digits取模并左补零到指定位数见 getCode 实现。4.2 测试向量佐证测试 TwoFactorAuthTest.php 使用 RFC 4226 附录的官方测试向量验证了算法正确性例如$this-assertEquals(543160, $tfa-getCode(VMR466AB62ZBOKHE, 1426847216)); $this-assertTrue($tfa-verifyCode(VMR466AB62ZBOKHE, 543160, 1, 1426847190)); $this-assertFalse($tfa-verifyCode(VMR466AB62ZBOKHE, 543160, 0, 1426847190 30)); // 超出时间片同时测试也覆盖了 sha256、sha512 算法下的多个已知时间点输出见 TwoFactorAuthTest.php可用于在集成后快速验证你环境中的计算结果是否正确。4.3 mailcow 中的完整调用链mailcow 在用户开启 TOTP 时functions.inc.php执行if ($tfa-verifyCode($_POST[totp_secret], $_POST[totp_confirm_token]) true) { // 校验通过将密钥与 key_id 写入 tfa 表并激活 $stmt $pdo-prepare(INSERT INTO tfa (username, key_id, authmech, secret, active) VALUES (?, ?, totp, ?, 1)); $stmt-execute(array($username, $key_id, $_POST[totp_secret])); unset($_SESSION[pending_tfa_setup]); } else { // 校验失败提示 totp_verification_failed }而在用户登录时functions.inc.php则用持久化在数据库中的$row[secret]与用户提交的$_data[token]再次调用$tfa-verifyCode()。这正是官方文档所述保存密钥后每次登录都调用同一verifyCode方法的工程化落地。5. 补充把密钥交给用户的最佳实践——二维码虽然Getting Started一章只要求把密钥文本展示给用户但官方文档明确指出二维码是避免手输错误、并可预填 App 内文本的推荐方式。生成二维码只需p请使用您的应用扫描下方图片:/p img src?php echo $tfa-getQRCodeImageAsDataUri(Bob Ross, $secret); ?getQRCodeImageAsDataUri($label, $secret, $size 200)返回 base64 编码的data:URI二维码内容由 getQRText() 按 Google Authenticator Key URI 格式生成otpauth://totp/{label}?secret{secret}issuer{issuer}period{period}algorithm{ALGO}digits{digits}5.1 默认 QR 提供器与离线替代重要提醒库默认使用QRServerProvider它依赖第三方在线服务生成二维码如果该服务不可达用户将看到二维码加载缓慢甚至无法显示。文档建议使用离线提供器如BaconQrCodeProvider需composer require bacon/bacon-qr-code ^2.0非 SVG 格式还需 PHP imagick 扩展可配置$borderWidth、$backgroundColour、$foregroundColour、$format见 docs/qr-codes/bacon.mdEndroidQrCodeProvider/EndroidQrCodeWithLogoProvider需endroid/qr-code。mailcow 正是选择了BaconQrCodeProvider离线方案prerequisites.inc.php并通过 ajax/qr_gen.php 在用户设置页面动态输出二维码echo $tfa-getQRCodeImageAsDataUri($_SESSION[mailcow_cc_username], $_GET[token]);在线/离线各提供器的完整列表及自定义提供器实现IQRCodeProvider接口的方法见 docs/qr-codes.md。6. 继续深入本仓库中可参考的进阶文档Getting Started只是该库文档体系的第一篇。本仓库还随库携带了以下进阶文档均可直接阅读optional-configuration.md构造函数全部可选参数$issuer、$digits、$period、$algorithm、$qrcodeprovider、$rngprovider、$timeprovider的默认值与用途RNG 提供器的自动选择顺序PHP7 的CSRNGProvider→MCryptRNGProvider→OpenSSLRNGProvider→ 非加密安全的HashRNGProvider见 getRngProvider 实现以及用ensureCorrectTime()借助NTPTimeProvider/HttpTimeProvider校验服务器时间偏差默认容忍 5 秒improved-code-verification.mdverifyCode()的$discrepancy默认 1表示在当前时间片前后各检查几个时间片、$time指定时间点多用于单元测试与$timeslice按引用返回匹配的时间片的进阶用法——将上次成功匹配的 timeslice 与密钥一同存储可有效防御重放攻击index.md文档目录总览demo/demo.php一个无需框架、自带spl_autoload_register的最小可运行示例完整演示了创建密钥 → 展示二维码 → 计算当前码 → 校验码 → 检查服务器时间的全过程适合作为快速原型参考。7. 常见问题与注意事项小结服务器时间必须准确TOTP 依赖时间片对齐。官方演示脚本demo/demo.php专门提示确保服务器时间已 NTP 同步并演示了用ensureCorrectTime()检测偏差。若服务器时钟漂移过大用户会持续验证失败密钥在验证成功前只放 Session避免把无效密钥污染用户数据mailcow 的pending_tfa_setup会话标记即为此设计不要无限调大$discrepancy时间片检查窗口越大验证码有效时间越长被恶意重用的风险越高默认参数 最大兼容性digits6、period30、algorithmsha1与 Google Authenticator 等主流 App 完全兼容一旦改动需要用户使用支持对应参数组合的特定 App。至此从安装、实例化、密钥创建与展示、到安全校验的完整 TOTP 2FA 接入流程已经讲清并且每一步都能在 mailcow-dockerized 仓库的源码与测试中找到真实对应实现可作为你在其他 PHP 项目中接入双因素认证的可靠参考。【免费下载链接】mailcow-dockerizedmailcow: dockerized - 项目地址: https://gitcode.com/GitHub_Trending/ma/mailcow-dockerized创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考