hstspreload

README

HSTS Preload List – Utility Code

HSTS is HTTP Strict Transport Security, which is a policy system for web sites to express a desire only to be contacted over HTTPS.

See https://github.com/chromium/hstspreload.org for the submission site code.

Usage

To check if a domain satisfies the requirements for preloading (assuming $PATH contains $GOPATH/bin/):

go install github.com/chromium/hstspreload/...@latest
hstspreload preloadabledomain wikipedia.org

For full documentation, see https://godoc.org/github.com/chromium/hstspreload

Documentation

Overview

Package hstspreload has 3 parts:

- The `hstspreload` package with functions to check HSTS preload requirements.

- The `chromium/preloadlist` package, to query Chromium preload list state.

- The `hstspreload` command line tool.

Index

• func ParseHeaderString(headerString string) (HSTSHeader, Issues)
• type HSTSHeader
• type Issue
• type IssueCode
• type Issues
  • func EligibleDomain(domain string, policy preloadlist.PolicyType) (header *string, issues Issues)
  • func EligibleDomainResponse(domain string, policy preloadlist.PolicyType) (header *string, issues Issues, resp *http.Response)
  • func EligibleHeader(hstsHeader HSTSHeader, policy preloadlist.PolicyType) Issues
  • func EligibleHeaderString(headerString string, policy preloadlist.PolicyType) Issues
  • func EligibleResponse(resp *http.Response, policy preloadlist.PolicyType) (header *string, issues Issues)
  • func PreloadableDomain(domain string) (header *string, issues Issues)
  • func PreloadableHeader(hstsHeader HSTSHeader) Issues
  • func PreloadableHeaderString(headerString string) Issues
  • func PreloadableResponse(resp *http.Response) (header *string, issues Issues)
  • func RemovableDomain(domain string) (header *string, issues Issues)
  • func RemovableHeader(hstsHeader HSTSHeader) Issues
  • func RemovableHeaderString(headerString string) Issues
  • func RemovableResponse(resp *http.Response) (header *string, issues Issues)
  • func (iss Issues) GoString() string
  • func (iss Issues) MarshalJSON() ([]byte, error)
  • func (iss Issues) Match(wanted Issues) bool
• type MaxAge

Examples

• ParseHeaderString
• PreloadableDomain
• PreloadableResponse

Functions

func ParseHeaderString

func ParseHeaderString(headerString string) (HSTSHeader, Issues)

ParseHeaderString parses an HSTS header. ParseHeaderString will report syntax errors and warnings, but does NOT calculate whether the header value is semantically valid. (See PreloadableHeaderString() for that.)

To interpret the Issues that are returned, see the list of conventions in the documentation for Issues.

Example

hstsHeader, issues := ParseHeaderString("includeSubDomains; max-age;")
fmt.Printf("%v\n%v", hstsHeader, issues)

Types

type HSTSHeader

type HSTSHeader struct {
	// A MaxAge of `nil` indicates "not present".
	MaxAge            *MaxAge `json:"max_age,omitempty"`
	IncludeSubDomains bool    `json:"includeSubDomains"`
	Preload           bool    `json:"preload"`
}

An HSTSHeader stores the semantics of an HSTS header. https://tools.ietf.org/html/rfc6797#section-6.1

Note that the `preload` directive is not standardized yet: https://crbug.com/591212

type Issue

type Issue struct {
	// An error code.
	Code IssueCode `json:"code"`
	// A short summary (≈2-5 words) of the issue.
	Summary string `json:"summary"`
	// A detailed explanation with instructions for fixing.
	Message string `json:"message"`
}

An Issue is an error or a warning relating to a site's HSTS preload configuration.

type IssueCode

type IssueCode string

An IssueCode is a string identifier for an Issue. This allows other programs to perform analysis or take actions based on specific issues.

Examples: "domain.is_subdomain", "domain.tls.cannot_connect", "header.preloadable.max_age.below_1_year"

type Issues

type Issues struct {
	Errors   []Issue `json:"errors"`
	Warnings []Issue `json:"warnings"`
}

The Issues struct encapsulates a set of errors and warnings. By convention:

- Errors contains a list of errors that will prevent preloading.

- Warnings contains a list errors that are a good idea to fix, but are okay for preloading.

- Warning and errors will state at which level the issue occurred (e.g. header syntax, preload requirement checking, HTTP response checking, domain checking).

- If Issues is returned from a Check____() function without any errors or warnings, it means that the function passed all checks.

- The list of errors is not guaranteed to be exhaustive. In particular, fixing a given error (e.g. "could not connect to server") may bring another error to light (e.g. "HSTS header was not found").

func EligibleDomain

func EligibleDomain(domain string, policy preloadlist.PolicyType) (header *string, issues Issues)

EligibleDomain checks whether the domain passes HSTS preload requirements for Chromium when it was added using the requirements from PreloadableDomain

func EligibleDomainResponse

func EligibleDomainResponse(domain string, policy preloadlist.PolicyType) (header *string, issues Issues, resp *http.Response)

EligibleDomainResponse is like EligibleDomain, but also returns the initial response over HTTPS.

func EligibleHeader

func EligibleHeader(hstsHeader HSTSHeader, policy preloadlist.PolicyType) Issues

