Skip to content

Commit 1b91c47

Browse files
committed
trim down README
1 parent 2b5fa25 commit 1b91c47

File tree

1 file changed

+4
-132
lines changed

1 file changed

+4
-132
lines changed

README.md

Lines changed: 4 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -309,51 +309,6 @@ func ExampleNewClient() {
309309
source: [http/http_example_test.go](https://github.com/lestrrat-go/htmsig/blob/main/http/http_example_test.go)
310310
<!-- END INCLUDE -->
311311

312-
## Components
313-
314-
### Core Package (`htmsig`)
315-
316-
The main package provides low-level signing and verification functions:
317-
318-
- `SignRequest(ctx, headers, inputValue, key)` - Sign HTTP requests
319-
- `SignResponse(ctx, headers, inputValue, key)` - Sign HTTP responses
320-
- `VerifyRequest(ctx, headers, keyOrResolver)` - Verify HTTP requests
321-
- `VerifyResponse(ctx, headers, keyOrResolver)` - Verify HTTP responses
322-
323-
### HTTP Package (`htmsig/http`)
324-
325-
High-level HTTP integration with handlers, middleware, and clients:
326-
327-
- **Server Components**:
328-
- `Verifier` - Middleware for verifying incoming signatures
329-
- `ResponseSigner` - Middleware for signing outgoing responses
330-
- `Wrap()` - Combine verification and signing around handlers
331-
332-
- **Client Components**:
333-
- `SigningTransport` - HTTP transport that signs requests
334-
- `NewClient()` - Create HTTP client with automatic signing
335-
336-
- **Key Resolution**:
337-
- `StaticKeyResolver` - Single key for all signatures
338-
- `MapKeyResolver` - Map-based key lookup
339-
- `KeyResolverFunc` - Custom key resolution function
340-
341-
### Component Package (`htmsig/component`)
342-
343-
Define which parts of HTTP messages to include in signatures:
344-
345-
- **Derived Components**: `@method`, `@target-uri`, `@authority`, `@scheme`, `@request-target`, `@path`, `@query`, `@status`
346-
- **HTTP Fields**: Any HTTP header (e.g., `content-type`, `date`, `authorization`)
347-
- **Structured Fields**: Support for structured field parsing
348-
349-
### Input Package (`htmsig/input`)
350-
351-
Build signature input specifications:
352-
353-
- `DefinitionBuilder` - Create signature definitions
354-
- `ValueBuilder` - Combine multiple signature definitions
355-
- Support for all RFC 9421 parameters: `created`, `expires`, `keyid`, `alg`, `nonce`, `tag`
356-
357312
## Supported Algorithms
358313

359314
| Algorithm | RFC 9421 Name | Description |
@@ -369,94 +324,11 @@ Build signature input specifications:
369324

370325
### Custom Component Selection
371326

372-
```go
373-
// Sign specific headers and derived components
374-
def, _ := input.NewDefinitionBuilder().
375-
Components(
376-
component.Method(), // @method
377-
component.TargetURI(), // @target-uri
378-
component.New("authorization"), // authorization header
379-
component.New("content-digest"), // content-digest header
380-
component.New("date"), // date header
381-
).
382-
Created(time.Now().Unix()). // Add creation timestamp
383-
Expires(time.Now().Add(time.Hour).Unix()). // Add expiration
384-
Build()
385-
```
386-
387-
### Key Resolution with Multiple Keys
388-
389-
```go
390-
keyResolver := &htmsighttp.MapKeyResolver{
391-
Keys: map[string]any{
392-
"rsa-key-2021": rsaPublicKey,
393-
"ecdsa-key-2022": ecdsaPublicKey,
394-
"hmac-secret": []byte("shared-secret"),
395-
},
396-
}
397-
398-
verifier := htmsighttp.NewVerifier(keyResolver)
399-
```
400-
401-
### Response Signing
402-
403-
```go
404-
// Sign HTTP responses
405-
signer := htmsighttp.NewResponseSigner(privateKey, "response-key",
406-
htmsighttp.WithSignerComponents(
407-
component.Status(), // @status
408-
component.New("content-type"), // content-type header
409-
component.New("content-length"), // content-length header
410-
),
411-
)
412-
413-
handler := htmsighttp.Wrap(appHandler, htmsighttp.WithSigner(signer))
414-
```
415-
416-
### Error Handling and Configuration
327+
You can specify exactly which parts of the HTTP message to include in signatures:
417328

418-
```go
419-
verifier := htmsighttp.NewVerifier(keyResolver,
420-
htmsighttp.WithMaxSignatureAge(5*time.Minute), // Reject old signatures
421-
htmsighttp.WithRequiredComponents( // Require specific components
422-
component.Method(),
423-
component.New("date"),
424-
),
425-
htmsighttp.WithAllowedAlgorithms("rsa-pss-sha512"), // Restrict algorithms
426-
htmsighttp.WithSkipOnMissing(false), // Require signatures
427-
)
428-
```
429-
430-
## Examples
431-
432-
See the [examples directory](./examples/) for complete working examples:
433-
434-
- Basic request/response signing
435-
- HTTP server with verification
436-
- HTTP client with signing
437-
- Multiple signature scenarios
438-
- Custom key resolution
439-
440-
## RFC 9421 Compliance
441-
442-
This implementation follows RFC 9421 specifications including:
443-
444-
- ✅ Signature base construction (Section 2.5)
445-
- ✅ Signature creation and verification (Section 3)
446-
- ✅ All standard algorithms (Section 3.3)
447-
- ✅ Component identifiers (Section 2.1-2.3)
448-
- ✅ Signature parameters (Section 2.4)
449-
- ✅ Multiple signatures (Section 4.1)
450-
- ✅ Test vectors from RFC examples
451-
452-
## Contributing
453-
454-
Contributions are welcome! Please ensure:
455-
456-
1. All tests pass: `go test ./...`
457-
2. Code is formatted: `go fmt ./...`
458-
3. Linting passes: `golangci-lint run`
459-
4. New features include tests and documentation
329+
- **Derived Components**: `@method`, `@target-uri`, `@authority`, `@scheme`, `@request-target`, `@path`, `@query`, `@status`
330+
- **HTTP Fields**: Any HTTP header (e.g., `content-type`, `date`, `authorization`)
331+
- **Signature Parameters**: `created`, `expires`, `keyid`, `alg`, `nonce`, `tag`
460332

461333
## License
462334

0 commit comments

Comments
 (0)