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
This commit is contained in:
Jay Satiro
2015-09-03 02:35:11 -04:00
parent b604b7f040
commit cb6a07fed0
5 changed files with 40 additions and 13 deletions

View File

@@ -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

View File

@@ -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

View File

@@ -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), "

View File

@@ -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), "