HTTP Signatures overview
DamianH.Http.HttpSignatures provides RFC 9421 HTTP Message Signatures for
signing and verifying HTTP messages.
Depends on
DamianH.Http.StructuredFieldValues(pulled in automatically as a transitive dependency).
Installation
Run in the consuming project directory:
dotnet add package DamianH.Http.HttpSignaturesRepository builds reference the local Structured Field Values project, so both libraries use the same object model. NuGet packaging records that project's computed version as a dependency. For coordinated releases, publish the matching Structured Field Values package before HttpSignatures, from the same source commit.
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):
The hard-coded secret is illustrative, not a production key. Supply securely provisioned key material in an application.
contextadapts your message throughIHttpMessageContext; verification must see the message with its signature headers attached.IsValidis protocol and cryptographic verification, not application acceptance or authorization. Use verification policy to enforce application requirements and read the security boundaries.
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 signingCredentials = new SigningCredentials(signingKey, algorithm);
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, signingCredentials);
// 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 verificationCredentials = new VerificationCredentials(verificationKey, algorithm);
var verifier = new HttpMessageVerifier();
VerificationResult verification = verifier.Verify("sig1", context, verificationCredentials);
if (!verification.IsValid)
{
Console.WriteLine($"Signature invalid: {verification.ErrorMessage}");
}The example uses Encoding from System.Text.
Supported Algorithms
| Class | Algorithm Name | RFC Section | Key Types | Status |
|---|---|---|---|---|
HmacSha256SignatureAlgorithm |
hmac-sha256 |
§3.3.3 | HmacSharedKey / HmacSharedVerificationKey |
✅ Supported |
EcdsaP256Sha256SignatureAlgorithm |
ecdsa-p256-sha256 |
§3.3.4 | EcdsaSigningKey / EcdsaVerificationKey |
✅ Supported |
EcdsaP384Sha384SignatureAlgorithm |
ecdsa-p384-sha384 |
§3.3.5 | EcdsaSigningKey / EcdsaVerificationKey |
✅ Supported |
RsaPssSha512SignatureAlgorithm |
rsa-pss-sha512 |
§3.3.1 | RsaSigningKey / RsaVerificationKey |
✅ Supported |
RsaPkcs1Sha256SignatureAlgorithm |
rsa-v1_5-sha256 |
§3.3.2 | RsaSigningKey / RsaVerificationKey |
✅ Supported |
Ed25519SignatureAlgorithm |
ed25519 |
§3.3.6 | Ed25519SigningKey / Ed25519VerificationKey |
⚠️ Stub — throws PlatformNotSupportedException (awaiting .NET runtime support) |
See credentials and key types for trusted algorithm binding, ownership, and runtime resolution, and the API reference for message and field adapters.