From: Daniel Stenberg <daniel@haxx.se>
Date: Fri, 12 Jan 2024 15:50:44 +0000 (+0100)
Subject: docs: describe and highlight super cookies
X-Git-Tag: curl-8_6_0~95
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5da57193b732;p=thirdparty%2Fcurl.git

docs: describe and highlight super cookies

Reported-by: Yadhu Krishna M

Closes #12687
---

diff --git a/docs/HTTP-COOKIES.md b/docs/HTTP-COOKIES.md
index d6fd87d205..a91e824d54 100644
--- a/docs/HTTP-COOKIES.md
+++ b/docs/HTTP-COOKIES.md
@@ -34,6 +34,25 @@
   over plain HTTP for this host. curl does this to match how popular browsers
   work with secure cookies.
 
+## Super cookies
+
+  A single cookie can be set for a domain that matches multiple hosts. Like if
+  set for `example.com` it gets sent to both `aa.example.com` as well as
+  `bb.example.com`.
+
+  A challenge with this concept is that there are certain domains for which
+  cookies should not be allowed at all, because they are *Public
+  Suffixes*. Similarly, a client never accepts cookies set directly for the
+  top-level domain like for example `.com`. Cookies set for *too broad*
+  domains are generally referred to as *super cookies*.
+
+  If curl is built with PSL (**Public Suffix List**) support, it detects and
+  discards cookies that are specified for such suffix domains that should not
+  be allowed to have cookies.
+
+  if curl is *not* built with PSL support, it has no ability to stop super
+  cookies.
+
 ## Cookies saved to disk
 
   Netscape once created a file format for storing cookies on disk so that they
diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.d
index 23f3f466a3..601a1958c8 100644
--- a/docs/cmdline-opts/cookie.d
+++ b/docs/cmdline-opts/cookie.d
@@ -44,3 +44,8 @@ the Netscape format.
 Users often want to both read cookies from a file and write updated cookies
 back to a file, so using both --cookie and --cookie-jar in the same command
 line is common.
+
+If curl is built with PSL (*Public Suffix List*) support, it detects and
+discards cookies that are specified for such suffix domains that should not be
+allowed to have cookies. If curl is *not* built with PSL support, it has no
+ability to stop super cookies.
diff --git a/docs/libcurl/libcurl-security.3 b/docs/libcurl/libcurl-security.3
index 0d7bce06bb..4a0d76d66a 100644
--- a/docs/libcurl/libcurl-security.3
+++ b/docs/libcurl/libcurl-security.3
@@ -420,6 +420,13 @@ credentials may be left in freed data.
 .SH "Saving files"
 libcurl cannot protect against attacks where an attacker has write access to
 the same directory where libcurl is directed to save files.
+.SH "Cookies"
+If libcurl is built with PSL (**Public Suffix List**) support, it detects and
+discards cookies that are specified for such suffix domains that should not be
+allowed to have cookies.
+
+if libcurl is *not* built with PSL support, it has no ability to stop super
+cookies.
 .SH "Report Security Problems"
 Should you detect or just suspect a security problem in libcurl or curl,
 contact the project curl security team immediately. See
diff --git a/docs/libcurl/opts/CURLOPT_COOKIE.3 b/docs/libcurl/opts/CURLOPT_COOKIE.3
index e21d54c5f6..4d24fc21e2 100644
--- a/docs/libcurl/opts/CURLOPT_COOKIE.3
+++ b/docs/libcurl/opts/CURLOPT_COOKIE.3
@@ -62,6 +62,12 @@ automatically.
 
 The application does not have to keep the string around after setting this
 option.
+
+If libcurl is built with PSL (*Public Suffix List*) support, it detects and
+discards cookies that are specified for such suffix domains that should not be
+allowed to have cookies. If libcurl is *not* built with PSL support, it has no
+ability to stop super cookies. PSL support is identified by the
+\fBCURL_VERSION_PSL\fP feature bit returned by \fIcurl_version_info(3)\fP.
 .SH DEFAULT
 NULL, no cookies
 .SH PROTOCOLS