diff options
Diffstat (limited to 'docs/libcurl/libcurl-tutorial.3')
| -rw-r--r-- | docs/libcurl/libcurl-tutorial.3 | 76 |
1 files changed, 55 insertions, 21 deletions
diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 72f002963..eb44502f3 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -249,9 +249,11 @@ complication for you. Given simply the URL to a file, libcurl will take care of all the details needed to get the file moved from one machine to another. .SH "Multi-threading Issues" -The first basic rule is that you must \fBnever\fP share a libcurl handle (be -it easy or multi or whatever) between multiple threads. Only use one handle in -one thread at a time. +The first basic rule is that you must \fBnever\fP simultaneously share a +libcurl handle (be it easy or multi or whatever) between multiple +threads. Only use one handle in one thread at any time. You can pass the +handles around among threads, but you must never use a single handle from more +than one thread at any given time. libcurl is completely thread safe, except for two issues: signals and SSL/TLS handlers. Signals are used for timing out name resolves (during DNS lookup) - @@ -283,6 +285,14 @@ yassl Required actions unknown. +axTLS + + Required actions unknown. + +Secure Transport + + The engine is fully thread-safe, and no additional steps are required. + When using multiple threads you should set the CURLOPT_NOSIGNAL option to 1 for all handles. Everything will or might work fine except that timeouts are not honored during the DNS lookup - which you can work around by building @@ -811,10 +821,6 @@ This header is required by HTTP 1.1 and even many 1.0 servers and should be the name of the server we want to talk to. This includes the port number if anything but default. -.IP "Pragma" -\&"no-cache". Tells a possible proxy to not grab a copy from the cache but to -fetch a fresh one. - .IP "Accept" \&"*/*". @@ -1151,13 +1157,13 @@ and install a CURLOPT_OPENSOCKETFUNCTION callback function in which addresses are sanitized before use. .IP "Private Resources" -A user who can control the DNS server of a domain being passed in within -a URL can change the address of the host to a local, private address -which the libcurl application will then use. e.g. The innocuous URL -http://fuzzybunnies.example.com/ could actually resolve to the IP address -of a server behind a firewall, such as 127.0.0.1 or 10.1.2.3 -Apps can mitigate against this by setting a CURLOPT_OPENSOCKETFUNCTION -and checking the address before a connection. +A user who can control the DNS server of a domain being passed in within a URL +can change the address of the host to a local, private address which a +server-side libcurl-using application could then use. e.g. the innocuous URL +http://fuzzybunnies.example.com/ could actually resolve to the IP address of a +server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Apps can mitigate +against this by setting a CURLOPT_OPENSOCKETFUNCTION and checking the address +before a connection. All the malicious scenarios regarding redirected URLs apply just as well to non-redirected URLs, if the user is allowed to specify an arbitrary URL @@ -1172,6 +1178,19 @@ IP address and port number for a server local to the app running libcurl but behind a firewall. Apps can mitigate against this by using the CURLOPT_FTP_SKIP_PASV_IP option or CURLOPT_FTPPORT. +.IP "IPv6 Addresses" +libcurl will normally handle IPv6 addresses transparently and just as easily +as IPv4 addresses. That means that a sanitizing function that filters out +addressses like 127.0.0.1 isn't sufficient--the equivalent IPv6 addresses ::1, +::, 0:00::0:1, ::127.0.0.1 and ::ffff:7f00:1 supplied somehow by an attacker +would all bypass a naive filter and could allow access to undesired local +resources. IPv6 also has special address blocks like link-local and site-local +that generally shouldn't be accessed by a server-side libcurl-using +application. A poorly-configured firewall installed in a data center, +organization or server may also be configured to limit IPv4 connections but +leave IPv6 connections wide open. In some cases, the CURL_IPRESOLVE_V4 option +can be used to limit resolved addresses to IPv4 only and bypass these issues. + .IP Uploads When uploading, a redirect can cause a local (or remote) file to be overwritten. Apps must not allow any unsanitized URL to be passed in @@ -1244,7 +1263,7 @@ using the Content-disposition: header to generate a file name. An application could also use CURLINFO_EFFECTIVE_URL to generate a file name from a server-supplied redirect URL. Special care must be taken to sanitize such names to avoid the possibility of a malicious server supplying one like -"/etc/passwd", "\autoexec.bat" or even ".bashrc". +"/etc/passwd", "\\autoexec.bat", "prn:" or even ".bashrc". .IP "Server Certificates" A secure application should never use the CURLOPT_SSL_VERIFYPEER option to @@ -1257,10 +1276,15 @@ validated certificates is potentially as insecure as a plain HTTP connection. On a related issue, be aware that even in situations like when you have problems with libcurl and ask someone for help, everything you reveal in order to get best possible help might also impose certain security related -risks. Host names, user names, paths, operating system specifics, etc (not to +risks. Host names, user names, paths, operating system specifics, etc. (not to mention passwords of course) may in fact be used by intruders to gain additional information of a potential target. +Be sure to limit access to application logs if they could hold private or +security-related data. Besides the obvious candidates like user names and +passwords, things like URLs, cookies or even file names could also hold +sensitive data. + To avoid this problem, you must of course use your common sense. Often, you can just edit out the sensitive data or just search/replace your true information with faked data. @@ -1297,9 +1321,7 @@ ones at any time), you start the transfers by calling \fIcurl_multi_perform(3)\fP is asynchronous. It will only execute as little as possible and then return back control to your program. It is designed to never -block. If it returns CURLM_CALL_MULTI_PERFORM you better call it again soon, -as that is a signal that it still has local data to send or remote data to -receive. +block. The best usage of this interface is when you do a select() on all possible file descriptors or sockets to know when to call libcurl again. This also @@ -1335,9 +1357,21 @@ to figure out success on each individual transfer. [ seeding, passwords, keys, certificates, ENGINE, ca certs ] .SH "Sharing Data Between Easy Handles" +You can share some data between easy handles when the easy interface is used, +and some data is share automatically when you use the multi interface. + +When you add easy handles to a multi handle, these easy handles will +automatically share a lot of the data that otherwise would be kept on a +per-easy handle basis when the easy interface is used. - [ fill in ] +The DNS cache is shared between handles within a multi handle, making +subsequent name resolving faster, and the connection pool that is kept to +better allow persistent connections and connection re-use is also shared. If +you're using the easy interface, you can still share these between specific +easy handles by using the share interface, see \fIlibcurl-share(3)\fP. +Some things are never shared automatically, not within multi handles, like for +example cookies so the only way to share that is with the share interface. .SH "Footnotes" .IP "[1]" |