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)
- func SetSignatureError(h http.Header, se SignatureError) error
- type OIDCIssuerVerifier
- type OIDCOption
- type ParametersHWK
- type ParametersJKTJWT
- type ParametersJWKSURI
- type ParametersJWT
- type ParametersX509
- type Scheme
- type SigKeyHeader
- func (e SigKeyHeader) DWK() (string, error)
- func (skh SigKeyHeader) DeriveHeader(existingHeader string) (string, error)
- func (e SigKeyHeader) ID() (string, error)
- func (e SigKeyHeader) JWT() (string, error)
- func (e SigKeyHeader) KID() (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 SignatureError
- type SignatureErrorCode
- 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.
func SetSignatureError ¶
func SetSignatureError(h http.Header, se SignatureError) error
SetSignatureError sets the Signature-Error response header on h.
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 ParametersJKTJWT ¶
type ParametersJKTJWT struct {
JWT string `sfv:"jwt"`
}
ParametersJKTJWT are the parameters for the jkt-jwt scheme. The JWT must have its signing key in the jwk header parameter and its typ must be "jkt-s256+jwt" or "jkt-s512+jwt".
type ParametersJWKSURI ¶
type ParametersJWKSURI struct {
// ID is the signer identifier (HTTPS URL).
ID string `sfv:"id"`
// DWK is the dot well-known metadata document name under /.well-known/.
DWK string `sfv:"dwk"`
// KID is the key identifier within the JWKS.
KID string `sfv:"kid"`
}
ParametersJWKSURI are the parameters for the jwks_uri scheme. The verifier fetches {ID}/.well-known/{DWK} to obtain the JWKS URI, then retrieves the key matching KID.
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) DWK ¶
func (e SigKeyHeader) DWK() (string, error)
DWK returns the dot well-known metadata document name from a jwks_uri entry.
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) ID ¶
func (e SigKeyHeader) ID() (string, error)
ID returns the signer identifier (HTTPS URL) from a jwks_uri entry.
func (SigKeyHeader) JWT ¶
func (e SigKeyHeader) JWT() (string, error)
JWT returns the unvalidated JWT string from the entry's parameters. Used for both the jwt and jkt-jwt schemes, both of which carry the JWT in the "jwt" parameter.
func (SigKeyHeader) KID ¶
func (e SigKeyHeader) KID() (string, error)
KID returns the key identifier from a jwks_uri entry.
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 SignatureError ¶
type SignatureError struct {
// Code is the required error token.
Code SignatureErrorCode
// SupportedAlgorithms is populated for ErrCodeUnsupportedAlgorithm errors.
SupportedAlgorithms []string
// RequiredInput is optionally populated for ErrCodeInvalidInput errors.
RequiredInput []string
}
SignatureError represents a parsed Signature-Error response header.
func ParseSignatureError ¶
func ParseSignatureError(headerValue string) (SignatureError, error)
ParseSignatureError parses the value of a Signature-Error response header.
type SignatureErrorCode ¶
type SignatureErrorCode string
SignatureErrorCode is a token value for the Signature-Error response header.
const ( // SignatureErrorHeader is the canonical name of the Signature-Error HTTP response header. SignatureErrorHeader = "Signature-Error" ErrCodeUnsupportedAlgorithm SignatureErrorCode = "unsupported_algorithm" ErrCodeInvalidSignature SignatureErrorCode = "invalid_signature" ErrCodeInvalidInput SignatureErrorCode = "invalid_input" ErrCodeInvalidRequest SignatureErrorCode = "invalid_request" ErrCodeInvalidKey SignatureErrorCode = "invalid_key" ErrCodeUnknownKey SignatureErrorCode = "unknown_key" ErrCodeInvalidJWT SignatureErrorCode = "invalid_jwt" ErrCodeExpiredJWT SignatureErrorCode = "expired_jwt" )
type SignatureKeyFetcher ¶
type SignatureKeyFetcher struct {
// contains filtered or unexported fields
}
Signature-Key header using draft-hardt-httpbis-signature-key-04.
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