# README
A Golang implementation of HTTP Message Signatures, as defined by RFC 9421 (the former draft-ietf-httpbis-message-signatures).
This is a nearly feature-complete implementation of the RFC, including all test vectors.
Usage
The library provides natural integration points with Go HTTP clients and servers, as well as direct usage of the sign and verify functions.
Below is what a basic client-side integration looks like. Additional examples are available in the API reference.
// Create a signer and a wrapped HTTP client
signer, _ := httpsign.NewRSAPSSSigner(*prvKey, httpsign.NewSignConfig(),
httpsign.Headers("@request-target", "content-digest")) // The Content-Digest header will be auto-generated
client := httpsign.NewDefaultClient(httpsign.NewClientConfig().SetSignatureName("sig1").SetSigner(signer)) // sign requests, don't verify responses
// Send an HTTP POST, get response -- signing happens behind the scenes
body := `{"hello": "world"}`
res, _ := client.Post(ts.URL, "application/json", bufio.NewReader(strings.NewReader(body)))
// Read the response
serverText, _ := io.ReadAll(res.Body)
_ = res.Body.Close()
Notes and Missing Features
- The
Accept-Signatureheader is unimplemented. - In responses, when using the "wrapped handler" feature, the
Content-Typeheader is only signed if set explicitly by the server. This is different, but arguably more secure, than the normalnet.httpbehavior.
# Functions
GenerateContentDigestHeader generates a digest of the message body according to the given scheme(s) (currently supporting DigestSha256 and DigestSha512).
Headers is a simple way to generate a Fields list, where only simple header names and derived headers are needed.
NewClient constructs a new client, with the flexibility of including a custom http.Client.
NewClientConfig creates a new, default ClientConfig.
NewDefaultClient constructs a new client, based on the http.DefaultClient.
NewEd25519Signer returns a new Signer structure.
NewEd25519SignerFromSeed returns a new Signer structure.
NewEd25519Verifier generates a new Verifier for EdDSA Curve 25519 signatures.
NewFields returns an empty list of fields.
NewHandlerConfig generates a default configuration.
NewHMACSHA256Signer returns a new Signer structure.
NewHMACSHA256Verifier generates a new Verifier for HMAC-SHA256 signatures.
NewJWSSigner creates a generic signer for JWS algorithms, using the go-jwx package.
NewJWSVerifier creates a generic verifier for JWS algorithms, using the go-jwx package.
NewP256Signer returns a new Signer structure.
NewP256Verifier generates a new Verifier for ECDSA (P-256) signatures.
NewP384Signer returns a new Signer structure.
NewP384Verifier generates a new Verifier for ECDSA (P-384) signatures.
NewRSAPSSSigner returns a new Signer structure.
NewRSAPSSVerifier generates a new Verifier for RSA-PSS signatures.
NewRSASigner returns a new Signer structure.
NewRSAVerifier generates a new Verifier for RSA signatures.
NewSignConfig generates a default configuration.
NewVerifyConfig generates a default configuration.
QueryEscapeForSignature escapes the string, so it can be safely placed inside a URL query.
RequestDetails parses a signed request and returns the key ID and optionally the algorithm used in the given signature.
RequestSignatureNames returns the list of signature names present in a request (empty list if none found).
ResponseDetails parses a signed response and returns the key ID and optionally the algorithm used in the given signature.
ResponseSignatureNames returns the list of signature names present in a response (empty list if none found).
SignRequest signs an HTTP request.
SignResponse signs an HTTP response.
ValidateContentDigestHeader validates that the Content-Digest header complies to policy: at least one of the "accepted" schemes is used, and all known schemes are associated with a correct digest of the message body.
VerifyRequest verifies a signed HTTP request.
VerifyResponse verifies a signed HTTP response.
WrapHandler wraps a server's HTTP request handler so that the incoming request is verified and the response is signed.
# Constants
Constants define the hash algorithm to be used for the digest.
Constants define the hash algorithm to be used for the digest.
# Structs
Client represents an HTTP client that optionally signs requests and optionally verifies responses.
ClientConfig contains additional configuration for the HTTP client-side wrapper.
Fields is a list of fields to be signed or verified.
HandlerConfig contains additional configuration for the HTTP message handler wrapper.
MessageDetails aggregates the details of a signed message, for a given signature.
SignConfig contains additional configuration for the signer.
Signer includes a cryptographic key (typically a private key) and configuration of what needs to be signed.
Verifier includes a cryptographic key (typically a public key) and configuration of what needs to be verified.
VerifyConfig contains additional configuration for the verifier.
# Type aliases
No description provided by the author
No description provided by the author