Laravel如何做API请求签名验证_Laravel防止参数被篡改机制【介绍】-Laravel-PHP中文网

应使用 hash_hmac() 而非 Hash::make()：前者是密钥化、可复现、高性能的确定性哈希，适用于 API 签名；后者为密码设计，带盐且不可逆，会导致验签失败。

laravel如何做api请求签名验证_laravel防止参数被篡改机制【介绍】

签名验证该用 `Hash::make()` 还是 `hash_hmac()`？

别用 Hash::make() —— 它是为密码设计的慢哈希，不可逆、带盐、耗时，完全不适合 API 签名。签名必须可复现、快、确定性高。hash_hmac() 才是正解，它用密钥+数据生成固定长度摘要，服务端和客户端能独立算出同一结果。

常见错误：把 Hash::make($data . $secret) 当签名用，导致每次结果不同，验签必失败；或者用 md5($data . $secret)，不抗碰撞、无密钥保护，中间人可重放或篡改。

hash_hmac('sha256', $message, $secret_key) 是 Laravel 中最稳妥的选择，PHP 原生支持，Laravel 也默认推荐
密钥 $secret_key 必须存在配置里（如 config/api.php），不能硬编码在控制器中
签名原文 $message 必须严格排序、标准化：参数按 key 字典序排列，URL 编码，不含空格和换行

请求参数顺序乱了，签名总对不上怎么办？

签名对不上，八成是客户端和服务端拼接参数的顺序或格式不一致。Laravel 默认不帮你做标准化，得自己收口。

典型现象：401 Unauthorized 或 "Invalid signature"，但单独 echo 出来的签名看起来“应该没错”。问题往往出在 GET 参数键值对的遍历顺序上——PHP 数组遍历顺序依赖插入顺序，而 JS/Python/Java 的 Map 不一定保证字典序。

强制要求所有参与签名的参数（除 sign 外）按 key 升序排列，再拼成 key1=value1&key2=value2 格式
对每个 value 调用 rawurlencode()，不是 urlencode()（前者不转空格为 +，更可控）
排除 sign、timestamp（如果已由服务端校验过时效性）、nonce（若已存库去重）等非业务字段，避免客户端误传

怎么防重放？`timestamp` 和 `nonce` 怎么配合用？

光有签名只能防篡改，不能防重放。攻击者截获一次合法请求，稍作延迟重发，签名依然有效。

Laravel Cloud

Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。

下载

必须组合使用 timestamp 和 nonce：前者限制请求有效期（如 5 分钟），后者确保单次唯一。但 nonce 存哪、存多久，容易踩坑。

timestamp 必须是 UNIX 时间戳（秒级），服务端用 time() 对比，差值 > 300 秒直接拒绝
nonce 推荐用 16 字符以上随机字符串（Str::random(16)），不能是自增 ID 或毫秒时间 —— 后者易被预测
nonce 要存 Redis（带 TTL，比如 600 秒），写入前先 SETNX 判断是否已存在；不要存 MySQL，写入延迟高，压测时容易击穿
注意时钟漂移：如果客户端设备时间偏差大，timestamp 校验会频繁失败，建议前端首次请求时同步服务端时间并校准本地偏移

Laravel 中间件里怎么安全提取和验证签名？

别在控制器里写验签逻辑 —— 容易漏、难复用、测试成本高。必须抽成全局中间件，且要早于路由模型绑定和参数验证执行。

常见错误：在 app/Http/Controllers/Api/BaseController 里手动取 $request->header('X-Signature')，结果 POST JSON 请求头没传、或前端用 axios 自动加了 Content-Type: application/json 导致签名原文漏了 body 数据。

中间件应统一从 $request->query() 和 $request->except(['sign']) 拿参数，对 JSON 请求需先 $request->json()->all() 并合并到查询参数中（前提是约定 body 只传业务数据，不混杂 sign/timestamp）
签名字段名统一用 sign，不区分 header/query/body，降低客户端接入成本
验签失败直接 throw new HttpResponseException(response()->json(['message' => 'Invalid signature'], 401))，避免后续逻辑执行泄露信息
中间件里不要记录原始签名原文到日志 —— 可能含敏感参数，有合规风险

最麻烦的其实是跨语言对齐：PHP 的 hash_hmac 和 Python 的 hmac.new(key, msg, digestmod=sha256).hexdigest() 行为一致，但 JS 的 crypto.subtle.digest() 默认输出 ArrayBuffer，需要 Array.from() 转 hex —— 这类细节不写清楚，联调时能卡一整天。