httpsec

Documentation

Index

• Constants
• Variables
• func CSPReportHandler(handler func(report CSPReport)) http.Handler
• type CORSOption
  • func EndpointPolicy(endpoint string, policy *CORSPolicy) CORSOption
  • func EndpointPrefixPolicy(prefix string, policy *CORSPolicy) CORSOption
  • func FallbackPolicy(policy *CORSPolicy) CORSOption
• type CORSPolicy
  • func NewPolicy() *CORSPolicy
  • func (p *CORSPolicy) AllowAnyOrigin() *CORSPolicy
  • func (p *CORSPolicy) AllowCredentials() *CORSPolicy
  • func (p *CORSPolicy) AllowDelete() *CORSPolicy
  • func (p *CORSPolicy) AllowGet() *CORSPolicy
  • func (p *CORSPolicy) AllowHeader(headers ...string) *CORSPolicy
  • func (p *CORSPolicy) AllowMethods(methods ...string) *CORSPolicy
  • func (p *CORSPolicy) AllowOrigin(origins ...string) *CORSPolicy
  • func (p *CORSPolicy) AllowPatch() *CORSPolicy
  • func (p *CORSPolicy) AllowPost() *CORSPolicy
  • func (p *CORSPolicy) AllowPut() *CORSPolicy
  • func (p *CORSPolicy) MaxAge(ttl time.Duration) *CORSPolicy
• type CSPOption
  • func CSPReportingEndpoint(endpoint string) CSPOption
  • func DefaultNone() CSPOption
  • func DefaultSources(domains ...string) CSPOption
  • func ImageSources(domains ...string) CSPOption
  • func MediaSources(domains ...string) CSPOption
  • func ScriptSources(domains ...string) CSPOption
  • func StyleSources(domains ...string) CSPOption
• type CSPReport
• type SecurityOption
  • func EnableCORS(options ...CORSOption) SecurityOption
  • func EnableContentSecurityPolicy(opts ...CSPOption) SecurityOption
  • func EnableStrictTransportSecurity(maxAge time.Duration, includeSubdomains bool) SecurityOption
• type SecurityPolicies
  • func NewSecurityPolicies(opts ...SecurityOption) (*SecurityPolicies, error)
  • func (s *SecurityPolicies) Middleware(next http.Handler) http.Handler

Constants

const (
	HeaderCORSOrigin       = "Origin"
	HeaderCORSVary         = "Vary"
	HeaderCORSAllowOrigin  = "Access-Control-Allow-Origin"
	HeaderCORSAllowMethods = "Access-Control-Allow-Methods"
	HeaderCORSAllowHeaders = "Access-Control-Allow-Headers"
	HeaderCORSAllowCreds   = "Access-Control-Allow-Credentials"
	HeaderCORSMaxAge       = "Access-Control-Max-Age"

	CORSAnyOrigin  = "*"
	CORSNullOrigin = "null"
)

const (
	HeaderContentSecurityPolicy = "Content-Security-Policy"
	CSPSourceSelf               = "'self'" // CSPSourceNone is the constant for the policy accepting content from the origin domain.
	CSPSourceNone               = "'none'" // CSPSourceNone is the constant for the policy accepting no content.
	CSPReportContentType        = "application/csp-report"
)

const (
	HeaderReportingEndpoints = "Reporting-Endpoints"
)

const (
	HeaderStrictTransportSecurity = "Strict-Transport-Security"
)

Variables

var (
	ErrCORSPolicy    = errors.New("CORS policy error")
	ErrCORSNoOrigin  = errors.New("no allowed origins specified")
	ErrCORSNoMethods = errors.New("no allowed methods specified")
)

var (
	ErrContentSecurityConfig = errors.New("content security policy configuration error")
)

var (
	ErrStrictTransportSecurity = errors.New("strict transport security")
)

Functions

func CSPReportHandler

func CSPReportHandler(handler func(report CSPReport)) http.Handler

CSPReportHandler allows specifying a handler function for receiving CSP violation reports.

Types

type CORSOption

type CORSOption func(c *corsConfig)

func EndpointPolicy

func EndpointPolicy(endpoint string, policy *CORSPolicy) CORSOption

EndpointPolicy specifies the CORS allowances for the given endpoint. This will use an exact-match criteria to determine if the policy applies to the given request.

func EndpointPrefixPolicy

func EndpointPrefixPolicy(prefix string, policy *CORSPolicy) CORSOption

EndpointPrefixPolicy specifies the CORS allowances for endpoints with the given path prefix. This will use a starts-with criteria to determine if the policy applies to the given request.

func FallbackPolicy

func FallbackPolicy(policy *CORSPolicy) CORSOption

FallbackPolicy specifies the CORS allowances when no endpoint policy is found. If this is not specified, then the default will be to not allow cross-origin resource sharing.

type CORSPolicy

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

func NewPolicy

func NewPolicy() *CORSPolicy

func (*CORSPolicy) AllowAnyOrigin

func (p *CORSPolicy) AllowAnyOrigin() *CORSPolicy

AllowAnyOrigin sets this policy's origin allow list to be *, allowing any origin.

func (*CORSPolicy) AllowCredentials

func (p *CORSPolicy) AllowCredentials() *CORSPolicy

AllowCredentials sets the credentials flag when responding to OPTIONS preflight requests.

func (*CORSPolicy) AllowDelete

func (p *CORSPolicy) AllowDelete() *CORSPolicy

AllowDelete allows the DELETE method for this policy.

func (*CORSPolicy) AllowGet

func (p *CORSPolicy) AllowGet() *CORSPolicy

AllowGet allows the GET method for this policy.

func (*CORSPolicy) AllowHeader

