extension

package
v0.0.0-...-152fb42 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 20, 2024 License: NCSA Imports: 23 Imported by: 2

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrCSRFInvalidTokenBytes = errors.NewError("invalid token bytes")
View Source 
var ErrSessionCrypto = errors.NewError("unable to initialize crypto engine for session")
View Source 
var ErrSessionKeyGen = errors.NewError("could not obtain crypto keys for session")

Functions

func ApplyDefaultExtensions 

func ApplyDefaultExtensions(app capstan.Application) error

func CompareToken 

func CompareToken(src, dst string) bool

CompareToken is a helper/convenience function that provides a cryptographically secure comparison of two tokens as strings.

func CompareTokenBytes 

func CompareTokenBytes(src, dst []byte) bool

CompareTokenBytes is a helper/convenience function that provides a cryptographically secure comparison of two tokens as byte slices.

func NewAuthenticationExtension 

func NewAuthenticationExtension(conf auth.AuthenticationConfig) *authenticationExtension

func NewEndpointTelemetry 

func NewEndpointTelemetry(opts EndpointTelemetryOptions) *endpointTelemetry

func NewEndpointTelemetryDefaults 

func NewEndpointTelemetryDefaults() *endpointTelemetry

func NewKeyStar 

func NewKeyStar(opts KeyStarConfig) *keyStarExtension

func NewKeyStarDefaults 

func NewKeyStarDefaults() *keyStarExtension

func NewSession 

func NewSession(conf SessionExtensionConfig) *defaultSessionExtension

func NewSessionDefaults 

func NewSessionDefaults() *defaultSessionExtension

func NewWatcher 

func NewWatcher() (*watcher, error)

Types

type AlwaysSendCSRFHeader 

type AlwaysSendCSRFHeader struct{}

AlwaysSendCSRFHeader is a helper struct for embedding a default state for always sending the CSRF header for every request on the controller for this has been injected.

func (*AlwaysSendCSRFHeader) SendCSRFHeader 

func (a *AlwaysSendCSRFHeader) SendCSRFHeader() bool

SendCSRFHeader, as a member of the AlwaysSendCSRFHeader struct, always returns true indicating that CSRF tokens should always be dispatched as part of the response headers.

type AlwaysVerifyCSRF 

type AlwaysVerifyCSRF struct{}

AlwaysVerifyCSRF is a helper struct for embedding a default always-verify CSRF token state.

func (*AlwaysVerifyCSRF) VerifyCSRF 

func (n *AlwaysVerifyCSRF) VerifyCSRF() bool

VerifyCSRF, as a member of the AlwaysVerifyCSRF struct, will always return true for verification, enabling verification for every matching request.

type CSRF 

type CSRF struct {
	KM KeyManager `inject:"security.keys"`
	// contains filtered or unexported fields
}

func NewCSRF 

func NewCSRF(options *CSRFOptions) (*CSRF, error)

TODO: Load keys dynamically via extension Init?

func NewCSRFDefaults 

func NewCSRFDefaults() *CSRF

func (*CSRF) Init 

func (c *CSRF) Init(app capstan.Application) error

func (*CSRF) Name 

func (c *CSRF) Name() string

func (*CSRF) Provides 

func (c *CSRF) Provides() string

func (*CSRF) Ready 

func (c *CSRF) Ready(app capstan.Application) error

Ready or not.

func (*CSRF) Requires 

func (c *CSRF) Requires() []string

func (*CSRF) Validate 

func (c *CSRF) Validate(token string) bool

Validate the given CSRF token. This may be used by controllers through use of `inject:"csrf"`.

func (*CSRF) Verify 

func (c *CSRF) Verify(ctx capstan.Context, token string) bool

type CSRFHeaderSend 

type CSRFHeaderSend interface {
	// SendCSRFHeader instructs the CSRF generator to send the CSRF token header
	// along with every request on the specified method.
	SendCSRFHeader() bool
}

CSRFHeaderSend is an interface type that indicates the CSRF facilities should dispatch CSRF tokens for *every* request made to a given controller, regardless of method.

type CSRFIgnore 

type CSRFIgnore interface {
	// IgnoreCSRF instructs the CSRF generator to ignore the entirety of this
	// controller. If this method exists on the controller and returns true,
	// neither validation nor verification will occur.
	IgnoreCSRF() bool
}

CSRFIgnore is an interface type that instructs the CSRF facilities to ignore all CSRF validation and generation for the underlying controller.

See the contained IgnoreCSRF method.

type CSRFOptions 

