详解PHP做API开发时如何设计安全的签名验证

月亮慢半拍

发布时间：2026-10-13 | 3人浏览过

原创

在PHP API开发中，签名验证是保障通信安全的核心环节。本文将深入解析签名验证的设计原理，从基础的参数排序、加密生成到服务器端的比对逻辑，并针对传统MD5算法的安全性缺陷，提供基于HMAC-SHA256和时间戳防重放的完整安全代码实现方案。

1. 签名验证的核心逻辑

签名验证的主要目的是确保API请求来源合法且传输过程中未被篡改。其基本运作流程包含以下关键步骤：

参数准备与排序：将除签名值以外的所有业务参数按ASCII码升序排列，形成待签名字符串。
签名生成：客户端使用约定好的密钥和加密算法（如HMAC-SHA256）对待签名字符串进行加密，生成签名串（Signature）。
请求发送：将生成的签名串追加至请求头或参数中，发送至服务端。
服务端验签：服务端接收请求后，提取参数并按相同规则生成签名，与客户端传来的签名进行比对。一致则放行，不一致则拒绝。

一个健壮的签名体系还必须包含时间戳（Timestamp）字段，用于限制请求的有效窗口期，防止恶意用户截取旧请求进行重放攻击。

第1步：构建标准签名算法类

为了提高代码的可维护性和安全性，建议将签名逻辑封装为独立的工具类。在实际生产环境中，应避免使用已不安全的MD5，转而采用更稳健的HMAC-SHA256算法。

<?php
class Signer {
    /**
     * @var string 固定密钥，建议在环境变量或配置文件中管理
     */
    private static $secretKey = 'your_secret_key';

    /**
     * 生成签名
     *
     * @param array $params 参与签名的参数数组
     * @return string 生成的签名字符串
     */
    public static function generate(array $params): string {
        // 1. 过滤空值和签名键本身
        unset($params['sign']);
        foreach ($params as $key => $val) {
            if (empty($val)) {
                unset($params[$key]);
            }
        }

        // 2. 按键名ASCII升序排序
        ksort($params);

        // 3. 拼接成 key=value&key=value 格式
        $unSignString = implode('&', array_map(function($k, $v) {
            return "$k=$v";
        }, array_keys($params), array_values($params)));

        // 4. 加入密钥，计算HMAC-SHA256签名
        $signature = hash_hmac('sha256', $unSignString, self::$secretKey);

        return strtoupper($signature);
    }
}

第2步：客户端发起带签名的请求

客户端在构造请求时，需自动附加当前时间戳和生成的签名。以下示例展示了如何使用cURL库正确发送包含签名验证的数据。

<?php
function makeApiRequest($apiUrl, $businessParams) {
    // 添加基础控制参数
    $requestParams = [
        'timestamp' => time(),
        'nonce' => md5(uniqid()), // 随机数，进一步防重放
        'api_key' => 'client_001',
        ...$businessParams
    ];

    // 生成签名
    $requestParams['sign'] = Signer::generate($requestParams);

    // 构造HTTP请求
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $apiUrl,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($requestParams),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
        CURLOPT_TIMEOUT => 10
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// 调用示例
$result = makeApiRequest('https://example.com/api/data', ['data_id' => 12345]);
echo $result['msg']; ?>

第3步：服务端验证请求合法性

服务端收到请求后，必须先校验时效性，再校验签名。只有两项都通过，才处理具体业务逻辑。

<?php
// server.php
header('Content-Type: application/json');

// 1. 获取请求参数
$params = $_POST;
$receivedSign = $params['sign'] ?? '';
unset($params['sign']); // 移除签名，以便重新生成

// 2. 校验时间戳（防止重放攻击，允许误差范围±5分钟）
$currentTimestamp = time();
if (isset($params['timestamp']) && ($currentTimestamp - intval($params['timestamp'])) > 300) {
    http_response_code(403);
    echo json_encode(['code' => -1, 'msg' => 'Request expired']);
    exit;
}

// 3. 校验签名
$expectedSign = Signer::generate($params);
if (!hash_equals($expectedSign, $receivedSign)) { // 使用恒定时间比较函数防时序攻击
    http_response_code(403);
    echo json_encode(['code' => -1, 'msg' => 'Invalid signature']);
    exit;
}

// 4. 签名通过，执行业务逻辑
echo json_encode(['code' => 0, 'msg' => 'Success', 'data' => ['info' => 'secure data']]);
?>