curl/docs/HSTS.md

# HSTS support

HTTP Strict-Transport-Security. Added as experimental in curl
7.74.0. Supported "for real" since 7.77.0.

## Standard

[HTTP Strict Transport Security](https://tools.ietf.org/html/rfc6797)

## Behavior

libcurl features an in-memory cache for HSTS hosts, so that subsequent
HTTP-only requests to a host name present in the cache will get internally
"redirected" to the HTTPS version.

## `curl_easy_setopt()` options:

 - `CURLOPT_HSTS_CTRL` - enable HSTS for this easy handle
 - `CURLOPT_HSTS` - specify file name where to store the HSTS cache on close
  (and possibly read from at startup)

## curl cmdline options

 - `--hsts [filename]` - enable HSTS, use the file as HSTS cache. If filename
   is `""` (no length) then no file will be used, only in-memory cache.

## HSTS cache file format

Lines starting with `#` are ignored.

For each hsts entry:

    [host name] "YYYYMMDD HH:MM:SS"

The `[host name]` is dot-prefixed if it is a includeSubDomain.

The time stamp is when the entry expires.

I considered using wget's file format for the HSTS cache. However, they store the time stamp as the epoch (number of seconds since 1970) and I strongly disagree with using that format. Instead I opted to use a format similar to the curl alt-svc cache file format.

## Possible future additions

 - `CURLOPT_HSTS_PRELOAD` - provide a set of preloaded HSTS host names
 - ability to save to something else than a file
hsts: add support for Strict-Transport-Security - enable in the build (configure) - header parsing - host name lookup - unit tests for the above - CI build - CURL_VERSION_HSTS bit - curl_version_info support - curl -V output - curl-config --features - CURLOPT_HSTS_CTRL - man page for CURLOPT_HSTS_CTRL - curl --hsts (sets CURLOPT_HSTS_CTRL and works with --libcurl) - man page for --hsts - save cache to disk - load cache from disk - CURLOPT_HSTS - man page for CURLOPT_HSTS - added docs/HSTS.md - fixed --version docs - adjusted curl_easy_duphandle Closes #5896 2020-11-03 06:17:01 +08:00			`# HSTS support`

HSTS: not experimental anymore 2021-05-28 18:34:07 +08:00			`HTTP Strict-Transport-Security. Added as experimental in curl`
			`7.74.0. Supported "for real" since 7.77.0.`
hsts: add support for Strict-Transport-Security - enable in the build (configure) - header parsing - host name lookup - unit tests for the above - CI build - CURL_VERSION_HSTS bit - curl_version_info support - curl -V output - curl-config --features - CURLOPT_HSTS_CTRL - man page for CURLOPT_HSTS_CTRL - curl --hsts (sets CURLOPT_HSTS_CTRL and works with --libcurl) - man page for --hsts - save cache to disk - load cache from disk - CURLOPT_HSTS - man page for CURLOPT_HSTS - added docs/HSTS.md - fixed --version docs - adjusted curl_easy_duphandle Closes #5896 2020-11-03 06:17:01 +08:00
			`## Standard`

			`[HTTP Strict Transport Security](https://tools.ietf.org/html/rfc6797)`

			`## Behavior`

			`libcurl features an in-memory cache for HSTS hosts, so that subsequent`
			`HTTP-only requests to a host name present in the cache will get internally`
			`"redirected" to the HTTPS version.`

			## `curl_easy_setopt()` options:

			- `CURLOPT_HSTS_CTRL` - enable HSTS for this easy handle
			- `CURLOPT_HSTS` - specify file name where to store the HSTS cache on close
			`(and possibly read from at startup)`

			`## curl cmdline options`

			- `--hsts [filename]` - enable HSTS, use the file as HSTS cache. If filename
			is `""` (no length) then no file will be used, only in-memory cache.

			`## HSTS cache file format`

			Lines starting with `#` are ignored.

			`For each hsts entry:`

			`[host name] "YYYYMMDD HH:MM:SS"`

			The `[host name]` is dot-prefixed if it is a includeSubDomain.

			`The time stamp is when the entry expires.`

			`I considered using wget's file format for the HSTS cache. However, they store the time stamp as the epoch (number of seconds since 1970) and I strongly disagree with using that format. Instead I opted to use a format similar to the curl alt-svc cache file format.`

			`## Possible future additions`

			- `CURLOPT_HSTS_PRELOAD` - provide a set of preloaded HSTS host names
			`- ability to save to something else than a file`