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)
- type MaxAge
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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)
Output:
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 ¶
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 ¶
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)
Output:
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 ¶
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 ¶
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)
}
Output:
func RemovableDomain ¶
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 ¶
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 ¶
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 ¶
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 ¶
MarshalJSON converts the given Issues to JSON, making sure that empty Errors/Warnings are converted to empty lists rather than null.
func (Issues) Match ¶
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
Source Files
Directories