func EligibleHeaderString

func EligibleHeaderString(headerString string, policy preloadlist.PolicyType) Issues

EligibleHeaderString is a convenience function that calls ParseHeaderString() and then calls on EligibleHeader() the parsed header. It returns all issues from both calls, combined.

To interpret the result, see the list of conventions in the documentation for Issues.

func EligibleResponse

func EligibleResponse(resp *http.Response, policy preloadlist.PolicyType) (header *string, issues Issues)

EligibleResponse checks whether an resp has a single HSTS header that passes the preload requirements.

Iff a single HSTS header was received, `header` contains its value, else `header` is `nil`. To interpret `issues`, see the list of conventions in the documentation for Issues.

func PreloadableDomain

func PreloadableDomain(domain string) (header *string, issues Issues)

PreloadableDomain checks whether the domain passes HSTS preload requirements for Chromium. This includes:

- Serving a single HSTS header that passes header requirements.

- Using TLS settings that will not cause new problems for Chromium/Chrome users. (Example of a new problem: a missing intermediate certificate will turn an error page from overrideable to non-overridable on some mobile devices.)

Iff a single HSTS header was received, `header` contains its value, else `header` is `nil`. To interpret `issues`, see the list of conventions in the documentation for Issues.

Example

header, issues := PreloadableDomain("wikipedia.org")
if header != nil {
	fmt.Printf("Header: %s", *header)
}
fmt.Printf("Issues %v", issues)

func PreloadableHeader

func PreloadableHeader(hstsHeader HSTSHeader) Issues

PreloadableHeader checks whether hstsHeader satisfies all requirements for preloading in Chromium.

To interpret the result, see the list of conventions in the documentation for Issues.

Most of the time, you'll probably want to use PreloadableHeaderString() instead.

func PreloadableHeaderString

func PreloadableHeaderString(headerString string) Issues

PreloadableHeaderString is a convenience function that calls ParseHeaderString() and then calls on PreloadableHeader() the parsed header. It returns all issues from both calls, combined.

To interpret the result, see the list of conventions in the documentation for Issues.

func PreloadableResponse

func PreloadableResponse(resp *http.Response) (header *string, issues Issues)

PreloadableResponse checks whether an resp has a single HSTS header that passes the preload requirements.

Iff a single HSTS header was received, `header` contains its value, else `header` is `nil`. To interpret `issues`, see the list of conventions in the documentation for Issues.

Example

resp, err := http.Get("localhost:8080")
if err != nil {
	header, issues := PreloadableResponse(resp)
	if header != nil {
		fmt.Printf("Header: %s", *header)
	}
	fmt.Printf("Issues: %v", issues)
}

func RemovableDomain

func RemovableDomain(domain string) (header *string, issues Issues)

RemovableDomain checks whether the domain satisfies the requirements for being removed from the Chromium preload list:

- Serving a single valid HSTS header.

- The header must not contain the `preload` directive..

Iff a single HSTS header was received, `header` contains its value, else `header` is `nil`. To interpret `issues`, see the list of conventions in the documentation for Issues.

func RemovableHeader

func RemovableHeader(hstsHeader HSTSHeader) Issues

RemovableHeader checks whether the header satisfies all requirements for being removed from the Chromium preload list.

To interpret the result, see the list of conventions in the documentation for Issues.

Most of the time, you'll probably want to use RemovableHeaderString() instead.

func RemovableHeaderString

func RemovableHeaderString(headerString string) Issues

RemovableHeaderString is a convenience function that calls ParseHeaderString() and then calls on RemovableHeader() the parsed header. It returns all errors from ParseHeaderString() and all issues from RemovableHeader(). Note that *warnings* from ParseHeaderString() are ignored, since domains asking to be removed will often have minor errors that shouldn't affect removal. It's better to have a cleaner verdict in this case.

To interpret the result, see the list of conventions in the documentation for Issues.

func RemovableResponse

func RemovableResponse(resp *http.Response) (header *string, issues Issues)

RemovableResponse checks whether an resp has a single HSTS header that matches the requirements for removal from the HSTS preload list.

Iff a single HSTS header was received, `header` contains its value, else `header` is `nil`. To interpret `issues`, see the list of conventions in the documentation for Issues.

func (Issues) GoString

func (iss Issues) GoString() string

GoString formats `iss` with multiple lines and indentation. This is mainly used to provide output for unit tests in this project that can be pasted back into the relevant unit tess.

func (Issues) MarshalJSON

func (iss Issues) MarshalJSON() ([]byte, error)

MarshalJSON converts the given Issues to JSON, making sure that empty Errors/Warnings are converted to empty lists rather than null.

func (Issues) Match

func (iss Issues) Match(wanted Issues) bool

Match checks that the given issues match the `wanted` ones. This function always checks that both the lists of Errors and Warnings have the same number of `Issue`s with the same `IssuesCode`s codes in the same order. If any issues in `wanted` have the Summary or Message field set, the field is also compared against the field from the corresponding issue in `iss`.

type MaxAge

type MaxAge struct {
	Seconds uint64 `json:"seconds"`
}

MaxAge holds the max-age of an HSTS header in seconds. See https://tools.ietf.org/html/rfc6797#section-6.1.1