动态口令密码应用的技术原理与 GM/T 0021 标准深度解读：从 HOTP/TOTP 到国密算法实现

┌─────────────────────────────────────────────────────────┐
│                    OTP 生成模型                           │
│                                                         │
│  ┌──────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │ 种子密钥  │ +  │   动态因子    │ → │  哈希/加密运算 │  │
│  │ (Secret) │    │  (Counter/   │    │   (SHA-1/    │  │
│  │          │    │   Timestamp) │    │    SM3/SM4)  │  │
│  └──────────┘    └──────────────┘    └──────────────┘  │
│                                            │            │
│                                            ▼            │
│                                    ┌──────────────┐    │
│                                    │   截断函数    │    │
│                                    │ (Truncation) │    │
│                                    └──────────────┘    │
│                                            │            │
│                                            ▼            │
│                                    ┌──────────────┐    │
│                                    │ 6-8位数字OTP │    │
│                                    └──────────────┘    │
└─────────────────────────────────────────────────────────┘

def hmac_sha1_truncate(hmac_result: bytes) -> int:
    """RFC 4226 截断函数"""
    # 取低 4 位作为偏移量（0-15）
    offset = hmac_result[-1] & 0x0F
    # 从偏移量开始取 4 字节
    code = (
        ((hmac_result[offset] & 0x7F) << 24) |
        ((hmac_result[offset + 1] & 0xFF) << 16) |
        ((hmac_result[offset + 2] & 0xFF) << 8) |
        (hmac_result[offset + 3] & 0xFF)
    )
    # 取模得到 6 位数字
    return code % 1_000_000

┌─────────────────────────────────────────────────────────┐
│              TOTP 服务端验证流程                         │
│                                                         │
│  1. 接收客户端OTP + 时间戳（可选）                        │
│  2. 计算当前时间步 index = floor(current_time / 30)      │
│  3. 遍历窗口 [index - lookahead, index + lookahead]      │
│     对每个 index_i：                                      │
│       otp_i = HOTP(secret, index_i)                     │
│       如果 otp_i == client_otp → 验证通过               │
│  4. 全部不匹配 → 验证失败                                │
│  5. 验证通过后：                                         │
│     - HOTP: 更新服务端计数器 = matched_index + 1         │
│     - TOTP: 记录已使用的 (otp, time_step) 防重放         │
└─────────────────────────────────────────────────────────┘

# ⚠️ 原理演示代码，非完整生产实现
# SM3 算法通过 gmssl 库或 cryptography（v41+）调用
import struct
import time

def sm3_otp_generate(seed_key: bytes, time_step: int = 30, digits: int = 6, current_time: int = None) -> str:
    """
    GM/T 0021 风格的 SM3 TOTP 生成（伪代码）
    参数 current_time 用于指定时间，默认使用当前时间
    """
    # 1. 计算时间因子
    t = (current_time if current_time is not None else int(time.time())) // time_step
    time_factor = struct.pack(">Q", t)  # 8 字节大端
    
    # 2. 拼接种子密钥与时间因子
    #    具体拼接顺序和编码参考 GM/T 0021 标准原文
    data = seed_key + time_factor
    
    # 3. SM3 哈希运算
    #    digest = sm3_hash(data)  # 通过国密库调用，输出 32 字节
    
    # 4. 截断（类似 RFC 4226）
    # offset = digest[-1] & 0x1F  # SM3 32 字节，取低 5 位 → 0-31
    #   取 4 字节，掩码高位：
    # code = ((digest[offset] & 0x7F) << 24) | \
    #        ((digest[offset+1] & 0xFF) << 16) | \
    #        ((digest[offset+2] & 0xFF) << 8) | \
    #        (digest[offset+3] & 0xFF)
    
    # 5. 取模生成 OTP
    # otp = code % (10 ** digits)
    # return str(otp).zfill(digits)
    
    # 完整实现需引入国密 SM3 函数库
    # 推荐使用 gmssl（pip install gmssl）或 Tongsuo OpenSSL 绑定
    pass


def sm3_otp_verify(
    seed_key: bytes,
    client_otp: str,
    current_time: int = None,
    look_ahead: int = 2,
    time_step: int = 30,
    digits: int = 6
) -> dict:
    """
    GM/T 0021 风格的服务端验证
    
    返回：{"valid": bool, "matched_step": int} 
    """
    if current_time is None:
        current_time = int(time.time())
    
    current_step = current_time // time_step
    
    # 搜索窗口内的所有可能口令
    for offset in range(-look_ahead, look_ahead + 1):
        check_step = current_step + offset
        # 使用 check_step 计算预期 OTP
        check_time = check_step * time_step
        expected_otp = sm3_otp_generate(seed_key, time_step, digits, check_time)
        if expected_otp == client_otp:
            return {"valid": True, "matched_step": check_step}
    
    return {"valid": False, "matched_step": -1}

-- 方案一：记录已使用的 (otp, step) 对
CREATE TABLE used_otp_records (
    user_id     INTEGER NOT NULL,
    time_step   INTEGER NOT NULL,
    otp_value   VARCHAR(8) NOT NULL,
    used_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (user_id, time_step, otp_value)
);

-- 验证时先检查是否已使用
-- INSERT 失败（主键冲突）→ 重放攻击

-- 定期清理过期记录（窗口外的记录不再需要）
DELETE FROM used_otp_records 
WHERE time_step < (current_step - look_ahead);

# 方案二：基于步长的单调递增验证（HOTP 方式适配 TOTP）
# 记录每个用户最后成功认证的步长，拒绝任何 <= last_step 的认证请求
def verify_with_monotonic_step(user_id: int, otp: str, step: int, db_session):
    last_step = db_session.query(User.otp_last_step).filter_by(id=user_id).scalar()
    
    if step <= last_step:
        return False  # 重放或时钟回退攻击
    
    # 验证 OTP...
    if otp_matches:
        db_session.query(User).filter_by(id=user_id).update({"otp_last_step": step})
        db_session.commit()
        return True
    return False

┌─────────────────────────────────────────────────────────┐
│                    密钥分散模型                           │
│                                                         │
│  根密钥（Root Key，存储在密码机中）                        │
│       │                                                 │
│       │ 分散因子（如用户ID/手机号/身份证号）               │
│       ▼                                                 │
│  ┌─────────────┐                                        │
│  │ 密钥派生函数 │  KDF = SM3(RootKey || Factor)          │
│  │ （SM3 杂凑） │     或 SM4-KDF(RootKey, Factor)         │
│  └─────────────┘                                        │
│       │                                                 │
│       ▼                                                 │
│  用户专属种子密钥（User Seed）                            │
│       │                                                 │
│       │ 动态因子                                         │
│       ▼                                                 │
│  用户动态口令                                            │
└─────────────────────────────────────────────────────────┘