From 96ffb570407fe142a3756735a343ba17b089cdce Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 9 Dec 2024 08:52:01 +0100 Subject: [PATCH] docs: bring back ALTSVC.md and HSTS.md This partly reverts 0e06603b2318356ba78b2f These file formats are not properly documented elsewhere, plus the website uses these files to populate the documentation pages to which users end up via the URLs that are mentioned within the alt-svc and hsts files. Fixes #15705 Reported-by: Jeffrey Bosboom Closes #15706 --- docs/ALTSVC.md | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/HSTS.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/Makefile.am | 2 ++ 3 files changed, 93 insertions(+) create mode 100644 docs/ALTSVC.md create mode 100644 docs/HSTS.md diff --git a/docs/ALTSVC.md b/docs/ALTSVC.md new file mode 100644 index 0000000000..bcdf565074 --- /dev/null +++ b/docs/ALTSVC.md @@ -0,0 +1,43 @@ + + +# Alt-Svc + +curl features support for the Alt-Svc: HTTP header. + +## Enable Alt-Svc in build + +`./configure --enable-alt-svc` + +(enabled by default since 7.73.0) + +## Standard + +[RFC 7838](https://datatracker.ietf.org/doc/html/rfc7838) + +# Alt-Svc cache file format + +This is a text based file with one line per entry and each line consists of nine +space separated fields. + +## Example + + h2 quic.tech 8443 h3-22 quic.tech 8443 "20190808 06:18:37" 0 0 + +## Fields + +1. The ALPN id for the source origin +2. The hostname for the source origin +3. The port number for the source origin +4. The ALPN id for the destination host +5. The hostname for the destination host +6. The port number for the destination host +7. The expiration date and time of this entry within double quotes. The date format is "YYYYMMDD HH:MM:SS" and the time zone is GMT. +8. Boolean (1 or 0) if "persist" was set for this entry +9. Integer priority value (not currently used) + +If the hostname is an IPv6 numerical address, it is stored with brackets such +as `[::1]`. diff --git a/docs/HSTS.md b/docs/HSTS.md new file mode 100644 index 0000000000..85140ab30f --- /dev/null +++ b/docs/HSTS.md @@ -0,0 +1,48 @@ + + +# 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://datatracker.ietf.org/doc/html/rfc6797) + +## Behavior + +libcurl features an in-memory cache for HSTS hosts, so that subsequent +HTTP-only requests to a hostname present in the cache gets internally +"redirected" to the HTTPS version. + +## `curl_easy_setopt()` options: + + - `CURLOPT_HSTS_CTRL` - enable HSTS for this easy handle + - `CURLOPT_HSTS` - specify filename where to store the HSTS cache on close + (and possibly read from at startup) + +## curl command line options + + - `--hsts [filename]` - enable HSTS, use the file as HSTS cache. If filename + is `""` (no length) then no file is 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 includes subdomains. + +The time stamp is when the entry expires. + +## Possible future additions + + - `CURLOPT_HSTS_PRELOAD` - provide a set of HSTS hostnames to load first + - ability to save to something else than a file diff --git a/docs/Makefile.am b/docs/Makefile.am index e8f2d55bf3..d944111b1a 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -61,6 +61,7 @@ INTERNALDOCS = \ EXTRA_DIST = \ $(CURLPAGES) \ $(INTERNALDOCS) \ + ALTSVC.md \ BINDINGS.md \ BUG-BOUNTY.md \ BUGS.md \ @@ -82,6 +83,7 @@ EXTRA_DIST = \ GOVERNANCE.md \ HELP-US.md \ HISTORY.md \ + HSTS.md \ HTTP-COOKIES.md \ HTTP3.md \ INSTALL \ -- 2.47.3