Cookies and state

Active contributors: Daniel Stenberg, Viktor Szakats

Purpose

libcurl maintains several persistent (or near-persistent) caches that affect future requests: cookies, HSTS, alt-svc, ETag conditional requests, and PSL (Public Suffix List). All of them can be loaded from and saved to disk and shared across handles via the share interface.

Cache	Source	Public option	File format
Cookies	lib/cookie.c	CURLOPT_COOKIEFILE/CURLOPT_COOKIEJAR	Netscape cookie file format
HSTS	lib/hsts.c	CURLOPT_HSTS/CURLOPT_HSTS_CTRL	Custom plain-text
Alt-Svc	lib/altsvc.c	CURLOPT_ALTSVC/CURLOPT_ALTSVC_CTRL	Custom plain-text
ETag	lib/file.c + tool	--etag-save/--etag-compare	One-line file
PSL	lib/psl.c	(libpsl)	Compiled-in via libpsl
Netrc	lib/netrc.c	CURLOPT_NETRC	Standard ~/.netrc

Cookies

lib/cookie.c (~48 KB) is curl's cookie engine: it parses incoming Set-Cookie headers (RFC 6265-ish), maintains a hashed jar, applies scope and lifetime checks, and renders matching cookies into outgoing Cookie headers.

Storage

The jar is a hash of (domain, path, name) → struct Cookie (lib/cookie.h). Each cookie carries the secure, httponly, prefix-secure, prefix-host, samesite, expiration, and creation-time metadata defined by RFC 6265-bis.

Public Suffix List

To prevent setting a cookie for .com or .co.uk, curl consults libpsl through lib/psl.c. If libpsl is not compiled in, this check is skipped (with a documented security caveat in docs/SSLCERTS.md and docs/HTTP-COOKIES.md).

File formats

• --cookie file.txt (CURLOPT_COOKIEFILE) reads either the Netscape format ("Mozilla cookie jar") or HTTP-style Cookie: headers.
• --cookie-jar file.txt (CURLOPT_COOKIEJAR) writes the Netscape format.

The jar's serializer/deserializer is in lib/cookie.c.

Sharing

curl_share_setopt(sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE) lets multiple handles see the same jar.

HSTS

lib/hsts.c (~17 KB) caches HTTP Strict Transport Security data: hosts that promised to serve only HTTPS for a given duration. When a transfer is about to use http://example.com, curl checks the HSTS cache before proxying or connecting and rewrites to https:// if applicable.

The on-disk format is a simple line-per-host text file. Atomic writes use Curl_fopen from curlx.

The user-visible side is documented in docs/HSTS.md. Reading and writing happens at multi-init and multi-cleanup time when CURLOPT_HSTS is set; programmatic access is via curl_easy_setopt(CURLOPT_HSTSREADFUNCTION, …) / curl_easy_setopt(CURLOPT_HSTSWRITEFUNCTION, …) for applications that store HSTS in a database.

Alt-Svc

lib/altsvc.c (~20 KB) caches the Alt-Svc header sent by HTTP/2 and HTTP/3 servers, telling the client "for this origin, alternative endpoints are available". Curl uses this to opportunistically jump to HTTP/3 on a subsequent request.

Like HSTS, alt-svc is plain-text, persisted via CURLOPT_ALTSVC, and documented in docs/ALTSVC.md.

ETag conditional requests

--etag-save out.etag saves the ETag from the response; --etag-compare in.etag adds an If-None-Match header on the next request. Implementation in src/tool_operate.c and src/tool_filetime.c.

Netrc

lib/netrc.c parses the standard ~/.netrc file (or the file pointed to by CURLOPT_NETRC_FILE). Credentials sourced from netrc are applied in Curl_setopt/Curl_input_auth time, not at parse time, so they only affect transfers that have not been given explicit credentials.

Integration points

• HTTP handler: cookie injection / extraction happens in lib/http.c::Curl_http_output_cookies and Curl_http_input_cookies.
• URL setup: HSTS rewriting happens in lib/url.c before the connection cache key is computed.
• HTTP/2 / HTTP/3 path: alt-svc upgrade is consulted alongside the URL during connection setup.
• Share handle: cookies, HSTS, and DNS each have a CURL_LOCK_DATA_* flag.

Entry points for modification

• Cookie scoring/scope rule → lib/cookie.c::Curl_cookie_match
• New on-disk cookie format → it would live in lib/cookie.c. Maintainers strongly prefer keeping the Netscape format the only on-disk format.
• HSTS persistence backend → callbacks CURLOPT_HSTSREAD/WRITE/FUNCTION
• Alt-Svc persistence → CURLOPT_ALTSVC plus lib/altsvc.c::Curl_altsvc_save/_load
• PSL behaviour → lib/psl.c and the libpsl version

Related pages

• HTTP/2 and HTTP/3 — alt-svc piloting
• Authentication — netrc credential lookup
• Protocol handlers