鱼梦江湖 @Yumengjh

外观

基于时间戳的动态密钥认证机制实现

约 1285 字大约 4 分钟

Nest.js

2025-07-11

背景介绍

在 Web 应用开发中，API 接口的安全性一直是一个重要话题。传统的认证方式如 JWT、Session 等都有其适用场景，但在某些特定场景下（如只需要限制特定客户端访问），这些方案可能显得过重。本文将介绍一种基于时间戳的动态密钥认证机制，它具有实现简单、安全可靠、性能高效等特点。

实现原理

该认证机制的核心思想是：

  1. 前后端共享一个密钥（Secret Key）
  2. 使用当前时间戳 + 密钥生成签名
  3. 在请求时带上时间戳和签名
  4. 服务端验证时间戳是否在有效期内，并重新计算签名进行比对

安全性保障

  • 使用 HMAC-SHA256 进行签名，确保签名不可逆
  • 基于时间戳的动态验证，防止重放攻击
  • 使用 crypto.timingSafeEqual 防止时序攻击
  • 严格的时间窗口控制，默认 30 秒

技术实现

1. 工具类实现（auth.util.ts）

import * as crypto from 'crypto';

export class AuthUtil {
  private static readonly TIME_TOLERANCE = 30; // 允许的时间误差（秒）

  /**
   * 生成动态密钥
   * @param secretKey 服务器密钥
   * @returns { timestamp: number; signature: string }
   */
  static generateDynamicAuth(secretKey: string) {
    const timestamp = Math.floor(Date.now() / 1000); // 转换为秒
    const signature = this.generateSignature(timestamp, secretKey);
    return { timestamp, signature };
  }

  /**
   * 验证动态密钥
   * @param timestamp 客户端时间戳
   * @param signature 客户端签名
   * @param secretKey 服务器密钥
   */
  static verifyDynamicAuth(timestamp: number, signature: string, secretKey: string): boolean {
    const currentTime = Math.floor(Date.now() / 1000);
    
    // 检查时间戳是否在允许范围内
    if (Math.abs(currentTime - timestamp) > this.TIME_TOLERANCE) {
      return false;
    }

    // 生成服务器端签名并比对
    const serverSignature = this.generateSignature(timestamp, secretKey);
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(serverSignature)
    );
  }

  /**
   * 生成签名
   * @param timestamp 时间戳
   * @param secretKey 密钥
   */
  private static generateSignature(timestamp: number, secretKey: string): string {
    return crypto
      .createHmac('sha256', secretKey)
      .update(timestamp.toString())
      .digest('hex');
  }
}

2. 守卫实现（dynamic-auth.guard.ts）

import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { AuthUtil } from '../utils/auth.util';

@Injectable()
export class DynamicAuthGuard implements CanActivate {
  constructor(private configService: ConfigService) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const timestamp = request.headers['x-timestamp'];
    const signature = request.headers['x-signature'];

    if (!timestamp || !signature) {
      throw new UnauthorizedException('缺少认证信息');
    }

    const secretKey = this.configService.get<string>('AUTH_SECRET_KEY');
    if (!secretKey) {
      throw new UnauthorizedException('服务器配置错误');
    }

    const isValid = AuthUtil.verifyDynamicAuth(
      parseInt(timestamp),
      signature,
      secretKey
    );

    if (!isValid) {
      throw new UnauthorizedException('认证失败');
    }

    return true;
  }
}

3. 在控制器中使用

@Controller('api')
@UseGuards(DynamicAuthGuard)  // 应用认证守卫
export class ApiController {
  // ... 控制器方法
}

4. 前端实现

// auth.ts
const generateAuthHeaders = async () => {
  const secretKey = process.env.NEXT_PUBLIC_AUTH_SECRET_KEY;
  const timestamp = Math.floor(Date.now() / 1000);
  
  const signature = CryptoJS.HmacSHA256(timestamp.toString(), secretKey).toString();
  
  return {
    'x-timestamp': timestamp.toString(),
    'x-signature': signature,
  };
};

// API 调用示例
const fetchData = async () => {
  const headers = await generateAuthHeaders();
  
  const response = await fetch('your-api-url', {
    headers: {
      ...headers,
      'Content-Type': 'application/json',
    },
  });
  
  return response.json();
};

关键技术点解析

1. HMAC-SHA256 算法

HMAC（Hash-based Message Authentication Code）是一种基于哈希函数的消息认证码算法，它可以用来检查消息的完整性和真实性。在本实现中，我们使用 SHA256 作为底层哈希函数，这提供了足够的安全性。

2. 时序攻击防护

使用 crypto.timingSafeEqual 而不是简单的字符串比较，可以防止通过比较时间差异来推测签名的时序攻击。

3. 时间窗口控制

设置 30 秒的时间窗口，在保证安全性的同时，也考虑到了前后端时间可能存在的轻微差异。

安全性分析

  1. 防重放攻击

    • 每个签名都包含时间戳
    • 严格的时间窗口控制
    • 过期签名自动失效

  2. 防篡改

    • HMAC-SHA256 确保消息完整性
    • 修改任何参数都会导致验证失败

  3. 密钥安全

    • 服务器密钥通过环境变量管理
    • 签名过程不可逆，无法从签名推导出密钥

最佳实践建议

  1. 密钥管理
    • 使用足够长的随机密钥
    • 定期轮换密钥
    • 使用环境变量存储密钥
// 生成安全的随机密钥
const secretKey = crypto.randomBytes(32).toString('hex');

  1. 传输安全

    • 必须使用 HTTPS
    • 设置适当的 CORS 策略
    • 添加请求频率限制

  2. 监控和日志

    • 记录认证失败的尝试
    • 监控异常的请求模式
    • 设置告警机制

扩展优化

  1. IP 白名单
static isIPAllowed(ip: string): boolean {
  const allowedIPs = process.env.ALLOWED_IPS?.split(',') || [];
  return allowedIPs.includes(ip);
}
  1. 请求频率限制
static readonly requestLimits = new Map<string, number>();
static isRequestAllowed(clientId: string): boolean {
  const now = Date.now();
  const lastRequest = this.requestLimits.get(clientId) || 0;
  if (now - lastRequest < 1000) {
    return false;
  }
  this.requestLimits.set(clientId, now);
  return true;
}

总结

这种基于时间戳的动态密钥认证机制具有以下优势：

  1. 简单高效

    • 无需数据库操作
    • 实现简单，维护成本低
    • 验证过程快速

  2. 安全可靠

    • 防重放攻击
    • 防时序攻击
    • 签名不可逆

  3. 灵活可扩展

    • 易于集成到现有系统
    • 可以添加额外的安全层
    • 支持自定义时间窗口

这种认证机制特别适合以下场景：

  • 个人博客 API 保护
  • 内部系统接口认证
  • 特定客户端访问控制

只要确保密钥的安全性，这种认证机制在大多数场景下都是一个简单且安全的选择。

贡献者: 鱼梦江湖, yumengjh