DamianH.Http.HttpSignatures 0.1.0

DamianH.Http.HttpSignatures

RFC 9421 HTTP Message Signatures for signing and verifying HTTP messages.

Depends on DamianH.Http.StructuredFieldValues (pulled in automatically as a transitive dependency).

Table of Contents

• Installation
• Quick Start
• Supported Algorithms
• API Reference
  • HttpMessageSigner
  • HttpMessageVerifier
  • SignatureParameters
  • ComponentIdentifier
  • IHttpMessageContext
  • SignatureResult
  • VerificationResult
• Key Types
• Runtime Resolution

Installation

dotnet add package DamianH.Http.HttpSignatures

Quick Start

The following example shows a complete sign-then-verify round-trip using HMAC-SHA256 (symmetric — the same key is used for both operations):

using DamianH.Http.HttpSignatures;
using DamianH.Http.HttpSignatures.Algorithms;
using DamianH.Http.HttpSignatures.Keys;

// --- Signing ---

var signingKey = new HmacSharedKey("my-key-id", Encoding.UTF8.GetBytes("super-secret"));
var algorithm = new HmacSha256SignatureAlgorithm();
var signer = new HttpMessageSigner();

var parameters = new SignatureParameters([
    ComponentIdentifier.Method,
    ComponentIdentifier.Authority,
    ComponentIdentifier.Path,
    ComponentIdentifier.Field("content-type"),
])
{
    Created = DateTimeOffset.UtcNow,
    KeyId = signingKey.KeyId,
    Algorithm = algorithm.AlgorithmName,
};

// context adapts your HTTP message (see IHttpMessageContext)
SignatureResult result = signer.Sign("sig1", context, parameters, signingKey, algorithm);

// Add the headers to the outgoing request
request.Headers.Add("Signature-Input", result.SignatureInputHeaderValue);
request.Headers.Add("Signature", result.SignatureHeaderValue);

// --- Verification ---

var verificationKey = signingKey.AsVerificationKey();
var verifier = new HttpMessageVerifier();

VerificationResult verification = verifier.Verify("sig1", context, verificationKey, algorithm);

if (!verification.IsValid)
{
    Console.WriteLine($"Signature invalid: {verification.ErrorMessage}");
}

Supported Algorithms

API Reference

HttpMessageSigner

Signs an HTTP message, producing Signature-Input and Signature header values.

public sealed class HttpMessageSigner
{
    public SignatureResult Sign(
        string label,
        IHttpMessageContext context,
        SignatureParameters parameters,
        SigningKey key,
        ISignatureAlgorithm algorithm);
}

HttpMessageVerifier

Verifies an HTTP message signature, either with explicit key/algorithm or via runtime resolution.

public sealed class HttpMessageVerifier
{
    // Explicit key and algorithm
    public VerificationResult Verify(
        string label,
        IHttpMessageContext context,
        VerificationKey key,
        ISignatureAlgorithm algorithm);

    // Runtime key and algorithm resolution
    public Task<VerificationResult> VerifyAsync(
        string label,
        IHttpMessageContext context,
        IKeyResolver keyResolver,
        ISignatureAlgorithmRegistry algorithmRegistry,
        CancellationToken cancellationToken = default);
}

SignatureParameters

Defines the covered components and metadata for a signature. Covered components determine which parts of the HTTP message are included in the signature base.

var parameters = new SignatureParameters([
    ComponentIdentifier.Method,
    ComponentIdentifier.Authority,
    ComponentIdentifier.Path,
])
{
    Created  = DateTimeOffset.UtcNow,       // ;created=<unix timestamp>
    Expires  = DateTimeOffset.UtcNow.AddMinutes(5), // ;expires=<unix timestamp>
    KeyId    = "my-key-id",                 // ;keyid="..."
    Nonce    = Guid.NewGuid().ToString(),   // ;nonce="..."
    Algorithm = "hmac-sha256",              // ;alg="..."
    Tag      = "my-app",                    // ;tag="..."
};

All properties except CoveredComponents are optional. Omitting Created/Expires means no time-bound validation.

ComponentIdentifier

Identifies a component of the HTTP message to include in the signature base.

Derived components (start with @):

HTTP field components:

IHttpMessageContext

Adapts a concrete HTTP message to the interface required by HttpMessageSigner and HttpMessageVerifier. You implement this for your specific HTTP framework.

public interface IHttpMessageContext
{
    bool IsRequest { get; }
    string? Method { get; }
    string? Scheme { get; }
    string? Authority { get; }
    string? Path { get; }
    string? Query { get; }
    string? TargetUri { get; }
    string? RequestTarget { get; }
    int? StatusCode { get; }
    string? GetHeaderValue(string fieldName);
    IReadOnlyList<string> GetHeaderValues(string fieldName);
    IHttpMessageContext? AssociatedRequest { get; }
}

SignatureResult

Returned by HttpMessageSigner.Sign. Contains the values to set on the outgoing HTTP message headers.

VerificationResult

Returned by HttpMessageVerifier.Verify / VerifyAsync.

Key Types

Signing Keys

Verification Keys

All key types carry a KeyId (used in the keyid signature parameter) and an optional AlgorithmHint.

Runtime Resolution

For server-side verification where the key and algorithm are not known in advance, implement IKeyResolver and use SignatureAlgorithmRegistry:

// Implement key resolution from your keystore
public class MyKeyResolver : IKeyResolver
{
    public Task<VerificationKey?> ResolveKeyAsync(string keyId, CancellationToken ct = default)
    {
        // look up key by keyId
        var key = _store.Find(keyId);
        return Task.FromResult<VerificationKey?>(key);
    }
}

// Register the algorithms you accept
var registry = new SignatureAlgorithmRegistry();
registry.Register(new HmacSha256SignatureAlgorithm());
registry.Register(new EcdsaP256Sha256SignatureAlgorithm());

// Verify — algorithm and key are resolved from the Signature-Input header
var verifier = new HttpMessageVerifier();
var result = await verifier.VerifyAsync("sig1", context, new MyKeyResolver(), registry);

The alg and keyid parameters must be present in the Signature-Input header when using VerifyAsync.