Bitzsoft.HmacAuth 1.0.0

Bitzsoft.HmacAuth

HMAC-SHA256 第三方接口鉴权组件，为 ASP.NET Core API 提供安全、高效的签名认证。

功能特性

• HMAC-SHA256 签名生成与验证
• 请求载荷防篡改（HTTP 方法 + 路径 + 查询参数 + 请求头 + 请求体）
• Nonce 防重放攻击
• 密钥轮换（同一 AppKey 支持多密钥）
• 密钥派生（AWS SigV4 风格的两轮 HMAC 派生）
• 三种集成方式：Action Filter / AuthenticationHandler / Middleware
• 客户端自动签名 DelegatingHandler
• 密钥生命周期管理（ISecretManager）

快速开始

安装

dotnet add package Bitzsoft.HmacAuth

服务端 —— 注册服务

// 方式 1：使用配置文件
builder.Services.AddHmacAuth(builder.Configuration, "HmacAuth");

// 方式 2：使用字典
builder.Services.AddHmacAuth(new Dictionary<string, string>
{
    ["my-app-key"] = "my-secret-base64"
});

// 方式 3：自定义 ISecretStore
builder.Services.AddHmacAuth(options =>
{
    options.ExpirySeconds = 300;
    options.ValidatePayload = true;
    options.EnableKeyDerivation = true;
});

服务端 —— 鉴权集成

方式 1：Action Filter（MVC Controller）

[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    [HmacAuth]
    [HttpGet("profile")]
    public IActionResult GetProfile() => Ok();
}

方式 2：AuthenticationHandler（标准认证方案）

builder.Services.AddAuthentication()
    .AddHmac(builder.Configuration, "HmacAuth");

// 在 Controller 上使用 [Authorize]
[Authorize]
[ApiController]
public class ApiController : ControllerBase { }

方式 3：Middleware（Minimal API / 全局鉴权）

app.UseHmacAuth(options =>
{
    options.ExcludePaths.Add("/health");
    options.ExcludePaths.Add("/swagger*");
});

客户端 —— 自动签名

var handler = new HmacSigningHandler("my-app-key", "my-secret-base64");
var client = new HttpClient(handler);

// 所有请求自动添加 HMAC 鉴权头
var response = await client.GetAsync("https://api.example.com/users");

配置文件格式

{
  "HmacAuth": {
    "ExpirySeconds": 300,
    "ValidatePayload": true,
    "ValidateNonce": true,
    "EnableKeyDerivation": false,
    "MaxBodySize": 10485760,
    "SignedHeaders": [ "Content-Type" ],
    "Credentials": [
      {
        "AppKey": "app_abc123",
        "AppSecret": "c2VjcmV0LXZhbHVl",
        "Description": "Production key",
        "ExpiresAt": null
      }
    ]
  }
}

请求头说明

密钥管理

// 使用 ISecretManager 动态管理密钥
public class KeyManagementService
{
    private readonly ISecretManager _manager;

    public KeyManagementService(ISecretManager manager)
    {
        _manager = manager;
    }

    public void RotateKey(string appKey)
    {
        // 生成新密钥
        var newKey = HmacAuthManager.GenerateAppSecret();
        _manager.Add(appKey, newKey, "Rotated key");
        // 旧密钥继续有效，直到被禁用
    }
}

错误码

License

MIT