|
4 | 4 |
|
5 | 5 | ## Introduction and Scope |
6 | 6 |
|
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). |
8 | 8 |
|
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). |
10 | 18 |
|
11 | 19 | ## Usage |
12 | 20 |
|
@@ -264,6 +272,125 @@ For automatic negotiation, the configured `NonceGetter` runs while `Verify` prep |
264 | 272 |
|
265 | 273 | 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. |
266 | 274 |
|
| 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 | + |
267 | 394 | ## Protocols and Profiles |
268 | 395 |
|
269 | 396 | ### WIMSE Workload-to-Workload HTTP Signatures |
@@ -474,4 +601,17 @@ app.Use(func(c fiber.Ctx) error { |
474 | 601 | * **Replay:** Enforce the required nonce checks after successful signature verification. |
475 | 602 | * **Multiple signatures:** Labels are not signed, and `VerificationResult` has no defined order. Choose the required tags or validate all signatures as appropriate. |
476 | 603 |
|
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. |
0 commit comments