目前,有关 HMAC 身份验证的文档存在严重误导性,因为它建议您只需在站点的管理部分中启用它即可。
发送信封时,您还需要在信封的 EventNotification 部分中设置“IncludeHMAC”设置。
此代码基于 C# DocuSign 客户端,但同样适用于其他语言。
public EventNotification BuildEventNotifications(string callbackUrl)
{
return new EventNotification
{
IncludeEnvelopeVoidReason = "true",
EnvelopeEvents = new List<EnvelopeEvent>
{
new EnvelopeEvent("sent", "false"),
new EnvelopeEvent("delivered", "false"), // When opened
new EnvelopeEvent("completed", "true"), // When signed
new EnvelopeEvent("declined", "false"),
new EnvelopeEvent("voided", "false")
},
Url = callbackUrl,
LoggingEnabled = "true",
IncludeHMAC = "true",
IncludeDocuments = "false",
RequireAcknowledgment = "true",
RecipientEvents = new List<RecipientEvent>
{
new RecipientEvent("false", "Sent"),
new RecipientEvent("false", "Delivered"),
new RecipientEvent("true", "Completed"),
new RecipientEvent("false", "Declined")
}
};
}
这是如何在 Api 端验证其 HMAC 签名的示例。 Web Api / .NET Core 中的示例,但应该很容易转换为 Java 或您选择的框架。
public class HMACAuthorization : Attribute, IAuthorizationFilter
{
public void OnAuthorization(AuthorizationFilterContext context)
{
string xmlBody;
context.HttpContext.Request.Body.Seek(0, SeekOrigin.Begin);
using (var reader = new StreamReader(context.HttpContext.Request.Body, Encoding.UTF8, true, 1024, true))
{
xmlBody = reader.ReadToEnd();
}
context.HttpContext.Request.Headers.TryGetValue("X-DocuSign-Signature-1", out var hmacSignature);
if (!HmacIsValid(ConfigurationSettings.DocuSignHMACKey, xmlBody, hmacSignature)) context.Result = new UnauthorizedResult();
}
private static bool HmacIsValid(string hmacKey, string body, string hmacSignature)
{
var computedHmac = BuildHmacHash(hmacKey, body);
var hmacIsValid = computedHmac == hmacSignature;
return hmacIsValid;
}
private static string BuildHmacHash(string hmacKey, string body)
{
string hash;
using (var sha = new HMACSHA256(Encoding.UTF8.GetBytes(hmacKey)))
{
hash = Convert.ToBase64String(sha.ComputeHash(Encoding.UTF8.GetBytes(body)));
}
return hash;
}
}
如果您使用 .NET Core / Web Api 中的示例,则需要在 Http 请求正文上启用倒带。您可以使用这个中间件来实现此功能。
public class EnableRequestRewindMiddleware
{
private readonly RequestDelegate _next;
public EnableRequestRewindMiddleware(RequestDelegate next)
{
_next = next;
}
public async Task Invoke(HttpContext context)
{
context.Request.EnableRewind();
await _next(context);
}
}
app.UseMiddleware<EnableRequestRewindMiddleware>();