type CSRFOptions struct {
	// Key for CSRF token encipherment.
	Key []byte

	// HMAC key for CSRF token validity checks.
	HMAC []byte

	// Namespace for key retrieval.
	//
	// This may be a specific namespace for tokens generated using keys for a
	// particular purpose, "__global__" for the global namespace, or if left
	// uninitialized as the empty string, this will default to the namespace
	// configured by the key management extension.
	Namespace string

	// TokenHeader to use for validating CSRF tokens. Default "X-Csrf-Token" if
	// empty.
	TokenHeader string

	// SendTokenHeader with each response. This can be useful for API endpoints
	SendTokenHeader bool

	// NoTokenHeader disables validating CSRF tokens based upon the TokenHeader
	// value (above) sent as part of a request.
	NoTokenHeader bool

	// FormField instructions the CSRF validator which form field to examine for
	// validation. Default is "csrftoken."
	//
	// This value also controls the hidden field created by
	// csrftoken_hidden_field.
	FormField string

	// EnableFormValidation. By default, this is disabled. Form validation is an
	// opt-in-only feature because it requires the CSRF extension to call
	// Request.ParseForm or Request.ParseMultipartForm. This may have
	// performance implications.
	EnableFormValidation bool

	// CookeName to use for storing CSRF tokens client-side.
	CookieName string

	// CookieSecure, if enabled, forces CSRF token cookies to only be sent if
	// the connection is secure.
	CookieSecure bool

	// CookieSameSite to control SameSite settings. If this is disabled, this
	// will default to Lax. Set this to http.SameSiteNone to disable.
	CookieSameSite http.SameSite

	// InjectedName dictates what string is used to identify the CSRF validator
	// for dependency injection. If this isn't provided, "csrf" is used instead.
	InjectedName string

	// MaxAge after which the token is considered invalid. This defaults to 1
	// month.
	MaxAge time.Duration

	// GracePeriod for expired tokens. If the token exceeds its MaxAge but is
	// still within the confines of the GracePeriod, it will be accepted and
	// regenerated. This defaults to 1 week.
	GracePeriod time.Duration

	// RegenerationThreshold dictates when regeneration should pre-date the
	// MaxAge of the token. If this value is zero, the regeneration threshold
	// will default to 1 week.
	RegenerationThreshold time.Duration

	// Methods considered valid for CSRF checks. Leave this empty to validate
	// DELETE, PATCH, POST, and PUT.
	Methods []string
}

type CSRFRelinquish 

type CSRFRelinquish interface {
	// LetMeFail indicates the controller wishes to handle CSRF failures on its
	// own. Unlike CSRFVerifier, this doesn't bail from the token setup; tokens
	// are still generated (and verified) as needed, but the verification
	// failure is left to the controller.
	LetMeFail() bool
}

CSRFRelinquish is an interface type that indicates to the CSRF facilities that they much relinquish control over CSRF validation failures to the underlying controller type.

See the contained LetMeFail method.

type CSRFVerifier 

type CSRFVerifier interface {
	// VerifyCSRF token (or not) depending on the value of the returned `bool`.
	//
	// If the value returned is `true`, CSRF tokens will *always* be validated
	// for the implementing endpoint. If the value returned is `false`, CSRF
	// tokens will *never* be validated for the implementing endpoint.
	//
	// Tokens will still be generated for endpoints that return VerifyCSRF() ==
	// false; they just won't be validated. To ignore all CSRF activity,
	// implement CSRFIgnore.
	VerifyCSRF() bool
}

CSRFVerifier is an interface type that controllers may implement to indicate whether or not they wish to implement CSRF token validation.

See the contained VerifyCSRF method.

type EndpointTelemetryOptions 

type EndpointTelemetryOptions struct {
	Manager     *lib.TelemetryManager
	BindSignals bool
}

type HandlesCSRF 

type HandlesCSRF struct{}

HandlesCSRF is a helper struct that embeds the appropriate function and return value indicating that the parent struct wishes to handle CSRF validation itself.

func (*HandlesCSRF) LetMeFail 

func (h *HandlesCSRF) LetMeFail() bool

LetMeFail, as a member of the HandlesCSRF struct, always returns true indicating that the controller wishes to manage CSRF validation itself.

type IgnoreCSRF 

type IgnoreCSRF struct{}

IgnoreCSRF is a helper struct for embedding a default state for ignoring all CSRF token generation and validation.

func (*IgnoreCSRF) IgnoreCSRF 

func (i *IgnoreCSRF) IgnoreCSRF() bool

IgnoreCSRF, as a member of the IgnoreCSRF struct, indicates that the controller wishes to ignore all CSRF token generation and validation procedures.

type Key 

type Key interface {
	Bytes() []byte
	Created() time.Time
	Expires() time.Time
	IsExpired() bool
	Length() int
	Name() string
	Version() int
}

type KeyManager 

