PHP 接口签名验证：HMAC-SHA256 与时间戳防重放实现方案

在前后端分离、微服务架构普及的当下，API 接口的安全性直接决定了系统的整体安全水位。未经签名保护的接口极易遭遇数据篡改、请求伪造、重放攻击等风险，而 HMAC-SHA256 结合时间戳的签名方案，凭借实现成本低、安全强度高的特性，成为中小型项目接口鉴权的主流选择。

一、核心安全原理

1. HMAC-SHA256 签名机制

HMAC（Hash-based Message Authentication Code）即哈希消息认证码，基于 SHA-256 哈希函数，配合双方预先约定的密钥（Secret Key）对请求参数进行加密运算，生成固定长度的签名字符串。其核心价值在于两点：一是保证数据完整性，参数被篡改后签名必然失效；二是实现身份认证，只有持有正确密钥的客户端才能生成合法签名。

与普通 MD5、SHA256 哈希相比，HMAC 引入了密钥因子，即使攻击者截获请求参数，没有密钥也无法伪造有效签名，安全等级显著提升。

2. 时间戳防重放逻辑

重放攻击指攻击者截获合法请求后，原样重复发送给服务器以达成恶意目的。时间戳方案的核心思路是：客户端在请求中携带当前时间戳，服务端接收后校验时间戳与服务器当前时间的差值，若超出设定的有效期窗口（通常为 60-300 秒）则直接拒绝请求，大幅缩小重放攻击的可利用时间窗口。

仅靠时间戳仍存在窗口期内的重放风险，因此通常会搭配 nonce 随机字符串，服务端缓存有效期内的 nonce 值，相同 nonce 的请求直接判定为重复请求，实现窗口期内的二次防护。

二、完整签名规则约定

在编码实现前，需先统一客户端与服务端的签名规范，常见约定如下：

剔除空值参数与 sign 参数本身，按参数名 ASCII 码从小到大升序排列；
将排序后的参数拼接为key1=value1&key2=value2格式的字符串；
在拼接字符串末尾追加密钥，格式为&secret=密钥值；
使用 HMAC-SHA256 算法对最终字符串进行加密，结果转为小写十六进制字符串作为 sign 值；
请求头中必须携带timestamp（时间戳）、nonce（随机字符串）、sign（签名值）三个字段。

三、PHP 服务端实现代码

签名验证核心类

php

class Signature
{
    // 密钥，实际项目中建议存入配置文件或环境变量
    private string $secret = 'your_secret_key_here';
    
    // 请求有效期，单位秒，默认5分钟
    private int $expire = 300;
    
    // nonce缓存前缀，建议使用Redis存储
    private string $noncePrefix = 'api_nonce:';

    /**
     * 校验请求签名
     */
    public function verify(array $params, string $timestamp, string $nonce, string $sign): bool
    {
        // 1. 校验时间戳有效性
        if (abs(time() - $timestamp) > $this->expire) {
            return false;
        }

        // 2. 校验nonce是否已使用
        if ($this->isNonceUsed($nonce)) {
            return false;
        }

        // 3. 生成服务端签名并比对
        $serverSign = $this->generateSign($params);
        if (!hash_equals($serverSign, strtolower($sign))) {
            return false;
        }

        // 4. 记录已使用的nonce
        $this->recordNonce($nonce);
        return true;
    }

    /**
     * 生成签名
     */
    public function generateSign(array $params): string
    {
        // 剔除空值与sign参数
        $params = array_filter($params, function ($val) {
            return $val !== '' && $val !== null;
        });
        unset($params['sign']);

        // 按键名升序排列
        ksort($params);

        // 拼接参数
        $paramStr = urldecode(http_build_query($params));
        $paramStr .= '&secret=' . $this->secret;

        // HMAC-SHA256加密
        return hash_hmac('sha256', $paramStr, $this->secret);
    }

    /**
     * 判断nonce是否已使用（示例使用Redis）
     */
    private function isNonceUsed(string $nonce): bool
    {
        $redis = new Redis();
        $redis->connect('127.0.0.1', 6379);
        return $redis->exists($this->noncePrefix . $nonce) > 0;
    }

    /**
     * 记录nonce，设置过期时间与请求有效期一致
     */
    private function recordNonce(string $nonce): void
    {
        $redis = new Redis();
        $redis->connect('127.0.0.1', 6379);
        $redis->setex($this->noncePrefix . $nonce, $this->expire, 1);
    }
}

接口调用示例

php

// 获取请求头与参数
$timestamp = $_SERVER['HTTP_TIMESTAMP'] ?? '';
$nonce = $_SERVER['HTTP_NONCE'] ?? '';
$sign = $_SERVER['HTTP_SIGN'] ?? '';
$params = $_REQUEST;

// 执行校验
$signature = new Signature();
if (!$signature->verify($params, $timestamp, $nonce, $sign)) {
    header('Content-Type: application/json');
    echo json_encode([
        'code' => 401,
        'msg' => '签名验证失败',
        'data' => null
    ]);
    exit;
}

// 验证通过，执行业务逻辑
echo json_encode(['code' => 200, 'msg' => 'success', 'data' => []]);

四、客户端请求示例

php

$secret = 'your_secret_key_here';
$timestamp = time();
$nonce = md5(uniqid(mt_rand(), true));

// 请求参数
$params = [
    'user_id' => 1001,
    'page' => 1,
    'page_size' => 20
];

// 生成签名
ksort($params);
$paramStr = urldecode(http_build_query($params));
$paramStr .= '&secret=' . $secret;
$sign = hash_hmac('sha256', $paramStr, $secret);

// 发起请求
$ch = curl_init('https://api.example.com/user/list');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Timestamp: {$timestamp}",
    "Nonce: {$nonce}",
    "Sign: {$sign}"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

五、安全加固最佳实践

密钥安全管理：禁止硬编码在业务代码中，建议通过环境变量或配置中心注入，定期轮换密钥；多端接入时采用 AppKey+AppSecret 模式，不同端分配独立密钥。
传输层加密：签名仅解决应用层问题，接口必须强制开启 HTTPS，避免传输过程中请求被明文截获。
异常限流：对签名失败的 IP 设置频率限制，防止攻击者暴力枚举密钥；对同一接口的高频请求触发熔断机制。
参数白名单：服务端只参与约定参数的签名运算，避免多余参数混入签名逻辑引发意外漏洞。
时钟同步：服务器需配置 NTP 时间同步，避免因时钟偏差导致合法请求被误拦截；可适当放宽时间窗口降低误判率。

六、方案局限性与进阶方向

HMAC-SHA256 + 时间戳方案足以应对绝大多数常规业务场景，但在金融、支付等高安全等级场景下仍存在不足。如需进一步提升安全等级，可考虑引入 RSA 非对称加密签名、请求体整体加密、接口令牌机制等方案，构建多层防护体系。

总体而言，该方案实现简单、性能损耗低、兼容性强，是 PHP 项目接口安全防护的入门首选方案，能够以极低的开发成本抵御绝大多数常见接口攻击。