Documentation
¶
Overview ¶
Package sigkey parses the Signature-Key HTTP header defined in draft-hardt-httpbis-signature-key. It has no dependency on the parent httpsig package and can be used standalone.
This package does not perform any validation of keys or certificates and is only responsible for parsing the Signature-Key header.
Index ¶
- func ParseHeader(headerValue string) (map[string]SigKeyHeader, error)
- type OIDCIssuerVerifier
- type OIDCOption
- type ParametersHWK
- type ParametersJWKSURI
- type ParametersJWT
- type ParametersX509
- type Scheme
- type SigKeyHeader
- func (skh SigKeyHeader) DeriveHeader(existingHeader string) (string, error)
- func (e SigKeyHeader) JWKSURI() (string, error)
- func (e SigKeyHeader) JWT() (string, error)
- func (e SigKeyHeader) Param(name string) (any, bool)
- func (skh SigKeyHeader) SetHeader(h http.Header) error
- func (e SigKeyHeader) StringParam(name string) (string, error)
- type SignatureKeyFetcher
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseHeader ¶
func ParseHeader(headerValue string) (map[string]SigKeyHeader, error)
ParseHeader parses a Signature-Key header value as an SFV Dictionary and returns a map from signature label to SigKey. Returns an error if the value is empty, not a valid SFV dictionary, or any entry has a malformed scheme.
Types ¶
type OIDCIssuerVerifier ¶
type OIDCIssuerVerifier struct {
// contains filtered or unexported fields
}
OIDCIssuerVerifier validates JWTs by fetching the issuer's JWKS from {iss}/.well-known/jwks.json, verifying the JWT signature, and validating standard claims (exp, iat).
Only issuers in the allowedIssuers list are accepted. An empty list rejects all JWTs.
JWKS responses are cached per issuer with a configurable TTL (default 5 minutes) to avoid fetching on every request.
func NewOIDCIssuerVerifier ¶
func NewOIDCIssuerVerifier(allowedIssuers []string, opts ...OIDCOption) *OIDCIssuerVerifier
NewOIDCIssuerVerifier creates an OIDCIssuerVerifier that accepts JWTs from any issuer in allowedIssuers. Pass an empty slice to reject all JWTs.
type OIDCOption ¶
type OIDCOption func(*OIDCIssuerVerifier)
OIDCOption configures an OIDCIssuerVerifier.
func WithHTTPClient ¶
func WithHTTPClient(c *http.Client) OIDCOption
WithHTTPClient sets the HTTP client used for JWKS fetches.
func WithJWKSCacheTTL ¶
func WithJWKSCacheTTL(d time.Duration) OIDCOption
WithJWKSCacheTTL sets how long a fetched JWKS is cached before re-fetching. Default is 5 minutes.
type ParametersHWK ¶
type ParametersJWKSURI ¶
type ParametersJWT ¶
type ParametersJWT struct {
JWT string `sfv:"jwt"`
}
type ParametersX509 ¶
type SigKeyHeader ¶
type SigKeyHeader struct {
// Label is the signature label (dictionary key), e.g. "sig1".
Label string
// Scheme is the key-transport scheme token, e.g. "jwt".
Scheme Scheme
// contains filtered or unexported fields
}
SigKeyHeader is one parsed entry from the Signature-Key header dictionary. Each entry corresponds to a single signature label.
func NewSigKey ¶
func NewSigKey(label string, scheme Scheme, params any) (SigKeyHeader, error)
NewSigKey constructs a SigKeyHeader from a label, scheme, and one of the Parameters structs. The resulting value can be serialized into a Signature-Key header value via DeriveHeader.
func (SigKeyHeader) DeriveHeader ¶
func (skh SigKeyHeader) DeriveHeader(existingHeader string) (string, error)
DeriveHeader returns the value to set for a Signature-Key header, adding or replacing the entry for label. existing is the current header value (empty string if the header is not yet set). scheme is the key-transport token (e.g. SchemeJWT). params must be a pointer to or value of one of the Parameters structs (ParametersJWT, ParametersHWK, ParametersJWKSURI, ParametersX509). Fields are mapped to SFV parameters using the "sfv" struct tag; fields tagged with "omitempty" are skipped when zero.
func (SigKeyHeader) JWKSURI ¶
func (e SigKeyHeader) JWKSURI() (string, error)
JWKSURI returns the JWKS URI from the entry's parameters. Convenience wrapper for StringParam(SchemeHWKSURI).
func (SigKeyHeader) JWT ¶
func (e SigKeyHeader) JWT() (string, error)
JWT returns the unvalidated JWT string from the entry's parameters. Convenience wrapper for StringParam(SchemeJWT).
func (SigKeyHeader) Param ¶
func (e SigKeyHeader) Param(name string) (any, bool)
Param returns the raw SFV parameter value for the given name, along with whether it was present. This provides access to scheme-specific parameters (e.g. "jwt") without the caller needing to know the SFV types.
func (SigKeyHeader) StringParam ¶
func (e SigKeyHeader) StringParam(name string) (string, error)
StringParam returns the named parameter as a string. Returns an error if the parameter is absent or is not a string value.
type SignatureKeyFetcher ¶
type SignatureKeyFetcher struct {
// contains filtered or unexported fields
}
SignatureKeyFetcher implements key.KeyFetcher by resolving keys from the Signature-Key header using draft-hardt-httpbis-signature-key-02.
Only the jwt scheme is supported. For each verified signature label the fetcher validates the JWT via OIDCIssuerVerifier, extracts the public key from the cnf.jwk claim, and returns a KeySpec whose Identity field is populated from the JWT iss and sub claims.
func NewSignatureKeyFetcher ¶
func NewSignatureKeyFetcher(label string, issuerVerifier *OIDCIssuerVerifier) *SignatureKeyFetcher
NewSignatureKeyFetcher creates a SignatureKeyFetcher for the given signature label. issuerVerifier verifies the JWT and fetches the issuer's JWKS.
func (*SignatureKeyFetcher) Fetch ¶
func (f *SignatureKeyFetcher) Fetch(ctx context.Context, headers http.Header, _ types.MetadataProvider) (key.KeySpecer, error)
Fetch implements key.KeyFetcher.
func (*SignatureKeyFetcher) FetchByKeyID ¶
func (f *SignatureKeyFetcher) FetchByKeyID(ctx context.Context, headers http.Header, _ string) (key.KeySpecer, error)
FetchByKeyID implements key.KeyFetcher. The keyID from the signature metadata is ignored because the key material is carried in the Signature-Key header.
Source Files