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 d6fd87d2051f19e5907222b28664e029cd019b16..a91e824d5438cc639921789a3120bc401b03b72f 100644 (file)
--- 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 23f3f466a3ef5a14e2b51d3f9e73a9f07f041b72..601a1958c80a3d570c6ab415c2359b4d0ef1c20f 100644 (file)
--- 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 0d7bce06bb093cb6123166a417d6080d221ceb37..4a0d76d66a89f2f9fbf92822e3f7e7715b4d6d71 100644 (file)
--- 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 e21d54c5f67af6b56be7ac6ec598140109a51ddb..4d24fc21e23b3608bb950c4ddb19e04aa536aa71 100644 (file)
--- 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