1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HSTS_CTRL
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_ALTSVC (3)
9  - CURLOPT_CONNECT_TO (3)
10  - CURLOPT_HSTS (3)
11  - CURLOPT_RESOLVE (3)
12---
13
14# NAME
15
16CURLOPT_HSTS_CTRL - control HSTS behavior
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23#define CURLHSTS_ENABLE       (1<<0)
24#define CURLHSTS_READONLYFILE (1<<1)
25
26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS_CTRL, long bitmask);
27~~~
28
29# DESCRIPTION
30
31HSTS (HTTP Strict Transport Security) means that an HTTPS server can instruct
32the client to not contact it again over clear-text HTTP for a certain period
33into the future. libcurl then automatically redirects HTTP attempts to such
34hosts to instead use HTTPS. This is done by libcurl retaining this knowledge
35in an in-memory cache.
36
37Populate the long *bitmask* with the correct set of features to instruct
38libcurl how to handle HSTS for the transfers using this handle.
39
40# BITS
41
42## CURLHSTS_ENABLE
43
44Enable the in-memory HSTS cache for this handle.
45
46## CURLHSTS_READONLYFILE
47
48Make the HSTS file (if specified) read-only - makes libcurl not save the cache
49to the file when closing the handle.
50
51# DEFAULT
52
530. HSTS is disabled by default.
54
55# PROTOCOLS
56
57HTTPS and HTTP
58
59# EXAMPLE
60
61~~~c
62int main(void)
63{
64  CURL *curl = curl_easy_init();
65  if(curl) {
66    curl_easy_setopt(curl, CURLOPT_HSTS_CTRL, (long)CURLHSTS_ENABLE);
67    curl_easy_perform(curl);
68  }
69}
70~~~
71
72# AVAILABILITY
73
74Added in 7.74.0
75
76# RETURN VALUE
77
78Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
79