secureheader

README

Package secureheader adds some HTTP header fields widely
considered to improve safety of HTTP requests.

See http://godoc.org/github.com/kr/secureheader for more.

Contributions from web application platforms are
encouraged. If you have different default behavior that
would make better sense in your environment, send a pull
request! See heroku.go for an example.

Documentation

Overview

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.

Example

package main

import (
	"net/http"

	"github.com/kr/secureheader"
)

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

Example (Custom)

package main

import (
	"net/http"

	"github.com/kr/secureheader"
)

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

Index

• Variables
• func ShouldUseForwardedProto() bool
• type Config
  • func Handler(h http.Handler) *Config
  • func (c *Config) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type FramePolicy
  • func AllowFrom(url string) FramePolicy

Examples

• Package
• Package (Custom)

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.

Functions

func ShouldUseForwardedProto

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.

Types

type Config

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

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

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

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

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.