google authenticator 严格遵循 rfc 6238 标准 totp，需 base32 密钥、30 秒时间步长、hmac-sha1 动态截断；推荐使用 oath-net 库（otp.net），避免手写逻辑或过时的 googleauthenticator，并校验 ±1 时间窗口以兼容时钟漂移。
Google Authenticator 使用的是 TOTP 算法，不是自定义加密
直接调用 HMACSHA1 或手写时间步长计算很容易出错——Google Authenticator 只认标准 TOTP（RFC 6238），且要求严格对齐时间窗口、Base32 密钥、Unix 时间戳步长（默认 30 秒）和 HMAC-SHA1 输出截断逻辑。
别自己拼 HMACSHA1 + DateTimeOffset.UtcNow.ToUnixTimeSeconds() + 字节截断，漏掉任何一环都会导致验证码不匹配。
- 密钥必须是 Base32 编码的原始字节（不是字符串 ASCII 值）
- 时间步长必须用
(time / 30)向下取整，不能四舍五入或用 DateTime.Second - 最终 8 位数字必须是动态截断（DT）：取 HMAC 最后 4 bit 作为偏移，再取前 4 字节转 uint32，再 mod 1000000
推荐用 oath-net 库，而非手撸或用过时的 GoogleAuthenticator
社区维护最活跃、测试最全的是 oath-net（NuGet 包名：Otp.NET），它严格遵循 RFC 6238 和 RFC 4226，支持 TOTP/HOTP，且已适配 .NET Standard 2.0+ 和 .NET 5+。
旧包 GoogleAuthenticator 已多年未更新，存在 Base32 解码 bug（比如把 2 和 Z 混淆），且不支持自定义哈希算法（如 SHA256）。
- 安装：
dotnet add package Otp.NET - 生成密钥：
var key = KeyGeneration.GenerateRandomKey(20);（返回 byte[]，不是字符串） - 转 Base32 供用户扫码：
Rfc3548Encoding.ToBase32String(key)（不是Convert.ToBase64String） - 生成当前 TOTP：
var totp = new Totp(key); totp.ComputeTotp()（自动处理时间、截断、补零）
服务端验证必须容忍时间漂移，不能只校验当前值
客户端手机时钟可能快/慢 1–2 分钟，Google Authenticator 自身就允许 ±1 个时间步长（即 ±30 秒）校验。硬性比对 ComputeTotp() 当前结果，会导致大量合法请求失败。
正确做法是：在服务端生成 [t−1, t, t+1] 三个时间窗口的 TOTP 值，任一匹配即通过。注意不要扩大到 ±2（即 5 个值），会显著增加重放攻击窗口。
- 用
totp.VerifyTotp(providedCode, out long timeStepMatched, verificationWindow: 1)（Otp.NET内置支持） - 不要手动循环调用
ComputeTotp()三次——VerifyTotp已优化并处理了边界时间（如跨步长瞬间） - 记录
timeStepMatched可用于检测重复使用同一码（防止重放）
密钥存储与初始化阶段最容易被忽略的细节
用户首次绑定 Google Authenticator 时，你给他的二维码内容格式必须是标准 URI Scheme：otpauth://totp/YourApp:username?secret=JBSWY3DPEHPK3PXP&issuer=YourApp&digits=6&period=30。少一个参数，部分客户端（尤其是 iOS）可能无法识别。
-
secret必须是 Rfc3548 Base32 字符串（大写、无空格、无填充等号），且不含小写字母 -
issuer建议设置，否则 Android 端可能把所有账号归为“Unnamed”组，难区分 - 别把密钥明文存数据库；至少 AES 加密（用独立密钥），或用带盐的派生密钥加密
- 前端展示二维码时，确保
width/height≥ 200px，否则 iPhone 扫码失败率陡增
生成二维码本身不难，但漏掉 issuer 或 secret 大小写问题，会让用户卡在第一步——而这个错误根本不会抛异常，只是扫码后没反应。
