Artifactspublic-v0

curl

master
ply4 git calls152 ms288 KiB2 cachedprotocol v2
105 lines2.9 KiBRaw

NAME

CURLOPT_HSTS - HSTS cache filename

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS, char *filename);

DESCRIPTION

Make the filename point to a filename to load an existing HSTS cache from, and to store the cache in when the easy handle is closed. Setting a filename with this option also enables HSTS for this handle (the equivalent of setting CURLHSTS_ENABLE with CURLOPT_HSTS_CTRL(3)).

If the given file does not exist or contains no HSTS entries at startup, the HSTS cache starts empty. Setting the filename to NULL allows HSTS without reading from or writing to any file. NULL also makes libcurl clear the list of files to read HSTS data from, if any such were previously set.

If this option is set multiple times, libcurl loads cache entries from each given file but only stores the last used name for later writing.

Since libcurl 8.20.0, each in-memory HSTS cache (per easy handle or shared cache) holds no more than the most recently added 10,000 HSTS hostnames.

FILE FORMAT

The HSTS cache is saved to and loaded from a text file with one entry per physical line. Each line in the file has the following format:

[host] [stamp]

[host] is the domain name for the entry and the name is dot-prefixed if it is an entry valid for all subdomains to the name as well or only for the exact name.

[stamp] is the time (in UTC) when the entry expires and it uses the format "YYYYMMDD HH:MM:SS".

Lines starting with "#" are treated as comments and are ignored. There is currently no length or size limit.

DEFAULT

NULL, no filename

SECURITY CONCERNS

We strongly urge users to stick to https:// URLs, which makes this option unnecessary.

libcurl cannot fully protect against attacks where an attacker has write access to the same directory where it is directed to save files. This is particularly sensitive if you save files using elevated privileges.

libcurl creates the file to store HSTS data in using default file permissions, meaning that on *nix systems you may need to restrict your umask to prevent other users on the same system to access the file.

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    curl_easy_setopt(curl, CURLOPT_HSTS, "/home/user/.hsts-cache");
    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
}

%AVAILABILITY%

RETURN VALUE

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HSTS
5Section: 3
6Source: libcurl
7Protocol:
8 - HTTP
9See-also:
10 - CURLOPT_ALTSVC (3)
11 - CURLOPT_HSTS_CTRL (3)
12 - CURLOPT_RESOLVE (3)
13Added-in: 7.74.0
14---
16# NAME
18CURLOPT_HSTS - HSTS cache filename
20# SYNOPSIS
22~~~c
23#include <curl/curl.h>
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS, char *filename);
26~~~
28# DESCRIPTION
30Make the *filename* point to a filename to load an existing HSTS cache from,
31and to store the cache in when the easy handle is closed. Setting a filename
32with this option also enables HSTS for this handle (the equivalent of setting
33*CURLHSTS_ENABLE* with CURLOPT_HSTS_CTRL(3)).
35If the given file does not exist or contains no HSTS entries at startup, the
36HSTS cache starts empty. Setting the filename to NULL allows HSTS without
37reading from or writing to any file. NULL also makes libcurl clear the list of
38files to read HSTS data from, if any such were previously set.
40If this option is set multiple times, libcurl loads cache entries from each
41given file but only stores the last used name for later writing.
43Since libcurl 8.20.0, each in-memory HSTS cache (per easy handle or shared
44cache) holds no more than the most recently added 10,000 HSTS hostnames.
46# FILE FORMAT
48The HSTS cache is saved to and loaded from a text file with one entry per
49physical line. Each line in the file has the following format:
51 [host] [stamp]
53[host] is the domain name for the entry and the name is dot-prefixed if it is
54an entry valid for all subdomains to the name as well or only for the exact
55name.
57[stamp] is the time (in UTC) when the entry expires and it uses the format
58"YYYYMMDD HH:MM:SS".
60Lines starting with "#" are treated as comments and are ignored. There is
61currently no length or size limit.
63# DEFAULT
65NULL, no filename
67# SECURITY CONCERNS
69We strongly urge users to stick to `https://` URLs, which makes this option
70unnecessary.
72libcurl cannot fully protect against attacks where an attacker has write
73access to the same directory where it is directed to save files. This is
74particularly sensitive if you save files using elevated privileges.
76libcurl creates the file to store HSTS data in using default file permissions,
77meaning that on *nix systems you may need to restrict your umask to prevent
78other users on the same system to access the file.
80# %PROTOCOLS%
82# EXAMPLE
84~~~c
85int main(void)
87 CURL *curl = curl_easy_init();
88 if(curl) {
89 CURLcode result;
90 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
91 curl_easy_setopt(curl, CURLOPT_HSTS, "/home/user/.hsts-cache");
92 result = curl_easy_perform(curl);
93 curl_easy_cleanup(curl);
94 }
96~~~
98# %AVAILABILITY%
100# RETURN VALUE
102curl_easy_setopt(3) returns a CURLcode indicating success or error.
104CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
105libcurl-errors(3).
Diagnostics4 git calls · 152 ms
CallStatusSizeTime0152 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2001.6 KiB146 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=146
git.response.bytes=1598
git.response.cache=MISS
git.response.duration_ms=146
git.fetch.wants=12efff50bc79c68eb68e57349125ca52b581c98c
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1598
git.pkt.payload.max=1577
git.sideband.band1.bytes=1576
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e34d3f1f468a31
Request
5faa1665…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format