docs: Warn about any-domain cookies and multiple transfers

- Warn that cookies without a domain are sent to any domain:
CURLOPT_COOKIELIST, CURLOPT_COOKIEFILE, --cookie

- Note that imported Set-Cookie cookies without a domain are no longer
exported:
CURLINFO_COOKIELIST, CURLOPT_COOKIEJAR, --cookie-jar

diff --git a/docs/curl.1 b/docs/curl.1
index b49c492b2ca27ec72ed7baa1ad4ee89a5f25440b..6b3feab33aa22d610c719750c7525d05e08a9ae0 100644 (file)
--- a/docs/curl.1
+++ b/docs/curl.1
@@ -213,7 +213,7 @@ be in the format "NAME1=VALUE1; NAME2=VALUE2".
 
 If no '=' symbol is used in the line, it is treated as a filename to use to
 read previously stored cookie lines from, which should be used in this session
-if they match. Using this method also activates the "cookie parser" which will
+if they match. Using this method also activates the cookie engine which will
 make curl record incoming cookies too, which may be handy if you're using this
 in combination with the \fI-L, --location\fP option. The file format of the
 file to read cookies from should be plain HTTP headers or the Netscape/Mozilla
@@ -223,6 +223,15 @@ The file specified with \fI-b, --cookie\fP is only used as input. No cookies
 will be written to the file. To store cookies, use the \fI-c, --cookie-jar\fP
 option.
 
+Exercise caution if you are using this option and multiple transfers may occur.
+If you use the NAME1=VALUE1; format, or in a file use the Set-Cookie format and
+don't specify a domain, then the cookie is sent for any domain (even after
+redirects are followed) and cannot be modified by a server-set cookie. If the
+cookie engine is enabled and a server sets a cookie of the same name then both
+will be sent on a future transfer to that server, likely not what you intended.
+To address these issues set a domain in Set-Cookie (doing that will include
+sub-domains) or use the Netscape format.
+
 If this option is used several times, the last one will be used.
 .IP "-B, --use-ascii"
 (FTP/LDAP) Enable ASCII transfer. For FTP, this can also be enforced by using
@@ -254,6 +263,9 @@ won't fail or even report an error clearly. Using -v will get a warning
 displayed, but that is the only visible feedback you get about this possibly
 lethal situation.
 
+Since 7.43.0 cookies that were imported in the Set-Cookie format without a
+domain name are not exported by this option.
+
 If this option is used several times, the last specified file name will be
 used.
 .IP "-C, --continue-at <offset>"

diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3
index e5ac5009b9f696d2745786411b31ed49ddeb2d17..e72c6ba7d6f3c8ecfd57e4c9af55a8b4d36c5af1 100644 (file)
--- a/docs/libcurl/curl_easy_getinfo.3
+++ b/docs/libcurl/curl_easy_getinfo.3
@@ -132,8 +132,12 @@ Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all
 cookies cURL knows (expired ones, too). Don't forget to
 \fIcurl_slist_free_all(3)\fP the list after it has been used.  If there are no
 cookies (cookies for the handle have not been enabled or simply none have been
-received) 'struct curl_slist *' will be set to point to NULL. (Added in
-7.14.1)
+received) 'struct curl_slist *' will be set to point to NULL.
+
+Since 7.43.0 cookies that were imported in the Set-Cookie format without a
+domain name are not exported by this option.
+
+(Added in 7.14.1)
 .IP CURLINFO_LASTSOCKET
 Pass a pointer to a long to receive the last socket used by this curl
 session. If the socket is no longer valid, -1 is returned. When you finish

diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3
index a4c3b02b3ca3bba3b69005c637afe6c64c6f4033..643d8e32f62988e05cf8da7ccd272d89c4a0903c 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3
+++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3
@@ -43,6 +43,14 @@ cookies.
 This option only \fBreads\fP cookies. To make libcurl write cookies to file,
 see \fICURLOPT_COOKIEJAR(3)\fP.
 
+Exercise caution if you are using this option and multiple transfers may occur.
+If you use the Set-Cookie format and don't specify a domain then the cookie is
+sent for any domain (even after redirects are followed) and cannot be modified
+by a server-set cookie. If a server sets a cookie of the same name then both
+will be sent on a future transfer to that server, likely not what you intended.
+To address these issues set a domain in Set-Cookie (doing that will include
+sub-domains) or use the Netscape format.
+
 If you use this option multiple times, you just add more files to read.
 Subsequent files will add more cookies.
 .SH DEFAULT

diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3
index 936d4d8a46e9e502a64c5411969e2d5e3696a70e..e21540b3ad8a23aed52a070f088e16a1d5684d92 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3
+++ b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3
@@ -43,6 +43,9 @@ If the cookie jar file can't be created or written to (when the
 error for this. Using \fICURLOPT_VERBOSE(3)\fP or
 \fICURLOPT_DEBUGFUNCTION(3)\fP will get a warning to display, but that is the
 only visible feedback you get about this possibly lethal situation.
+
+Since 7.43.0 cookies that were imported in the Set-Cookie format without a
+domain name are not exported by this option.
 .SH DEFAULT
 NULL
 .SH PROTOCOLS
@@ -55,4 +58,5 @@ Along with HTTP
 Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or
 CURLE_OUT_OF_MEMORY if there was insufficient heap space.
 .SH "SEE ALSO"
-.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIE "(3), " CURLOPT_COOKIELIST "(3), "
+.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIE "(3), "
+.BR CURLOPT_COOKIELIST "(3), "

diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 b/docs/libcurl/opts/CURLOPT_COOKIELIST.3
index 937c79db85f8a6f9717bbaf73be1d00018ff923f..ca30ec2a63ab1a3d743b4ccdec6835b07fff6f8e 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_COOKIELIST.3
+++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.3
@@ -36,16 +36,15 @@ Such a cookie can be either a single line in Netscape / Mozilla format or just
 regular HTTP-style header (Set-Cookie: ...) format. This will also enable the
 cookie engine. This adds that single cookie to the internal cookie store.
 
-If you use the Set-Cookie format and don't specify a domain then the cookie
-is sent for any domain and will not be modified. If a server sets a cookie of
-the same name (or maybe you've imported one) then both will be sent on a future
-transfer to that server, likely not what you intended. Either set a domain in
-Set-Cookie (doing that will include sub domains) or use the Netscape format as
+Exercise caution if you are using this option and multiple transfers may occur.
+If you use the Set-Cookie format and don't specify a domain then the cookie is
+sent for any domain (even after redirects are followed) and cannot be modified
+by a server-set cookie. If a server sets a cookie of the same name (or maybe
+you've imported one) then both will be sent on a future transfer to that
+server, likely not what you intended. To address these issues set a domain in
+Set-Cookie (doing that will include sub-domains) or use the Netscape format as
 shown in EXAMPLE.
 
-Starting in 7.43.0 the aforementioned any-domain cookies will not appear in the
-lists exported by \fICURLINFO_COOKIELIST(3)\fP and \fICURLOPT_COOKIEJAR(3)\fP.
-
 Additionally, there are commands available that perform actions if you pass in
 these exact strings:
 .IP ALL
@@ -117,4 +116,4 @@ RELOAD was added in 7.39.0
 Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
 CURLE_OUT_OF_MEMORY if there was insufficient heap space.
 .SH "SEE ALSO"
-.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), "  CURLOPT_COOKIE "(3), "
+.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), " CURLOPT_COOKIE "(3), "