Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
Showing
38 changed files
with
1,122 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
Long: hsts | ||
Arg: <file name> | ||
Protocols: HTTPS | ||
Help: Enable HSTS with this cache file | ||
Added: 7.74.0 | ||
Category: http | ||
--- | ||
WARNING: this option is experimental. Do not use in production. | ||
|
||
This option enables HSTS for the transfer. If the file name points to an | ||
existing HSTS cache file, that will be used. After a completed transfer, the | ||
cache will be saved to the file name again if it has been modified. | ||
|
||
Specify a "" file name (zero length) to avoid loading/saving and make curl | ||
just handle HSTS in memory. | ||
|
||
If this option is used several times, curl will load contents from all the | ||
files but the last one will be used for saving. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
.\" ************************************************************************** | ||
.\" * _ _ ____ _ | ||
.\" * Project ___| | | | _ \| | | ||
.\" * / __| | | | |_) | | | ||
.\" * | (__| |_| | _ <| |___ | ||
.\" * \___|\___/|_| \_\_____| | ||
.\" * | ||
.\" * Copyright (C) 2020, Daniel Stenberg, <daniel@haxx.se>, et al. | ||
.\" * | ||
.\" * This software is licensed as described in the file COPYING, which | ||
.\" * you should have received as part of this distribution. The terms | ||
.\" * are also available at https://curl.haxx.se/docs/copyright.html. | ||
.\" * | ||
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell | ||
.\" * copies of the Software, and permit persons to whom the Software is | ||
.\" * furnished to do so, under the terms of the COPYING file. | ||
.\" * | ||
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY | ||
.\" * KIND, either express or implied. | ||
.\" * | ||
.\" ************************************************************************** | ||
.\" | ||
.TH CURLOPT_HSTS 3 "5 Feb 2019" "libcurl 7.74.0" "curl_easy_setopt options" | ||
.SH NAME | ||
CURLOPT_HSTS \- set HSTS cache file name | ||
.SH SYNOPSIS | ||
.nf | ||
#include <curl/curl.h> | ||
|
||
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS, char *filename); | ||
.fi | ||
.SH EXPERIMENTAL | ||
Warning: this feature is early code and is marked as experimental. It can only | ||
be enabled by explicitly telling configure with \fB--enable-hsts\fP. You are | ||
advised to not ship this in production before the experimental label is | ||
removed. | ||
.SH DESCRIPTION | ||
Make the \fIfilename\fP point to a file name to load an existing HSTS cache | ||
from, and to store the cache in when the easy handle is closed. Setting a file | ||
name with this option will also enable HSTS for this handle (the equivalent of | ||
setting \fICURLHSTS_ENABLE\fP with \fICURLOPT_HSTS_CTRL(3)\fP). | ||
|
||
If the given file does not exist or contains no HSTS entries at startup, the | ||
HSTS cache will simply start empty. Setting the file name to NULL or "" will | ||
only enable HSTS without reading from or writing to any file. | ||
|
||
If this option is set multiple times, libcurl will load cache entries from | ||
each given file but will only store the last used name for later writing. | ||
.SH DEFAULT | ||
NULL, no file name | ||
.SH PROTOCOLS | ||
HTTPS and HTTP | ||
.SH EXAMPLE | ||
.nf | ||
CURL *curl = curl_easy_init(); | ||
if(curl) { | ||
curl_easy_setopt(curl, CURLOPT_HSTS, "/home/user/.hsts-cache"); | ||
curl_easy_perform(curl); | ||
} | ||
.fi | ||
.SH AVAILABILITY | ||
Added in 7.74.0 | ||
.SH RETURN VALUE | ||
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. | ||
.SH "SEE ALSO" | ||
.BR CURLOPT_HSTS_CTRL "(3), " CURLOPT_ALTSVC "(3), " CURLOPT_RESOLVE "(3), " |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,73 @@ | ||
.\" ************************************************************************** | ||
.\" * _ _ ____ _ | ||
.\" * Project ___| | | | _ \| | | ||
.\" * / __| | | | |_) | | | ||
.\" * | (__| |_| | _ <| |___ | ||
.\" * \___|\___/|_| \_\_____| | ||
.\" * | ||
.\" * Copyright (C) 2020, Daniel Stenberg, <daniel@haxx.se>, et al. | ||
.\" * | ||
.\" * This software is licensed as described in the file COPYING, which | ||
.\" * you should have received as part of this distribution. The terms | ||
.\" * are also available at https://curl.haxx.se/docs/copyright.html. | ||
.\" * | ||
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell | ||
.\" * copies of the Software, and permit persons to whom the Software is | ||
.\" * furnished to do so, under the terms of the COPYING file. | ||
.\" * | ||
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY | ||
.\" * KIND, either express or implied. | ||
.\" * | ||
.\" ************************************************************************** | ||
.\" | ||
.TH CURLOPT_HSTS_CTRL 3 "4 Sep 2020" "libcurl 7.74.0" "curl_easy_setopt options" | ||
.SH NAME | ||
CURLOPT_HSTS_CTRL \- control HSTS behavior | ||
.SH SYNOPSIS | ||
.nf | ||
#include <curl/curl.h> | ||
|
||
#define CURLHSTS_ENABLE (1<<0) | ||
#define CURLHSTS_READONLYFILE (1<<1) | ||
|
||
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS_CTRL, long bitmask); | ||
.fi | ||
.SH EXPERIMENTAL | ||
Warning: this feature is early code and is marked as experimental. It can only | ||
be enabled by explicitly telling configure with \fB--enable-hsts\fP. You are | ||
advised to not ship this in production before the experimental label is | ||
removed. | ||
.SH DESCRIPTION | ||
HSTS (HTTP Strict Transport Security) means that an HTTPS server can instruct | ||
the client to not contact it again over clear-text HTTP for a certain period | ||
into the future. libcurl will then automatically redirect HTTP attempts to | ||
such hosts to instead use HTTPS. This is done by libcurl retaining this | ||
knowledge in an in-memory cache. | ||
|
||
Populate the long \fIbitmask\fP with the correct set of features to instruct | ||
libcurl how to handle HSTS for the transfers using this handle. | ||
.SH BITS | ||
.IP "CURLHSTS_ENABLE" | ||
Enable the in-memory HSTS cache for this handle. | ||
.IP "CURLHSTS_READONLYFILE" | ||
Make the HSTS file (if specified) read-only - makes libcurl not save the cache | ||
to the file when closing the handle. | ||
.SH DEFAULT | ||
0. HSTS is disabled by default. | ||
.SH PROTOCOLS | ||
HTTPS and HTTP | ||
.SH EXAMPLE | ||
.nf | ||
CURL *curl = curl_easy_init(); | ||
if(curl) { | ||
curl_easy_setopt(curl, CURLOPT_HSTS_CTRL, CURLHSTS_ENABLE); | ||
curl_easy_perform(curl); | ||
} | ||
.fi | ||
.SH AVAILABILITY | ||
Added in 7.74.0 | ||
.SH RETURN VALUE | ||
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. | ||
.SH "SEE ALSO" | ||
.BR CURLOPT_HSTS "(3), " CURLOPT_CONNECT_TO "(3), " CURLOPT_RESOLVE "(3), " | ||
.BR CURLOPT_ALTSVC "(3), " |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.