diff options
Diffstat (limited to 'docs/HSTS.md')
| -rw-r--r-- | docs/HSTS.md | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/docs/HSTS.md b/docs/HSTS.md new file mode 100644 index 000000000..c3f08393c --- /dev/null +++ b/docs/HSTS.md @@ -0,0 +1,44 @@ +# HSTS support + +curl features **EXPERIMENTAL** support for the Strict-Transport-Security: HTTP +header. Added in curl 7.74.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 |