Skip to content

Commit 77420eb

Browse files
authored
feat: Cryptographic agility support (#187)
1 parent 7805c90 commit 77420eb

13 files changed

Lines changed: 583 additions & 22 deletions

‎.mockery.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,5 @@ packages:
1010
interfaces:
1111
NonceGetter: {}
1212
KeyResolver: {}
13+
MessageSigner: {}
14+
MessageVerifier: {}

‎README.md‎

Lines changed: 143 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,17 @@
44

55
## Introduction and Scope
66

7-
`httpsig` is a library for signing and verifying HTTP requests and responses according to [RFC 9421 (HTTP Message Signatures)](https://www.rfc-editor.org/rfc/rfc9421.html). It combines reusable signing and verification policies with support for application-specific signature requirements and signature negotiation using `Accept-Signature`.
7+
`httpsig` is a library for signing and verifying HTTP requests and responses according to [RFC 9421 (HTTP Message Signatures)](https://www.rfc-editor.org/rfc/rfc9421.html).
88

9-
The `Message` abstraction keeps these capabilities independent of any particular HTTP framework. For API details and option semantics, see the [Go reference](https://pkg.go.dev/github.com/dadrus/httpsig).
9+
Its key features include:
10+
11+
- **Policy-based signing and verification:** Reusable policies for covered components, signature parameters, tags, and validity constraints.
12+
- **Message integrity:** Automatic generation and verification of `Content-Digest` to protect HTTP message bodies.
13+
- **Signature negotiation:** Support for requesting signatures via `Accept-Signature` and deriving signature requirements from verification policies.
14+
- **Framework independence:** A `Message` abstraction that enables integration with `net/http`, Fiber, other HTTP frameworks, and proxy-based services.
15+
- **Cryptographic agility:** Support for custom signing and verification implementations, allowing applications to use cryptographic algorithms and key management systems (HSMs and KMSs) independently of the library's built-in support (see [Cryptographic Agility](#cryptographic-agility)).
16+
17+
For API details and option semantics, see the [Go reference](https://pkg.go.dev/github.com/dadrus/httpsig). For known limitations and the current scope of RFC 9421 support, see [Limitations and Compliance](#limitations-and-compliance).
1018

1119
## Usage
1220

@@ -264,6 +272,125 @@ For automatic negotiation, the configured `NonceGetter` runs while `Verify` prep
264272

265273
A `Signer` or `Verifier` represents a reusable signing or verification policy. Create an instance once per policy and reuse it across messages. This allows most of the configuration work to happen upfront, keeping the per-message overhead low. Message-specific values can be supplied through per-call options.
266274

275+
## Cryptographic Agility
276+
277+
`httpsig` supports custom signing and verification implementations through the `MessageSigner` and `MessageVerifier` interfaces. This allows applications to use cryptographic algorithms (e.g., PQC) and key management systems (HSMs and KMSs) independently of the library's built-in support.
278+
279+
The library constructs the [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html) signature base and passes it unchanged to the application-provided implementation, which is responsible for the entire cryptographic operation, including hashing and signature encoding.
280+
281+
### ML-DSA
282+
283+
The following example demonstrates how to use ML-DSA, available in the Go standard library since Go 1.27, without requiring `httpsig` itself to target that Go version.
284+
285+
First, define adapters for signing and verification:
286+
287+
```go
288+
type mlDSASigner mldsa.PrivateKey
289+
290+
func (s *mlDSASigner) SignMessage(_ context.Context, message []byte) ([]byte, error) {
291+
return (*mldsa.PrivateKey)(s).Sign(nil, message, &mldsa.Options{})
292+
}
293+
294+
type mlDSAVerifier mldsa.PublicKey
295+
296+
func (v *mlDSAVerifier) VerifyMessage(_ context.Context, message, signature []byte) error {
297+
return mldsa.Verify((*mldsa.PublicKey)(v), message, signature, &mldsa.Options{})
298+
}
299+
```
300+
301+
These adapters can then be used directly with the existing signing and verification APIs:
302+
303+
```go
304+
// Generate an ML-DSA key pair.
305+
privateKey, err := mldsa.GenerateKey(mldsa.MLDSA44())
306+
// error handling
307+
308+
// Create a signer.
309+
signer, err := httpsig.NewSigner(
310+
httpsig.Key{
311+
Material: (*mlDSASigner)(privateKey),
312+
Algorithm: "ml-dsa-44",
313+
},
314+
httpsig.WithKeyID("demo-ml-dsa-44"),
315+
httpsig.WithAlg(),
316+
httpsig.WithComponents("@method", "@path"),
317+
)
318+
// error handling
319+
320+
req, err := ... // create the request
321+
322+
// Sign the request.
323+
req.Header, err = signer.Sign(httpsig.MessageFromRequest(req))
324+
// error handling
325+
326+
// Create a verifier.
327+
verifier, err := httpsig.NewVerifier(
328+
httpsig.Key{
329+
Material: (*mlDSAVerifier)(privateKey.PublicKey()),
330+
Algorithm: "ml-dsa-44",
331+
},
332+
httpsig.WithValidateAllSignatures(),
333+
httpsig.WithComponents("@method", "@path"),
334+
)
335+
// error handling
336+
337+
// Verify the request.
338+
result, err := verifier.Verify(httpsig.MessageFromRequest(req))
339+
// error handling
340+
```
341+
342+
### AWS KMS
343+
344+
The same approach works with external key management systems such as AWS KMS. The application-provided adapter handles the KMS interaction and any required cryptographic processing.
345+
346+
For example, an ECDSA signer backed by AWS KMS could look like this:
347+
348+
```go
349+
type awsMessageSigner struct {
350+
client *kms.Client
351+
keyID string
352+
}
353+
354+
func (s awsMessageSigner) SignMessage(ctx context.Context, message []byte) ([]byte, error) {
355+
digest := sha256.Sum256(message)
356+
357+
response, err := s.client.Sign(ctx, &kms.SignInput{
358+
KeyId: &s.keyID,
359+
Message: digest[:],
360+
MessageType: types.MessageTypeDigest,
361+
SigningAlgorithm: types.SigningAlgorithmSpecEcdsaSha256,
362+
})
363+
if err != nil {
364+
return nil, err
365+
}
366+
367+
// Convert the ASN.1 DER-encoded ECDSA signature returned by AWS KMS to r || s.
368+
return ecdsaSignatureToRaw(response.Signature)
369+
}
370+
```
371+
372+
The adapter can then be passed to `httpsig` like any other signing key:
373+
374+
```go
375+
client := ... // create the AWS KMS client
376+
keyID := ... // obtain the key ID
377+
378+
signer, err := httpsig.NewSigner(
379+
httpsig.Key{
380+
Material: awsMessageSigner{client: client, keyID: keyID},
381+
Algorithm: httpsig.EcdsaP256Sha256,
382+
},
383+
httpsig.WithKeyID(keyID),
384+
httpsig.WithComponents("@method", "@path"),
385+
)
386+
// error handling
387+
388+
req, err := ... // create the request
389+
390+
req.Header, err = signer.Sign(httpsig.MessageFromRequest(req))
391+
// error handling
392+
```
393+
267394
## Protocols and Profiles
268395

269396
### WIMSE Workload-to-Workload HTTP Signatures
@@ -474,4 +601,17 @@ app.Use(func(c fiber.Ctx) error {
474601
* **Replay:** Enforce the required nonce checks after successful signature verification.
475602
* **Multiple signatures:** Labels are not signed, and `VerificationResult` has no defined order. Choose the required tags or validate all signatures as appropriate.
476603

477-
See [RFC 9421 Security Considerations](https://www.rfc-editor.org/rfc/rfc9421.html#section-7).
604+
See also [RFC 9421 Security Considerations](https://www.rfc-editor.org/rfc/rfc9421.html#section-7).
605+
606+
## Limitations and Compliance
607+
608+
### RFC 9421 Compliance
609+
610+
Following are the known limitations and deviations:
611+
612+
- **HTTP trailers:** The `;tr` component identifier parameter is not supported. `Signature` and `Signature-Input` fields cannot be processed as trailers.
613+
- **Signature negotiation:** Generating `Accept-Signature` is supported, but parsing received `Accept-Signature` fields is not yet implemented.
614+
615+
### Other Limitations
616+
617+
- **Body streaming:** `Content-Digest` generation and verification currently require buffering the complete message body in memory. Streaming digest calculation is not yet supported.

‎httpsig.go‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,10 @@ const (
103103
)
104104

105105
// SignatureAlgorithm identifies the concrete cryptographic algorithm used
106-
// to create or verify an HTTP message signature. The supported algorithms
107-
// are the constants below; the selected algorithm must be compatible with
108-
// the supplied Key.Material.
106+
// to create or verify an HTTP message signature. The constants below are
107+
// supported by the built-in implementations. Other algorithms can be used
108+
// with an application-provided MessageSigner or MessageVerifier. The selected
109+
// algorithm must be compatible with the supplied Key.Material.
109110
type SignatureAlgorithm string
110111

111112
const (
@@ -239,17 +240,36 @@ func (p SignatureParameters) Tag() (string, bool) {
239240
// strings when validating profile-specific signature parameters.
240241
type Token string
241242

243+
// MessageSigner signs the complete HTTP signature base using an
244+
// application-provided implementation. The implementation is responsible for
245+
// all cryptographic processing and must return signature bytes in the format
246+
// required by the selected HTTP Message Signatures algorithm.
247+
// Context is supplied by the message being signed.
248+
type MessageSigner interface {
249+
SignMessage(ctx context.Context, message []byte) ([]byte, error)
250+
}
251+
252+
// MessageVerifier verifies the complete HTTP signature base using an
253+
// application-provided implementation. The signature bytes are passed through
254+
// unchanged; the implementation is responsible for the algorithm and encoding.
255+
// Context is supplied by the message being verified.
256+
type MessageVerifier interface {
257+
VerifyMessage(ctx context.Context, message, signature []byte) error
258+
}
259+
242260
// Key combines cryptographic key material with the concrete signature
243-
// algorithm to use. Signing requires private or symmetric key material;
244-
// verification requires public or symmetric key material.
261+
// algorithm to use. Signing requires private or symmetric key material (or
262+
// a signer interface); verification requires public or symmetric key material
263+
// (or a verifier interface).
245264
type Key struct {
246265
// Algorithm is the signature algorithm to use with Material.
247266
// It must be compatible with the supplied key material.
248267
Algorithm SignatureAlgorithm
249268

250269
// Material is the private, public, or symmetric key material used by the
251-
// chosen algorithm. The currently supported implementations accept the
252-
// corresponding Go crypto key types or []byte for HMAC.
270+
// chosen algorithm. The built-in implementations accept the
271+
// corresponding Go crypto key types or []byte for HMAC. Applications
272+
// may also provide a MessageSigner or MessageVerifier implementation.
253273
Material any
254274
}
255275

‎mock_message_signer_test.go‎

Lines changed: 115 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)