Spomky-Labs/otphp 项目：OTP 参数自定义完全指南-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00240/article/details/149014378

Spomky-Labs/otphp 项目：OTP 参数自定义完全指南

前言

在双因素认证(2FA)系统中，一次性密码(OTP)是最常用的验证方式之一。Spomky-Labs/otphp 是一个强大的PHP库，提供了灵活的方式来生成和验证OTP。本文将深入探讨如何自定义OTP的各项参数，以满足不同场景下的安全需求。

基础参数配置

所有类型的OTP都需要以下三个基本参数：

Secret (密钥)：Base32编码的密钥字符串
Digest Algorithm (摘要算法)：用于生成OTP的哈希算法
Digits (数字位数)：生成的OTP码长度

1. 密钥(Secret)自定义

默认情况下，库会生成512位的密钥。但你可以自定义密钥长度：

use OTPHP\TOTP;
use ParagonIE\ConstantTime\Base32;

// 生成1024位的自定义密钥
$mySecret = trim(Base32::encodeUpper(random_bytes(128)), '=');
$otp = TOTP::createFromSecret($mySecret);

注意：库会自动移除Base32编码中的尾部等号(=)。

2. 摘要算法选择

默认使用SHA1算法，但支持PHP hash_algos()列出的所有算法：

$totp = TOTP::generate();
$totp->setDigest('sha256');  // 更安全的SHA256算法

安全建议：优先考虑SHA-2系列算法(SHA256/SHA512)，它们提供更好的安全性。

3. 数字位数设置

默认生成6位OTP码，可根据需求调整：

$totp = TOTP::generate();
$totp->setDigits(8);  // 生成8位OTP码

注意：超过10位的OTP可能影响用户体验。

特定类型OTP的额外参数

TOTP(基于时间)特有参数

周期(Period)

默认30秒，可根据安全需求调整：

$otp = TOTP::generate();
$otp->setPeriod(60);  // 设置为60秒周期

纪元(Epoch)

纪元相当于RFC 6238中的T0参数，定义计数开始的时间点：

$otp = TOTP::generate();
$otp->setEpoch(1519401289);  // 设置特定开始时间戳

重要安全提示：使用固定纪元时，应配合动态密钥以避免生成重复OTP。

HOTP(基于计数器)特有参数

计数器(Counter)

$otp = HOTP::generate();
$otp->setCounter(1000);  // 设置初始计数器值

最佳实践：通常从0开始计数器，但可根据需要设置任意非负值。

高级自定义功能

1. 自定义参数

可以添加任意自定义参数，这些参数会包含在配置URI中：

$totp = TOTP::createFromSecret('JBSWY3DPEHPK3PXP');
$totp->setParameter('custom_param', 'value');

2. 发行者(Issuer)设置

为区分相同标签的不同OTP，建议设置发行者：

$totp->setIssuer('My Company');
$totp->setIssuerIncludedAsParameter(false);  // 可选：不在URI参数中包含发行者

3. 图像设置

某些OTP应用支持显示关联图像：

$totp->setParameter('image', 'https://example.com/logo.png');

实际应用示例

高安全TOTP配置

use OTPHP\TOTP;

$totp = TOTP::generate();
$totp->setPeriod(30);               // 30秒周期
$totp->setDigest('sha512');         // 使用SHA512算法
$totp->setDigits(8);                // 8位OTP码
$totp->setIssuer('Bank System');    // 设置发行者
$totp->setLabel('user@bank.com');   // 设置用户标识

// 获取配置URI，可用于生成二维码
$provisioningUri = $totp->getProvisioningUri();

自定义纪元的高级场景

$otp = TOTP::generate();
$otp->setPeriod(5);                 // 5秒短周期
$otp->setEpoch(time());             // 设置当前时间为纪元

// 生成OTP
$password = $otp->at(time());

// 验证窗口内有效
$otp->verify($password, time()+3);  // 5秒周期内有效