otp

otp

简介

otp 包提供了基于时间的一次性密码（TOTP）算法的完整实现，符合 RFC 6238 标准。该包还支持基于 HMAC 的一次性密码（HOTP）算法，适用于双因素身份验证（2FA）和多因素身份验证（MFA）场景。

主要特性

• 完整实现 TOTP 和 HOTP 算法
• 支持多种哈希算法（SHA1、SHA256、SHA512）
• 可配置的密码长度和有效期
• 时间窗口验证机制
• 支持生成兼容 Google Authenticator 的 URL
• 完整的错误处理
• 易于使用的 API 和选项模式
• 线程安全设计

设计理念

该包的设计理念是提供一个灵活且易于使用的 OTP 实现，同时保持与各种身份验证应用程序的兼容性。通过选项模式设计，用户可以根据自己的需求自定义 OTP 的各种参数，如哈希算法、密码长度、有效期等。包的实现专注于安全性和可靠性，遵循相关安全标准，并提供了详细的测试覆盖。

安装

前置条件

• Go 版本要求：Go 1.18 或更高版本
• 依赖要求：
  • Go 标准库的 crypto 包

安装命令

go get -u github.com/fsyyft-go/kit/crypto/otp

快速开始

基础用法

package main

import (
    "fmt"
    "github.com/fsyyft-go/kit/crypto/otp"
)

func main() {
    // 生成或使用现有的密钥（Base32 编码）
    secretKey := "JBSWY3DPEHPK3PXP" // 实际应用中应安全生成和存储
    
    // 使用默认设置创建 TOTP 实例（SHA1、6位数字、30秒有效期）
    totpInstance, err := otp.NewOneTimePassword(secretKey)
    if err != nil {
        panic(err)
    }
    
    // 生成当前时间的一次性密码
    password, err := totpInstance.Password()
    if err != nil {
        panic(err)
    }
    fmt.Printf("当前一次性密码: %s\n", password)
    
    // 验证一次性密码
    isValid := totpInstance.VeryfyPassword(password)
    fmt.Printf("密码验证结果: %v\n", isValid)
    
    // 生成用于二维码的 URL
    url := totpInstance.GenerateURL()
    fmt.Printf("扫描此 URL 添加到验证器应用: %s\n", url)
}

配置选项

// 自定义 TOTP 设置
totpInstance, err := otp.NewOneTimePassword(
    secretKey,
    otp.WithSHA256(),                // 使用 SHA256 算法
    otp.WithDigits(8),               // 生成 8 位密码
    otp.WithPeriodSeconds(60),       // 60 秒有效期
    otp.WithWindowSize(2),           // 前后 2 个时间窗口都视为有效
    otp.WithIssuer("MyCompany"),     // 设置发行者（在验证器应用中显示）
    otp.WithLabel("user@example.com"), // 设置标签（通常是用户标识）
)

详细指南

核心概念

基于时间的一次性密码（TOTP）是一种算法，它根据当前时间和共享密钥生成一次性密码。 这种密码具有时间限制，通常在短时间（如 30 秒）后失效，从而提供更高的安全性。

本包实现了 RFC 6238 中定义的 TOTP 算法，其核心是基于 HMAC 的一次性密码（HOTP）算法和时间因子的组合。 时间因子是从 Unix 时间戳派生的，将时间戳除以时间步长（通常为 30 秒）得到的整数值。

常见用例

1. 实现登录的双因素认证（2FA）

// 用户注册时，生成并存储密钥
secretKey := "JBSWY3DPEHPK3PXP" // 实际应用中应安全生成

// 创建 URL 供用户添加到验证器应用
url := otp.GenerateURL(secretKey, 
    otp.WithIssuer("MyApp"), 
    otp.WithLabel("user@example.com"))

// 向用户展示二维码（使用该 URL 生成）
fmt.Println("请扫描二维码添加到验证器应用:", url)

// 登录时验证用户提供的一次性密码
func verifyLogin(secretKey, userInputCode string) bool {
    return otp.VeryfyPassword(secretKey, userInputCode)
}

2. 使用自定义参数创建更安全的 TOTP

