.NET Core如何安全验证腾讯云新版云端录制回调签名？

Question

在使用腾讯云新版云端录制（Cloud Recording）服务时，回调 URL 收到的 `callback` 请求需验证其 `X-TX-Signature` 和 `X-TX-Timestamp` 头以防止伪造或重放攻击。常见问题是：开发者直接拼接请求体与密钥进行 HMAC-SHA256 计算，却忽略了腾讯云实际要求的签名算法细节——即**必须对原始请求体（raw body，非 JSON 反序列化后字符串）、时间戳（秒级整数）、HTTP 方法（全大写）、路径（不含 query string）及固定前缀 `txcloud_recording_callback_` 按指定顺序拼接后计算摘要**。此外，.NET Core 中若未正确读取不可重复的 `Request.Body`（如未启用 `AllowSynchronousIO` 或未 `Rewind` 流），会导致签名验签失败；同时未校验时间戳有效期（建议 ≤ 300 秒）和 `X-TX-Timestamp` 是否为合法 Unix 时间，亦构成安全风险。如何在 ASP.NET Core 中安全、高效、可测试地实现该验签逻辑？

Answer 1

```html

一、问题本质剖析：为何“简单 HMAC”必然失败？

腾讯云新版 Cloud Recording 回调签名不是标准 Webhook 签名（如 GitHub 的 X-Hub-Signature-256），而是严格定义的五元组拼接签名：固定前缀 + 原始请求体（raw bytes） + 秒级时间戳（string） + 大写 HTTP 方法 + 路径（无 query）。开发者常犯三大致命错误：

• ❌ 将 HttpContext.Request.Body 直接反序列化为 object 后再 JsonSerializer.Serialize() —— JSON 序列化会丢失空格、换行、字段顺序、null 处理，与原始 body 字节不等价；
• ❌ 忽略 Request.Body 是只读一次流（non-seekable by default），未 Rewind() 或启用 AllowSynchronousIO（已弃用但需兼容旧版）；
• ❌ 仅校验签名，未做时间漂移防御（如 Math.Abs(now - timestamp) > 300）或 Unix 时间合法性（timestamp < 0 || timestamp > DateTimeOffset.UtcNow.AddHours(1).ToUnixTimeSeconds()）。

二、签名算法规范：腾讯云官方要求的字节级拼接规则

按如下**严格顺序**拼接 UTF-8 编码字节数组（注意：非字符串拼接！需统一编码后 concat）：

1. "txcloud_recording_callback_"（固定 ASCII 前缀，12 字节）
2. 原始请求体字节（byte[]，不可经任何 JSON 解析/重序列化）
3. 时间戳字符串（timestamp.ToString("D")，如 "1717023456"）
4. HTTP 方法大写（context.Request.Method.ToUpperInvariant()）
5. 路径（context.Request.Path，不含 QueryString，如 "/webhook"）

最终对拼接后的 byte[] 计算 HMACSHA256(keyBytes)，Base64 编码结果即为期望签名。

三、.NET Core 安全实现关键：流复用与同步控制

必须启用请求体缓冲并支持多次读取：

// 在 Program.cs / Startup.cs 中全局配置
builder.Services.Configure<KestrelServerOptions>(options =>
{
    options.AllowSynchronousIO = true; // ⚠️ 仅用于调试/兼容，生产推荐异步 Rewind
});
// 更优实践：在中间件中显式 EnableBuffering()
app.Use(async (context, next) =>
{
    context.Request.EnableBuffering(); // 支持多次读取 Body
    await next();
});

四、可测试、可注入的验签服务设计

组件	职责	可测试性保障
IRecordingSignatureValidator	核心验签契约，含 ValidateAsync(HttpContext, string appSecret)	接口抽象，便于 Moq 模拟 HttpContext
TxCloudSignatureAlgorithm	纯函数式拼接逻辑，接收 byte[] body, long timestamp, string method, string path	无依赖、无状态、单元测试覆盖率可达 100%

五、完整中间件实现（含防御性校验）

public class TencentCloudRecordingSignatureMiddleware
{
    private readonly RequestDelegate _next;
    private readonly string _appSecret;

    public TencentCloudRecordingSignatureMiddleware(RequestDelegate next, IConfiguration config)
    {
        _next = next;
        _appSecret = config["TencentCloud:AppSecret"] ?? throw new InvalidOperationException("AppSecret missing");
    }

    public async Task InvokeAsync(HttpContext context)
    {
        if (!context.Request.Path.Equals("/webhook", StringComparison.Ordinal))
        {
            await _next(context);
            return;
        }

        var timestampHeader = context.Request.Headers["X-TX-Timestamp"].FirstOrDefault();
        var signatureHeader = context.Request.Headers["X-TX-Signature"].FirstOrDefault();

        if (string.IsNullOrEmpty(timestampHeader) || string.IsNullOrEmpty(signatureHeader))
        {
            context.Response.StatusCode = StatusCodes.Status401Unauthorized;
            await context.Response.WriteAsync("Missing X-TX-Timestamp or X-TX-Signature");
            return;
        }

        if (!long.TryParse(timestampHeader, out var timestamp) || timestamp < 0)
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            await context.Response.WriteAsync("Invalid X-TX-Timestamp format");
            return;
        }

        var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        if (Math.Abs(now - timestamp) > 300) // 5 分钟有效期
        {
            context.Response.StatusCode = StatusCodes.Status401Unauthorized;
            await context.Response.WriteAsync("X-TX-Timestamp expired");
            return;
        }

        context.Request.EnableBuffering();
        using var reader = new StreamReader(context.Request.Body, Encoding.UTF8, detectEncodingFromByteOrderMarks: false, bufferSize: 4096, leaveOpen: true);
        var rawBody = await reader.ReadToEndAsync();
        context.Request.Body.Position = 0; // Rewind for downstream consumers (e.g., model binding)

        var computedSig = new TxCloudSignatureAlgorithm().Compute(
            bodyBytes: Encoding.UTF8.GetBytes(rawBody),
            timestamp: timestamp,
            httpMethod: context.Request.Method.ToUpperInvariant(),
            path: context.Request.Path.ToString(),
            secretKey: _appSecret);

        if (!CryptographicOperations.FixedTimeEquals(
                Convert.FromBase64String(signatureHeader),
                Convert.FromBase64String(computedSig)))
        {
            context.Response.StatusCode = StatusCodes.Status401Unauthorized;
            await context.Response.WriteAsync("Invalid X-TX-Signature");
            return;
        }

        await _next(context);
    }
}

六、单元测试验证场景（xUnit + Moq）

覆盖以下边界用例：

• ✅ 正确签名 + 有效时间戳（±10s 内）
• ✅ Body 含 Unicode、换行、多余空格（验证原始字节一致性）
• ❌ 时间戳超时（+305s）
• ❌ 路径含 query string（应被截断）
• ❌ HTTP 方法小写（必须转大写）
• ❌ 签名 Base64 解码失败

七、安全增强建议（生产环境必启）

1. 使用 CryptographicOperations.FixedTimeEquals() 防侧信道攻击（而非 ==）；
2. AppSecret 存于 Azure Key Vault / Tencent Cloud KMS，禁止硬编码；
3. 记录验签失败日志（含 IP、User-Agent、时间戳偏差），接入 SIEM；
4. 对高频失败 IP 自动限流（集成 AspNetCoreRateLimit）；
5. 定期轮换 AppSecret 并双写灰度验证。

八、流程图：验签全生命周期

flowchart TD
    A[收到回调请求] --> B{路径匹配?}
    B -- 否 --> C[放行至下游]
    B -- 是 --> D[解析 X-TX-Timestamp]
    D --> E{格式合法且 Unix 时间?}
    E -- 否 --> F[400 Bad Request]
    E -- 是 --> G{时间偏差 ≤300s?}
    G -- 否 --> H[401 Unauthorized]
    G -- 是 --> I[EnableBuffering + Read Raw Body]
    I --> J[按五元组拼接字节]
    J --> K[HMAC-SHA256 + Base64]
    K --> L{FixedTimeEquals?}
    L -- 否 --> M[401 Unauthorized]
    L -- 是 --> N[放行至 Controller]

九、性能与可观测性优化点

在高并发场景下：

• ✅ 使用 Span<byte> 和 stackalloc 减少 GC 压力（拼接阶段）；
• ✅ 预编译 HMACSHA256 实例（new HMACSHA256(keyBytes) 可缓存）；
• ✅ 添加 ActivitySource 埋点，追踪验签耗时、失败率；
• ✅ Prometheus 指标暴露：tencent_cloud_recording_signature_validate_total{result="success|failed"}。

十、迁移与兼容性说明

若项目已使用旧版云端录制（v1）或第三方 SDK，需注意：

• 旧版签名仅含 body + timestamp，无 method/path/前缀，不可混用；
• 腾讯云控制台中「回调配置」必须勾选「启用签名验证」，否则不会发送 X-TX-Signature；
• 本地开发调试时，可用 curl -H "X-TX-Timestamp: $(date +%s)" -H "X-TX-Signature: ..." ... 手动生成签名验证链路；
• .NET 6+ 推荐禁用 AllowSynchronousIO，全程使用 Stream.ReadAsync + MemoryStream 缓冲。

```