type KeyManager interface {
	WithKeyRing(namespace, keyring string, fn KeyRingFunc) error

	WithKeyRingTTL(namespace, keyring string, ttl int, fn KeyRingFunc) error

	WithGlobalKeyRing(keyring string, fn KeyRingFunc) error

	WithGlobalKeyRingTTL(keyring string, ttl int, fn KeyRingFunc) error
}

type KeyRing 

type KeyRing interface {
	// NewKey returns a new key from the current namespace or the global
	// namespace if otherwise unspecified or Namespace() has not been called.
	NewKey(name string, size int) (Key, error)

	// NewKeyPair returns a key pair. This is typically useful for creating
	// cipher and HMAC keys with a single call.
	NewKeyPair(name string, len1, len2 int) (Key, Key, error)
}

type KeyRingFunc 

type KeyRingFunc func(KeyRing) error

type KeyStarConfig 

type KeyStarConfig struct {
	Path string
	URI  string
	VFS  vfs.MutableFS
}

type KeyStarExtensionConfig 

type KeyStarExtensionConfig struct {
	// Path for key server VFS config
	Path string

	// URI for keystar accessibility.
	URI string

	// Namespace specifies the default namespace for KeyStar.
	Namespace string

	// CipherKeyLength sets the default key length for cipher keys. If this
	// value is not provided, it will default to 32 (AES-256).
	CipherKeyLength int

	// HMACKeyLength sets the default key length for HMAC generation. If this
	// value is not provided, it will defualt to 64.
	HMACKeyLength int
}

type NeverVerifyCSRF 

type NeverVerifyCSRF struct{}

NeverVerifyCSRF is a helper struct for embedding a default never-verify CSRF token state.

func (*NeverVerifyCSRF) VerifyCSRF 

func (n *NeverVerifyCSRF) VerifyCSRF() bool

VerifyCSRF, as a member of the NeverVerifyCSRF struct, will always return false for verification, disabling it.

type SessionBackend 

type SessionBackend int
const (
	// SessionNoopBackend does nothing.
	SessionNoopBackend SessionBackend = iota

	// SessionMemoryBackend stores session data in an in-process data structure
	// and sends an identifier to the client via a cookie.
	SessionMemoryBackend

	// SessionCookieBackend sends session data to the client encapsulated in a
	// cookie; this cookie is encrypted.
	SessionCookieBackend

	// SessionTestCookieBackend should ONLY be used for test environments as
	// this will render the session cookie in plain text.
	SessionTestCookieBackend
)

type SessionExtensionConfig 

type SessionExtensionConfig struct {
	// Backend controls which backend may be configured for session
	// management. If this value isn't set, it defaults to SessionNoopBackend
	// treating sessions as a noop. Note that some values may require additional
	// dependencies. In particular, enabling the cookie backend will require
	// KeyStar.
	//
	// Dependencies are further gated in the compiled binary via build flags.
	Backend SessionBackend

	// CookieOptions configures the session cookie to dispatch to the browser.
	CookieOptions *http.Cookie

	// DSN for backends that require datasource configuration.
	//
	// See the documentation for individual backends for a description of how
	// this is used.
	DSN string

	// Key used to encrypt/decrypt the session data.
	//
	// This value may be used to override the key used during session
	// encryption, such as for unit testing when using known keys.
	Key []byte

	// HMACKey used to sign and verify the session cookie. A key length of 64
	// bytes is recommended as per[1]
	//
	// [1] https://tools.ietf.org/html/rfc4868#section-2.6
	//
	// This value may be used to override the key used during session
	// encryption, such as for unit testing when using known keys.
	HMACKey []byte

	// YesImAbsolutelySureIWantPlainText toggles off cookie encryption if true.
	// This flag should only ever be enabled for debugging or testing.
	//
	// This flag cannot be enabled unless development mode is turned on.
	//
	// Note: Not all backends support encryption.
	//
	// Note: The name of this flag was chosen deliberately for its value as
	// obnoxious and difficult to type without autocompletion. Think twice if
	// you're using it.
	YesImAbsolutelySureIWantPlainText bool
}

type StaticOptions 

type StaticOptions struct {
}

type StaticPath 

type StaticPath struct {
}

func (*StaticPath) Init 

func (s *StaticPath) Init(server capstan.Application)

type VFS 

type VFS struct {
}

VFS provides a virtualized file system backend for StaticPath. This may be used separately, such as by migration tools for integrated assets.

type Watcher 

type Watcher interface {
	AddDir(string)
	AddCallback(watcherCallback)
	Close() error
}

type WebhookTelemetry 

type WebhookTelemetry struct {
	// contains filtered or unexported fields
}

func (*WebhookTelemetry) Init 

func (t *WebhookTelemetry) Init() error

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.