func (p *CORSPolicy) AllowHeader(headers ...string) *CORSPolicy

AllowHeader allows the given header to be sent.

func (*CORSPolicy) AllowMethods

func (p *CORSPolicy) AllowMethods(methods ...string) *CORSPolicy

AllowMethods is a convenience method that enables specifying multiple allowed request methods for this policy.

func (*CORSPolicy) AllowOrigin

func (p *CORSPolicy) AllowOrigin(origins ...string) *CORSPolicy

AllowOrigin allows access to the given origin for this policy. Calling this method will override a previous call to CORSPolicy.AllowAnyOrigin.

func (*CORSPolicy) AllowPatch

func (p *CORSPolicy) AllowPatch() *CORSPolicy

AllowPatch allows the PATCH method for this policy.

func (*CORSPolicy) AllowPost

func (p *CORSPolicy) AllowPost() *CORSPolicy

AllowPost allows the POST method for this policy.

func (*CORSPolicy) AllowPut

func (p *CORSPolicy) AllowPut() *CORSPolicy

AllowPut allows the PUT method for this policy.

func (*CORSPolicy) MaxAge

func (p *CORSPolicy) MaxAge(ttl time.Duration) *CORSPolicy

MaxAge sets the max cache time for this policy. A policy's default max age without calling this method is 24 hours.

type CSPOption

type CSPOption func(c *cspConfig)

CSPOption represents an option to configure content security policy behavior.

func CSPReportingEndpoint

func CSPReportingEndpoint(endpoint string) CSPOption

CSPReportingEndpoint specifies a reporting endpoint that will be called in the case of CSP violations. The CSPReportHandler may be used to easily specify a handler for these reports.

func DefaultNone

func DefaultNone() CSPOption

DefaultNone sets a default source policy where no content is allowed. This should be used in cases where only specific policies should be matched to the content request. Note that this will replace any previously set default source entries.

func DefaultSources

func DefaultSources(domains ...string) CSPOption

DefaultSources sets the default, fallback policy for all content types. If a specific policy is not defined for the requested content, then this policy will apply.

If no default sources are given, then the CSP will use a default source of 'self'. To instead specify a default of 'none', use DefaultNone.

func ImageSources

func ImageSources(domains ...string) CSPOption

ImageSources specifies allowed domains for fetching image data.

func MediaSources

func MediaSources(domains ...string) CSPOption

MediaSources specifies allowed domains for fetching media.

func ScriptSources

func ScriptSources(domains ...string) CSPOption

ScriptSources specifies allowed domains for fetching executable scripts.

func StyleSources

func StyleSources(domains ...string) CSPOption

StyleSources specifies allowed domains for fetching styles.

type CSPReport

type CSPReport struct {
	DocumentURI        string `json:"document-uri"`        // The URI of the document in which the violation occurred.
	BlockedURI         string `json:"blocked-uri"`         // The blocked resource.
	Disposition        string `json:"disposition"`         // This should always be "enforce" with this setup.
	EffectiveDirective string `json:"effective-directive"` // The specific directive that resulted in the violation.
	OriginalPolicy     string `json:"original-policy"`     // The full CSP as seen and enforced by the user agent.
	ScriptSample       string `json:"script-sample"`       // If given, includes the initial 40 bytes of the offending reference.
	StatusCode         int    `json:"status-code"`
}

CSPReport is a report that should be forwarded from the user agent when the page requests content that violates the specified CSP. CSPReportHandler can be used to receive this report.

type SecurityOption

type SecurityOption func(sec *SecurityPolicies) error

func EnableCORS

func EnableCORS(options ...CORSOption) SecurityOption

EnableCORS sets up Cross Origin Resource Sharing (CORS) in the SecurityPolicies.

CORS is intended to explicitly and safely allow cross-origin requests from the browser. A web server by default doesn't allow cross-origin requests because no Allow headers will be sent. So this is provided to explicitly allow such requests in cases where it makes sense.

This implementation is somewhat opinionated. This will not allow a null origin to be accepted, because it enables a few classes of vulnerabilities. It also does not use wildcard prefixed/suffixed origins. These can usually be easily exploited despite an honest attempt to limit exposure. This does allow for accepting traffic from any origin (*), but should ONLY be used when truly ANY site should be able to access the content.

At the end of the day, the premise of CORS relies entirely on the correct behavior of the browser, which cannot be relied upon as any kind of silver bullet solution (defense in depth).

Source: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

func EnableContentSecurityPolicy

func EnableContentSecurityPolicy(opts ...CSPOption) SecurityOption

EnableContentSecurityPolicy allows specifying content security policies that will be applied in the SecurityPolicies middleware.

CSP policies inform the browser about what content sources should be trusted for what content class. The security of a CSP relies entirely upon the correct enforcement by the browser, so additional mechanisms and policies should be used (defense in depth). This helps prevent the "easy" methods of loading untrusted content into a page, it's not foolproof.

Source: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP

func EnableStrictTransportSecurity

func EnableStrictTransportSecurity(maxAge time.Duration, includeSubdomains bool) SecurityOption

EnableStrictTransportSecurity enables sending the HTTP Strict Transport Security (HSTS) header to ensure that connections are established with TLS. This helps to prevent man-in-the-middle (MITM) attacks against a previously visited web server, because the user agent will cache this header for max-age seconds. Of course, enabling this necessitates serving content using TLS.

Note that 'preload' is currently not part of the specification, and thus not supported.

Source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security

type SecurityPolicies

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

func NewSecurityPolicies

func NewSecurityPolicies(opts ...SecurityOption) (*SecurityPolicies, error)

func (*SecurityPolicies) Middleware

func (s *SecurityPolicies) Middleware(next http.Handler) http.Handler