// 创建使用 SHA512 和 8 位数字的 TOTP
totpInstance, err := otp.NewOneTimePassword(
    secretKey,
    otp.WithSHA512(),  // 使用更安全的 SHA512 哈希算法
    otp.WithDigits(8), // 使用 8 位密码增加复杂度
    otp.WithPeriodSeconds(15), // 缩短有效期到 15 秒
)
if err != nil {
    panic(err)
}

// 获取当前有效的所有密码（考虑时间窗口）
validPasswords, err := totpInstance.EffectivePassword()
if err != nil {
    panic(err)
}

fmt.Printf("当前有效的密码: %v\n", validPasswords)

最佳实践

• 密钥管理

  • 安全地生成、存储和传输密钥
  • 使用加密数据库存储用户密钥
  • 考虑在服务端加密密钥后再存储

• 安全考虑

  • 对于高安全性要求，使用 SHA256 或 SHA512
  • 考虑使用 8 位或更长密码
  • 实现速率限制，防止暴力破解
  • 监控异常登录尝试

• 用户体验

  • 提供恢复代码，防止用户丢失设备
  • 考虑时间同步问题，适当调整时间窗口大小
  • 清晰地向用户解释如何使用和备份 2FA

API 文档

主要类型

// OneTimePassword 定义了一次性密码的接口
type OneTimePassword interface {
    // 根据当前时间生成密码
    Password() (string, error)
    
    // 生成指定时间窗口内的所有密码
    EffectivePassword() ([]string, error)
    
    // 验证密码是否在指定时间窗口内
    VeryfyPassword(password string) bool
    
    // 生成对应的 URL 表示形式的字符串
    GenerateURL() string
}

关键函数

NewOneTimePassword

创建一个一次性密码生成器

func NewOneTimePassword(secretKeyBase32 string, options ...OneTimePasswordOption) (*oneTimePassword, error)

示例：

totp, err := otp.NewOneTimePassword("JBSWY3DPEHPK3PXP", otp.WithSHA256())
if err != nil {
    panic(err)
}

VeryfyPassword

验证一次性密码是否有效

func VeryfyPassword(secretKeyBase32, password string, options ...OneTimePasswordOption) bool

示例：

isValid := otp.VeryfyPassword("JBSWY3DPEHPK3PXP", "123456")

GenerateURL

生成可用于二维码的 URL

func GenerateURL(secretKeyBase32 string, options ...OneTimePasswordOption) string

示例：

url := otp.GenerateURL("JBSWY3DPEHPK3PXP", otp.WithIssuer("MyApp"))

配置选项

• WithSHA256() - 使用 SHA256 哈希算法（默认为 SHA1）
• WithSHA512() - 使用 SHA512 哈希算法
• WithDigits(digits int) - 设置密码长度（默认为 6）
• WithPeriodSeconds(periodSeconds int) - 设置密码有效期（默认为 30 秒）
• WithWindowSize(windowSize int) - 设置时间窗口大小（默认为 1）
• WithIssuer(issuer string) - 设置发行者名称
• WithLabel(label string) - 设置标签（通常是用户标识）

错误处理

本包返回以下类型的错误：

• 密钥格式错误：当 Base32 格式的密钥无法正确解码时
• 参数错误：当配置参数不合法时（如负数的时间窗口）
• 内部操作错误：生成密码过程中可能发生的内部错误

建议始终检查 NewOneTimePassword 和 Password 返回的错误。

性能指标

测试覆盖率

调试指南

常见问题排查

验证总是失败

• 检查服务器和客户端时间是否同步
• 验证密钥是否正确传输和存储
• 考虑增加时间窗口大小（使用 WithWindowSize）
• 检查密码长度设置是否与客户端一致

与验证器应用不兼容

• 确保使用标准的 Base32 编码密钥
• 验证 URL 格式是否符合标准
• 检查 issuer 和 label 参数是否正确设置
• 确认哈希算法与验证器支持的一致（大多数支持 SHA1）

相关文档

• RFC 6238 - TOTP
• RFC 4226 - HOTP
• Google Authenticator Key URI Format

贡献指南

我们欢迎任何形式的贡献，包括但不限于：

• 报告问题
• 提交功能建议
• 提交代码改进
• 完善文档

请参考我们的贡献指南了解详细信息。

许可证

本项目采用 MIT 许可证。查看 LICENSE 文件了解更多信息。