Documentation
¶
Overview ¶
Package httpsig implements HTTP Message Signatures per RFC 9421.
Overview ¶
HTTP Message Signatures provide a mechanism for digitally signing HTTP messages, enabling authentication, integrity protection, and non-repudiation. This package implements the signature creation and verification mechanisms required by the AAuth protocol.
Covered Components ¶
The signature covers specific components of the HTTP message:
- @method: The HTTP method (GET, POST, etc.)
- @target-uri: The full request target URI
- @authority: The host from the request
- @path: The path portion of the request target
- @query: The query string
- Standard headers: Any HTTP headers included in the signature base
Usage Example ¶
// Create a signer
signer, err := httpsig.NewSigner(httpsig.SignerOptions{
PrivateKey: privateKey,
KeyID: "my-key-1",
Algorithm: "ecdsa-p256-sha256",
})
if err != nil {
log.Fatal(err)
}
// Sign a request
req, _ := http.NewRequest("GET", "https://api.example.com/data", nil)
if err := signer.Sign(req); err != nil {
log.Fatal(err)
}
// Verify a request
verifier := httpsig.NewVerifier(httpsig.VerifierOptions{
PublicKey: publicKey,
KeyID: "my-key-1",
})
result, err := verifier.Verify(req)
References ¶
Index ¶
- Constants
- Variables
- func DeriveComponent(req *http.Request, component string) (string, error)
- func FormatSignatureInput(label string, params *SignatureParams) string
- func IsValidComponent(component string) bool
- func NormalizeHeaderName(name string) string
- func ParseSignatureInput(header string) (map[string]*SignatureParams, error)
- type KeyResolver
- type KeyResolverVerifier
- type SignatureParams
- type Signer
- type SignerOptions
- type VerificationResult
- type Verifier
- type VerifierOptions
Constants ¶
const ( // ComponentMethod is the HTTP request method. ComponentMethod = "@method" // ComponentTargetURI is the full target URI of the request. ComponentTargetURI = "@target-uri" // ComponentAuthority is the host/authority of the request. ComponentAuthority = "@authority" // ComponentScheme is the scheme of the request URI. ComponentScheme = "@scheme" // ComponentPath is the absolute path of the request URI. ComponentPath = "@path" // ComponentQuery is the query string (including the leading ?). ComponentQuery = "@query" // ComponentQueryParam is a specific query parameter (requires name parameter). ComponentQueryParam = "@query-param" // ComponentRequestTarget is the HTTP/1.1 request target. ComponentRequestTarget = "@request-target" // ComponentSignatureParams is the signature parameters (always included last). ComponentSignatureParams = "@signature-params" )
Derived component identifiers per RFC 9421.
Variables ¶
var AAuthCoveredComponents = []string{ ComponentMethod, ComponentTargetURI, "content-digest", "signature-key", }
AAuthCoveredComponents are the components recommended for AAuth signatures.
var DefaultCoveredComponents = []string{ ComponentMethod, ComponentTargetURI, "content-digest", "authorization", }
DefaultCoveredComponents are the default components to include in a signature.
Functions ¶
func DeriveComponent ¶
DeriveComponent derives the value of a component from an HTTP request. For derived components (starting with @), it computes the value per RFC 9421. For regular headers, it returns the header value.
func FormatSignatureInput ¶
func FormatSignatureInput(label string, params *SignatureParams) string
FormatSignatureInput formats a signature label and params for the Signature-Input header. Example: sig1=(@method @target-uri);created=123;keyid="key"
func IsValidComponent ¶
IsValidComponent checks if a component identifier is valid.
func NormalizeHeaderName ¶
NormalizeHeaderName normalizes a header name for signature purposes. Header names are lowercased per RFC 9421.
func ParseSignatureInput ¶
func ParseSignatureInput(header string) (map[string]*SignatureParams, error)
ParseSignatureInput parses a Signature-Input header value. Returns a map of label -> SignatureParams.
Types ¶
type KeyResolver ¶
type KeyResolver interface {
// ResolveKey returns the public key for a given key ID.
ResolveKey(keyID string) (crypto.PublicKey, error)
}
KeyResolver resolves public keys by key ID.
type KeyResolverVerifier ¶
type KeyResolverVerifier struct {
Resolver KeyResolver
AllowedAlgorithms []string
RequiredComponents []string
MaxAge time.Duration
}
KeyResolverVerifier is a verifier that uses a KeyResolver to find keys.
func (*KeyResolverVerifier) Verify ¶
func (v *KeyResolverVerifier) Verify(req *http.Request) (*VerificationResult, error)
Verify verifies a request using the key resolver to find the appropriate key.
type SignatureParams ¶
type SignatureParams struct {
// Components is the ordered list of covered components.
Components []string
// Created is the signature creation time.
Created time.Time
// Expires is the optional expiration time.
Expires *time.Time
// Nonce is an optional nonce value for replay protection.
Nonce string
// Algorithm is the signature algorithm identifier.
Algorithm string
// KeyID is the identifier for the signing key.
KeyID string
// Tag is an optional application-specific tag.
Tag string
}
SignatureParams represents the parameters of a signature.
func DefaultSignatureParams ¶
func DefaultSignatureParams(keyID, algorithm string, components []string) *SignatureParams
DefaultSignatureParams creates default signature parameters.
func ParseSignatureParams ¶
func ParseSignatureParams(input string) (*SignatureParams, error)
ParseSignatureParams parses a Signature-Input header value into SignatureParams. Format: (component1 component2 ...);created=123;keyid="key";alg="alg"
func (*SignatureParams) Serialize ¶
func (p *SignatureParams) Serialize() string
Serialize serializes the signature parameters to the Signature-Input format. Format: (component1 component2 ...);created=123;keyid="key";alg="alg"
type Signer ¶
type Signer interface {
// Sign adds Signature and Signature-Input headers to the request.
Sign(req *http.Request) error
}
Signer signs HTTP requests per RFC 9421.
func NewSigner ¶
func NewSigner(opts SignerOptions) (Signer, error)
NewSigner creates a new HTTP message signer.
type SignerOptions ¶
type SignerOptions struct {
// PrivateKey is the key used for signing.
PrivateKey crypto.PrivateKey
// KeyID is the identifier for the signing key.
KeyID string
// Algorithm is the HTTP signature algorithm identifier.
// Supported: ecdsa-p256-sha256, ecdsa-p384-sha384, rsa-pss-sha256, ed25519
Algorithm string
// CoveredComponents is the list of components to include in the signature.
// Defaults to DefaultCoveredComponents if not specified.
CoveredComponents []string
// Label is the signature label (defaults to "sig1").
Label string
// IncludeNonce adds a nonce to signatures for replay protection.
IncludeNonce bool
}
SignerOptions configures a Signer.
type VerificationResult ¶
type VerificationResult struct {
// Valid is true if the signature verified successfully.
Valid bool
// Label is the signature label that was verified.
Label string
// Params contains the signature parameters.
Params *SignatureParams
// KeyID is the key ID from the signature.
KeyID string
}
VerificationResult contains the result of signature verification.
type Verifier ¶
type Verifier interface {
// Verify checks the signature on a request.
Verify(req *http.Request) (*VerificationResult, error)
}
Verifier verifies HTTP message signatures per RFC 9421.
func NewVerifier ¶
func NewVerifier(opts VerifierOptions) (Verifier, error)
NewVerifier creates a new HTTP message signature verifier.
type VerifierOptions ¶
type VerifierOptions struct {
// PublicKey is the key used for verification.
PublicKey crypto.PublicKey
// KeyID is the expected key ID (optional, used for matching).
KeyID string
// AllowedAlgorithms restricts which algorithms are accepted.
// If empty, all supported algorithms are allowed.
AllowedAlgorithms []string
// RequiredComponents specifies components that must be in the signature.
// If empty, no specific components are required.
RequiredComponents []string
// MaxAge is the maximum age of a signature (based on created time).
// If zero, no age check is performed.
MaxAge time.Duration
// Label specifies which signature to verify (defaults to first signature).
Label string
}
VerifierOptions configures a Verifier.
Source Files