HardenLabs.Hmac 1.1.0

HardenLabs.Hmac

Cross-language HMAC-SHA256 request signing with a defined canonical string format. Guaranteed identical signatures across C#, Python, TypeScript, and Go.

Installation

dotnet add package HardenLabs.Hmac
dotnet add package HardenLabs.Hmac.AspNetCore  # for middleware

Quick Start — Server (ASP.NET Core)

using HardenLabs.Hmac;
using HardenLabs.Hmac.AspNetCore;

var config = new HmacConfig
{
    SignedHeaders = SignedHeadersConfig.Default,
    TimestampToleranceSeconds = 30,
    Clients = new Dictionary<string, HmacClientIdentity>
    {
        ["order-service"] = new HmacClientIdentity { SharedSecret = "orders-base64-secret" },
        ["payment-service"] = new HmacClientIdentity { SharedSecret = "payments-base64-secret" },
    },
};

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHardenHmac(config);

var app = builder.Build();
app.UseRouting();
app.UseHardenHmac();

// Protected — requires valid HMAC signature
app.MapGet("/api/hello", () => Results.Ok(new { message = "Authenticated!" }))
    .WithMetadata(new HmacValidateAttribute());

// Unprotected — no attribute, no HMAC required
app.MapGet("/health", () => Results.Ok(new { status = "healthy" }));

app.Run();

Endpoints are not validated by default — use [HmacValidate] to opt in. Use [SkipHmacValidate] on actions to exempt them when the controller is protected.

Public API — Server

Quick Start — Client (HttpClient)

using HardenLabs.Hmac;
using HardenLabs.Hmac.AspNetCore;

var config = new HmacConfig
{
    SignedHeaders = SignedHeadersConfig.Default,
    Targets = new Dictionary<string, HmacTargetConfig>
    {
        ["order-service"] = new HmacTargetConfig
        {
            BaseUrl = "https://orders.example.com",
            SharedSecret = "orders-base64-secret",
        },
    },
};

var factory = new HardenHmacClientFactory(config);
var client = factory.CreateClient("order-service"); // BaseAddress + signing pre-configured
var response = await client.GetAsync("/api/hello");  // automatically signed

Configuration from appsettings.json

{
  "HardenHmac": {
    "TimestampToleranceSeconds": 30,
    "Clients": {
      "order-service": { "SharedSecret": "orders-base64-secret" }
    },
    "Targets": {
      "order-service": {
        "BaseUrl": "https://orders.example.com",
        "SharedSecret": "orders-base64-secret"
      }
    }
  }
}

builder.Services.AddHardenHmac(builder.Configuration.GetSection("HardenHmac"));

Documentation

Full documentation, canonical string specification, and cross-language compatibility details: github.com/HardenLabs/HardenHMAC

License

Apache License 2.0