docs: describe and highlight super cookies

Reported-by: Yadhu Krishna M

Closes #12687

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

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.

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

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