secureheader: github.com/kr/secureheader Index | Examples | Files

package secureheader

import "github.com/kr/secureheader"

Package secureheader adds some HTTP header fields widely considered to improve safety of HTTP requests. These fields are documented as follows:

Strict Transport Security: https://tools.ietf.org/html/rfc6797
Frame Options:             https://tools.ietf.org/html/draft-ietf-websec-x-frame-options-00
Cross Site Scripting:      https://msdn.microsoft.com/en-us/library/dd565647%28v=vs.85%29.aspx
Content Type Options:      https://msdn.microsoft.com/en-us/library/ie/gg622941%28v=vs.85%29.aspx
Content Security Policy:   https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html

The easiest way to use this package:

http.ListenAndServe(addr, secureheader.DefaultConfig)

DefaultConfig is initialized with conservative (safer and more restrictive) behavior. If you want to change that, set its fields to different values before calling ListenAndServe. See the example code below.

This package was inspired by Twitter's secureheaders Ruby library. See https://github.com/twitter/secureheaders.

Code:

http.Handle("/", http.FileServer(http.Dir("/tmp")))
http.ListenAndServe(":80", secureheader.Handler(nil))

Code:

http.Handle("/", http.FileServer(http.Dir("/tmp")))
h := secureheader.Handler(http.DefaultServeMux)
h.HSTSIncludeSubdomains = false
h.FrameOptions = false
http.ListenAndServe(":80", h)

Index

Examples

Package Files

public.go secureheader.go

Variables

var DefaultConfig = &Config{
    HTTPSRedirect:          true,
    HTTPSUseForwardedProto: ShouldUseForwardedProto(),

    PermitClearLoopback: false,

    ContentTypeOptions: true,

    CSP:          false,
    CSPBody:      "default-src 'self'",
    CSPReportURI: "",

    CSPReportOnly:          false,
    CSPReportOnlyBody:      "default-src 'self'",
    CSPReportOnlyReportURI: "",

    HSTS:                  true,
    HSTSMaxAge:            300 * 24 * time.Hour,
    HSTSIncludeSubdomains: true,
    HSTSPreload:           false,

    FrameOptions:       true,
    FrameOptionsPolicy: Deny,

    XSSProtection:      true,
    XSSProtectionBlock: true,
}

DefaultConfig is initialized with conservative (safer and more restrictive) behavior.

func ShouldUseForwardedProto Uses

func ShouldUseForwardedProto() bool

ShouldUseForwardedProto returns whether to trust the X-Forwarded-Proto header field. DefaultConfig.HTTPSUseForwardedProto is initialized to this value.

This value depends on the particular environment where the package is built. It is currently true iff build constraint "heroku" is satisfied.

type Config Uses

type Config struct {
    // If true, redirects any request with scheme http to the
    // equivalent https URL.
    HTTPSRedirect          bool
    HTTPSUseForwardedProto bool

    // Allow cleartext (non-HTTPS) HTTP connections to a loopback
    // address, even if HTTPSRedirect is true.
    PermitClearLoopback bool

    // If true, sets X-Content-Type-Options to "nosniff".
    ContentTypeOptions bool

    // If true, send a Content-Security-Policy header. For more
    // information on deploying CSP, see for example
    // https://medium.com/sourceclear/content-security-policy-with-sentry-efb04f336f59
    // Dsiabled by default. If you set CSP = true,
    // the default policy is "default-src 'self'" and reporting is disabled.
    // To enable reporting, set CSPReportURI to your reporting endpoint.
    CSP          bool
    CSPBody      string
    CSPReportURI string

    // If true, the browser will report CSP violations, but won't enforce them
    // It *is* meaningful to set both headers
    // Content-Security-Policy *AND* Content-Security-Policy-Report-Only
    // and give them different bodys & report-uri's. The browser will
    // enforce the former, but only generate warnings on the latter.
    // Like CSPBody, the default is "default-src 'self'", and
    // Set CSPReportOnlyReportURI to your reporting endpoint.
    CSPReportOnly          bool
    CSPReportOnlyBody      string
    CSPReportOnlyReportURI string

    // If true, sets the HTTP Strict Transport Security header
    // field, which instructs browsers to send future requests
    // over HTTPS, even if the URL uses the unencrypted http
    // scheme.
    HSTS                  bool
    HSTSMaxAge            time.Duration
    HSTSIncludeSubdomains bool
    HSTSPreload           bool

    // If true, sets X-Frame-Options, to control when the request
    // should be displayed inside an HTML frame.
    FrameOptions       bool
    FrameOptionsPolicy FramePolicy

    // If true, sets X-XSS-Protection to "1", optionally with
    // "mode=block". See the official documentation, linked above,
    // for the meaning of these values.
    XSSProtection      bool
    XSSProtectionBlock bool

    // Used by ServeHTTP, after setting any extra headers, to
    // reply to the request. Next is typically nil, in which case
    // http.DefaultServeMux is used instead.
    Next http.Handler
}

func Handler Uses

func Handler(h http.Handler) *Config

Handler returns a new HTTP handler using the configuration in DefaultConfig, serving requests using h. If h is nil, it uses http.DefaultServeMux.

func (*Config) ServeHTTP Uses

func (c *Config) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP sets header fields on w according to the options in c, then either replies directly or runs c.Next to reply. Typically c.Next is nil, in which case http.DefaultServeMux is used instead.

type FramePolicy Uses

type FramePolicy string

FramePolicy tells the browser under what circumstances to allow the response to be displayed inside an HTML frame. There are three options:

Deny            do not permit display in a frame
SameOrigin      permit display in a frame from the same origin
AllowFrom(url)  permit display in a frame from the given url
const (
    Deny       FramePolicy = "DENY"
    SameOrigin FramePolicy = "SAMEORIGIN"
)

func AllowFrom Uses

func AllowFrom(url string) FramePolicy

AllowFrom returns a FramePolicy specifying that the requested resource should be included in a frame from only the given url.

Package secureheader imports 4 packages (graph) and is imported by 13 packages. Updated 2018-08-07. Refresh now. Tools for package owners.