Documentation ¶
Index ¶
- Variables
- func GetTypeForAlg(alg string) string
- func ResponseExtractorStatusAny(ctx context.Context, resp *http.Response) (json.RawMessage, error)
- func ResponseExtractorStatusOK(ctx context.Context, resp *http.Response) (json.RawMessage, error)
- type ErrorHandler
- type GivenKey
- func NewGivenCustom(key interface{}) (givenKey GivenKey)deprecated
- func NewGivenCustomWithOptions(key interface{}, options GivenKeyOptions) (givenKey GivenKey)
- func NewGivenECDSA(key *ecdsa.PublicKey) (givenKey GivenKey)deprecated
- func NewGivenECDSACustomWithOptions(key *ecdsa.PublicKey, options GivenKeyOptions) (givenKey GivenKey)
- func NewGivenEdDSA(key ed25519.PublicKey) (givenKey GivenKey)deprecated
- func NewGivenEdDSACustomWithOptions(key ed25519.PublicKey, options GivenKeyOptions) (givenKey GivenKey)
- func NewGivenHMAC(key []byte) (givenKey GivenKey)deprecated
- func NewGivenHMACCustomWithOptions(key []byte, options GivenKeyOptions) (givenKey GivenKey)
- func NewGivenRSA(key *rsa.PublicKey) (givenKey GivenKey)deprecated
- func NewGivenRSACustomWithOptions(key *rsa.PublicKey, options GivenKeyOptions) (givenKey GivenKey)
- type GivenKeyOptions
- type JWKS
- func (j *JWKS) EndBackground()
- func (j *JWKS) GetMatchingKeys(token *jwt.Token) ([]*ParsedJWK, error)
- func (j *JWKS) GetMatchingKeysWithRefresh(token *jwt.Token) []*ParsedJWK
- func (j *JWKS) KIDs() (kids []string)
- func (j *JWKS) Keyfunc(token *jwt.Token) (interface{}, error)
- func (j *JWKS) Len() int
- func (j *JWKS) RawJWKS() []byte
- func (j *JWKS) ReadOnlyKeys() map[string]interface{}
- type JWKUse
- type JsonWebKey
- type Options
- type ParsedJWK
Constants ¶
This section is empty.
Variables ¶
var ( // ErrJWKAlgMismatch indicates that the given JWK was found, but its "alg" parameter's value did not match that of // the JWT. ErrJWKAlgMismatch = errors.New(`the given JWK was found, but its "alg" parameter's value did not match the expected algorithm`) // ErrNoMatchingKey indicated no JWKey is matching the token according ti SingleStore rules. ErrNoMatchingKey = errors.New("no key can be matched to validate the token") // ErrMissingAssets indicates there are required assets are missing to create a public key. ErrMissingAssets = errors.New("required assets are missing to create a public key") )
var ( // ErrECDSACurve indicates an error with the ECDSA curve. ErrECDSACurve = errors.New("invalid ECDSA curve") )
var ErrInvalidHTTPStatusCode = errors.New("invalid HTTP status code")
ErrInvalidHTTPStatusCode indicates that the HTTP status code is invalid.
Functions ¶
func GetTypeForAlg ¶
GetTypeForAlg returns the corresponding Key Type (kty) for a given `alg` value. kty: https://www.rfc-editor.org/rfc/rfc7518#section-7.4.2 alg: https://www.rfc-editor.org/rfc/rfc7518#section-7.1.2
func ResponseExtractorStatusAny ¶
ResponseExtractorStatusAny is meant to be used as the ResponseExtractor field for Options. It returns the raw JSON from the response body regardless of the response status code.
func ResponseExtractorStatusOK ¶
ResponseExtractorStatusOK is meant to be used as the ResponseExtractor field for Options. It confirms that response status code is 200 OK and returns the raw JSON from the response body.
Types ¶
type ErrorHandler ¶
type ErrorHandler func(err error)
ErrorHandler is a function signature that consumes an error.
type GivenKey ¶
type GivenKey struct {
// contains filtered or unexported fields
}
GivenKey represents a cryptographic key that resides in a JWKS. In conjuncture with Options.
func NewGivenCustom
deprecated
func NewGivenCustom(key interface{}) (givenKey GivenKey)
NewGivenCustom creates a new GivenKey given an untyped variable. The key argument is expected to be a supported by the jwt package used.
See the https://pkg.go.dev/github.com/golang-jwt/jwt#RegisterSigningMethod function for registering an unsupported signing method.
Deprecated: This function does not allow the user to specify the JWT's signing algorithm. Use NewGivenCustomWithOptions instead.
func NewGivenCustomWithOptions ¶
func NewGivenCustomWithOptions(key interface{}, options GivenKeyOptions) (givenKey GivenKey)
NewGivenCustomWithOptions creates a new GivenKey given an untyped variable. The key argument is expected to be a type supported by the jwt package used.
Consider the options carefully as each field may have a security implication.
See the https://pkg.go.dev/github.com/golang-jwt/jwt/v4#RegisterSigningMethod function for registering an unsupported signing method.
func NewGivenECDSA
deprecated
func NewGivenECDSACustomWithOptions ¶
func NewGivenECDSACustomWithOptions(key *ecdsa.PublicKey, options GivenKeyOptions) (givenKey GivenKey)
NewGivenECDSACustomWithOptions creates a new GivenKey given an ECDSA public key.
Consider the options carefully as each field may have a security implication.
func NewGivenEdDSA
deprecated
func NewGivenEdDSACustomWithOptions ¶
func NewGivenEdDSACustomWithOptions(key ed25519.PublicKey, options GivenKeyOptions) (givenKey GivenKey)
NewGivenEdDSACustomWithOptions creates a new GivenKey given an EdDSA public key.
Consider the options carefully as each field may have a security implication.
func NewGivenHMAC
deprecated
func NewGivenHMACCustomWithOptions ¶
func NewGivenHMACCustomWithOptions(key []byte, options GivenKeyOptions) (givenKey GivenKey)
NewGivenHMACCustomWithOptions creates a new GivenKey given an HMAC key in a byte slice.
Consider the options carefully as each field may have a security implication.
func NewGivenRSA
deprecated
func NewGivenRSACustomWithOptions ¶
func NewGivenRSACustomWithOptions(key *rsa.PublicKey, options GivenKeyOptions) (givenKey GivenKey)
NewGivenRSACustomWithOptions creates a new GivenKey given an RSA public key.
Consider the options carefully as each field may have a security implication.
type GivenKeyOptions ¶
type GivenKeyOptions struct { // Algorithm is the given key's signing algorithm. Its value will be compared to unverified tokens' "alg" header. // // See RFC 8725 Section 3.1 for details. // https://www.rfc-editor.org/rfc/rfc8725#section-3.1 // // For a list of possible values, please see: // https://www.rfc-editor.org/rfc/rfc7518#section-3.1 // https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms Algorithm string }
type JWKS ¶
type JWKS struct {
// contains filtered or unexported fields
}
JWKS represents a JSON Web Key Set (JWK Set).
func NewGiven ¶
NewGiven creates a JWKS from a map of given keys. NewGiven creates a JWKS from a map of given keys.
func NewJSON ¶
func NewJSON(jwksBytes json.RawMessage) (jwks *JWKS, err error)
NewJSON creates a new JWKS from a raw JSON message.
func (*JWKS) EndBackground ¶
func (j *JWKS) EndBackground()
EndBackground ends the background goroutine to update the JWKS. It can only happen once and is only effective if the JWKS has a background goroutine refreshing the JWKS keys.
func (*JWKS) GetMatchingKeys ¶
GetMatchingKeys implements the logic described in https://docs.singlestore.com/db/v7.8/en/security/authentication/authenticate-via-jwt.html A Read Lock for `j.mux` is acquired when the JWKS is read
JWTs are matched with JSON Web Keys (JWKs) for validation as follows: 1. If the JWT has a kid (Key ID) field, the JWKs with matching kid fields are validated. 2. If the JWT has a kid field that doesn’t match any JWK or jwt_config key, the authentication request is rejected. See Validate JWTs with the jwt-config for more information. 3. If the JWT has an iss (Issuer) field (instead of a kid field) that matches the kid in one or more JWKs, the JWKs with matching kid fields are validated. 4. If the JWT does not have a kid field and the iss field does not match the kid field in any JWK, then validation is attempted with all the JWKs with a matching alg (Algorithm) field. If the alg field is not specified, the kty (Key Type) field is used instead.
func (*JWKS) GetMatchingKeysWithRefresh ¶
GetMatchingKeysWithRefresh gets the keys according to SingleStore logic, and if `j.refreshUnknownKID` is set to `true`, performs jwks refresh if no key was matched
func (*JWKS) Keyfunc ¶
Keyfunc matches the signature of github.com/golang-jwt/jwt's jwt.Keyfunc function.
func (*JWKS) ReadOnlyKeys ¶
ReadOnlyKeys returns a read-only copy of the mapping of key IDs (`kid`) to cryptographic keys. Currently this function is used for test purposes only
type JWKUse ¶
type JWKUse string
JWKUse is a set of values for the "use" parameter of a JWK. See https://tools.ietf.org/html/rfc7517#section-4.2.
const ( // UseEncryption is a JWK "use" parameter value indicating the JSON Web Key is to be used for encryption. UseEncryption JWKUse = "enc" // UseOmitted is a JWK "use" parameter value that was not specified or was empty. UseOmitted JWKUse = "" // UseSignature is a JWK "use" parameter value indicating the JSON Web Key is to be used for signatures. UseSignature JWKUse = "sig" )
type JsonWebKey ¶
type JsonWebKey struct { Algorithm string `json:"alg"` Curve string `json:"crv"` Exponent string `json:"e"` K string `json:"k"` ID string `json:"kid"` Modulus string `json:"n"` Type string `json:"kty"` Use string `json:"use"` X string `json:"x"` Y string `json:"y"` UsernameFrom string `json:"usernameFrom"` Audience interface{} `json:"aud"` }
JsonWebKey represents a JSON Web Key inside a JWKS.
func (*JsonWebKey) ECDSA ¶
func (j *JsonWebKey) ECDSA() (publicKey *ecdsa.PublicKey, err error)
ECDSA parses a jsonWebKey and turns it into an ECDSA public key.
func (*JsonWebKey) EdDSA ¶
func (j *JsonWebKey) EdDSA() (publicKey ed25519.PublicKey, err error)
EdDSA parses a jsonWebKey and turns it into a EdDSA public key.
func (*JsonWebKey) Oct ¶
func (j *JsonWebKey) Oct() (publicKey []byte, err error)
Oct parses a jsonWebKey and turns it into a raw byte slice (octet). This includes HMAC keys.
type Options ¶
type Options struct { // Client is the HTTP client used to get the JWKS via HTTP. Client *http.Client // Ctx is the context for the keyfunc's background refresh. When the context expires or is canceled, the background // goroutine will end. Ctx context.Context // GivenKeys is a map of JWT key IDs, `kid`, to their given keys. If the JWKS has a background refresh goroutine, // these values persist across JWKS refreshes. By default, if the remote JWKS resource contains a key with the same // `kid` any given keys with the same `kid` will be overwritten by the keys from the remote JWKS. Use the // GivenKIDOverride option to flip this behavior. GivenKeys map[string]GivenKey // GivenKIDOverride will make a GivenKey override any keys with the same ID (`kid`) in the remote JWKS. The is only // effectual if GivenKeys is provided. GivenKIDOverride bool // JWKUseWhitelist is a whitelist of JWK `use` parameter values that will restrict what keys can be returned for // jwt.Keyfunc. The assumption is that jwt.Keyfunc is only used for JWT signature verification. // The default behavior is to only return a JWK if its `use` parameter has the value `"sig"`, an empty string, or if // the parameter was omitted entirely. JWKUseWhitelist []JWKUse // JWKUseNoWhitelist overrides the JWKUseWhitelist field and its default behavior. If set to true, all JWKs will be // returned regardless of their `use` parameter value. JWKUseNoWhitelist bool // RefreshErrorHandler is a function that consumes errors that happen during a JWKS refresh. This is only effectual // if a background refresh goroutine is active. RefreshErrorHandler ErrorHandler // RefreshInterval is the duration to refresh the JWKS in the background via a new HTTP request. If this is not nil, // then a background goroutine will be used to refresh the JWKS once per the given interval. Make sure to call the // JWKS.EndBackground method to end this goroutine when it's no longer needed. RefreshInterval time.Duration // RefreshRateLimit limits the rate at which refresh requests are granted. Only one refresh request can be queued // at a time any refresh requests received while there is already a queue are ignored. It does not make sense to // have RefreshInterval's value shorter than this. RefreshRateLimit time.Duration // RefreshTimeout is the duration for the context timeout used to create the HTTP request for a refresh of the JWKS. // This defaults to one minute. This is used for the HTTP request and any background goroutine refreshes. RefreshTimeout time.Duration // RefreshUnknownKID indicates that the JWKS refresh request will occur every time a kid that isn't cached is seen. // This is done through a background goroutine. Without specifying a RefreshInterval a malicious client could // self-sign X JWTs, send them to this service, then cause potentially high network usage proportional to X. Make // sure to call the JWKS.EndBackground method to end this goroutine when it's no longer needed. RefreshUnknownKID bool // InitAsync indicates that the JWKS will be fetched asynchronously upon initialization. InitAsync bool // RequestFactory creates HTTP requests for the remote JWKS resource located at the given url. For example, an // HTTP header could be added to indicate a User-Agent. RequestFactory func(ctx context.Context, url string) (*http.Request, error) // ResponseExtractor consumes a *http.Response and produces the raw JSON for the JWKS. By default, the // ResponseExtractorStatusOK function is used. The default behavior changed in v1.4.0. ResponseExtractor func(ctx context.Context, resp *http.Response) (json.RawMessage, error) }
Options represents the configuration options for a JWKS.
If RefreshInterval and or RefreshUnknownKID is not nil, then a background goroutine will be launched to refresh the remote JWKS under the specified circumstances.
When using a background refresh goroutine, make sure to use RefreshRateLimit if paired with RefreshUnknownKID. Also make sure to end the background refresh goroutine with the JWKS.EndBackground method when it's no longer needed.
type ParsedJWK ¶
type ParsedJWK struct { Public interface{} Jwk *JsonWebKey // contains filtered or unexported fields }
parsedJWK represents a JSON Web Key parsed with fields as the correct Go types.