generic-library/curl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

docs: Warn about any-domain cookies and multiple transfers

Browse Source 
- 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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/curl.1
View File

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

8
docs/libcurl/curl_easy_getinfo.3
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

8
docs/libcurl/opts/CURLOPT_COOKIEFILE.3
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

6
docs/libcurl/opts/CURLOPT_COOKIEJAR.3
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), "

17
docs/libcurl/opts/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), "