.NET Framework 4.6.2 WebAPI中DocuSign Webhook HMAC验证失败求助

核心排查点 #

• 请求流读取异常：ASP.NET Web API 4.x默认会在模型绑定阶段读取请求输入流，未开启请求缓冲的情况下，即使手动重置InputStream.Position也无法获取完整原始请求体。需在WebApiConfig中全局开启请求流缓存：

config.Services.Replace(typeof(IHostBufferPolicySelector), new WebHostBufferPolicySelector { UseBufferedInputStream = true });

• 转码偏差：当前实现先将请求体转为字符串再计算哈希，字符串编码、BOM头处理、换行符自动转换等操作都会导致最终参与哈希计算的内容和DocuSign侧原始内容不一致，建议直接基于原始字节流计算哈希，跳过字符串转码步骤。
• 密钥配置错误：检查docuSignHMACSecretKey是否和DocuSign后台配置的密钥完全一致，不要包含多余的空格、换行符，不要混用测试环境与生产环境的密钥。
• 签名头取值异常：检查X-DocuSign-Signature-1头的取值是否为纯Base64格式，没有多余的前缀、后缀或空格。
• Payload内容差异：将读取到的请求体内容和DocuSign后台的请求日志做逐字符对比，确认不存在换行符、空格、转义字符的差异。

修复后参考代码 #

private bool ValidateHMAC()
{
    // 读取签名头
    if (!Request.Headers.Contains("X-DocuSign-Signature-1"))
        return false;
    string hmacSignature1 = Request.Headers.GetValues("X-DocuSign-Signature-1").First().Trim();

    // 直接读取原始请求字节流，避免转码偏差
    byte[] payloadBytes;
    var inputStream = HttpContext.Current.Request.InputStream;
    inputStream.Position = 0;
    using (var ms = new MemoryStream())
    {
        inputStream.CopyTo(ms);
        payloadBytes = ms.ToArray();
    }

    return HashIsValid(payloadBytes, hmacSignature1);
}

private string ComputeHash(byte[] payloadBytes)
{
    string docuSignHMACSecretKey = "KXXXXKXXKXKXKXXXX-FFDocuSignHMACKey";
    byte[] keyBytes = Encoding.UTF8.GetBytes(docuSignHMACSecretKey);
    using (var hmac = new System.Security.Cryptography.HMACSHA256(keyBytes))
    {
        byte[] hashBytes = hmac.ComputeHash(payloadBytes);
        return Convert.ToBase64String(hashBytes);
    }
}

private bool HashIsValid(byte[] payloadBytes, string verifySignature)
{
    string computedHash = ComputeHash(payloadBytes);
    // 固定序数比较避免大小写、文化差异带来的匹配失败
    return computedHash.Equals(verifySignature, StringComparison.Ordinal);
}

额外优化建议 #

• 替换普通字符串比较为恒定时间比较，避免时序攻击漏洞，.NET Framework 4.6.2可自行实现逐字节固定时间比较逻辑，避免泄露哈希差异相关的时序信息。
• 增加签名过期校验，避免重放攻击。
• 增加异常捕获逻辑，处理请求流读取、哈希计算过程中的异常情况。

内容的提问来源于stack exchange，提问作者Shyam Vashista