1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HSTS
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_ALTSVC (3)
9  - CURLOPT_HSTS_CTRL (3)
10  - CURLOPT_RESOLVE (3)
11---
12
13# NAME
14
15CURLOPT_HSTS - HSTS cache file name
16
17# SYNOPSIS
18
19~~~c
20#include <curl/curl.h>
21
22CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS, char *filename);
23~~~
24
25# DESCRIPTION
26
27Make the *filename* point to a filename to load an existing HSTS cache
28from, and to store the cache in when the easy handle is closed. Setting a file
29name with this option also enables HSTS for this handle (the equivalent of
30setting *CURLHSTS_ENABLE* with CURLOPT_HSTS_CTRL(3)).
31
32If the given file does not exist or contains no HSTS entries at startup, the
33HSTS cache simply starts empty. Setting the filename to NULL or "" only
34enables HSTS without reading from or writing to any file.
35
36If this option is set multiple times, libcurl loads cache entries from each
37given file but only stores the last used name for later writing.
38
39# FILE FORMAT
40
41The HSTS cache is saved to and loaded from a text file with one entry per
42physical line. Each line in the file has the following format:
43
44[host] [stamp]
45
46[host] is the domain name for the entry and the name is dot-prefixed if it is
47an entry valid for all subdomains to the name as well or only for the exact
48name.
49
50[stamp] is the time (in UTC) when the entry expires and it uses the format
51"YYYYMMDD HH:MM:SS".
52
53Lines starting with "#" are treated as comments and are ignored. There is
54currently no length or size limit.
55
56# DEFAULT
57
58NULL, no file name
59
60# PROTOCOLS
61
62HTTPS and HTTP
63
64# EXAMPLE
65
66~~~c
67int main(void)
68{
69  CURL *curl = curl_easy_init();
70  if(curl) {
71    curl_easy_setopt(curl, CURLOPT_HSTS, "/home/user/.hsts-cache");
72    curl_easy_perform(curl);
73  }
74}
75~~~
76
77# AVAILABILITY
78
79Added in 7.74.0
80
81# RETURN VALUE
82
83Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
84