← Back to branch summary

~ubuntu-branches/ubuntu/natty/curl/natty-proposed

« back to all changes in this revision

Viewing changes to docs/libcurl/libcurl-tutorial.3

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Schuldei
  • Date: 2009-05-24 21:12:19 UTC
  • mfrom: (1.1.12 upstream)
  • mto: (3.3.1 squeeze)
  • mto: This revision was merged to the branch mainline in revision 39.
  • Revision ID: james.westby@ubuntu.com-20090524211219-7jgcwuhl04ixuqsm
Tags: upstream-7.19.5
Import upstream version 7.19.5

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/libcurl/libcurl-tutorial.3
5
5
.\" *                            | (__| |_| |  _ <| |___
6
6
.\" *                             \___|\___/|_| \_\_____|
7
7
.\" *
8
 
.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, <daniel@haxx.se>, et al.
 
8
.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, <daniel@haxx.se>, et al.
9
9
.\" *
10
10
.\" * This software is licensed as described in the file COPYING, which
11
11
.\" * you should have received as part of this distribution. The terms
18
18
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19
19
.\" * KIND, either express or implied.
20
20
.\" *
21
 
.\" * $Id: libcurl-tutorial.3,v 1.14 2007-08-30 20:34:57 danf Exp $
 
21
.\" * $Id: libcurl-tutorial.3,v 1.26 2009-05-04 13:01:27 bagder Exp $
22
22
.\" **************************************************************************
23
23
.\"
24
 
.TH libcurl-tutorial 3 "27 Feb 2007" "libcurl" "libcurl programming"
 
24
.TH libcurl-tutorial 3 "4 Mar 2009" "libcurl" "libcurl programming"
25
25
.SH NAME
26
26
libcurl-tutorial \- libcurl programming tutorial
27
27
.SH "Objective"
36
36
source code that you write that is using libcurl for transfers. The program
37
37
is outside libcurl and libcurl is outside of the program.
38
38
 
39
 
To get the more details on all options and functions described herein, please
 
39
To get more details on all options and functions described herein, please
40
40
refer to their respective man pages.
41
41
 
42
42
.SH "Building"
43
43
There are many different ways to build C programs. This chapter will assume a
44
 
unix-style build process. If you use a different build system, you can still
 
44
UNIX-style build process. If you use a different build system, you can still
45
45
read this to get general information that may apply to your environment as
46
46
well.
47
47
.IP "Compiling the Program"
72
72
$ curl-config --feature
73
73
 
74
74
And if SSL is supported, the keyword 'SSL' will be written to stdout,
75
 
possibly together with a few other features that can be on and off on
76
 
different libcurls.
 
75
possibly together with a few other features that could be either on or off on
 
76
for different libcurls.
77
77
 
78
78
See also the "Features libcurl Provides" further down.
79
79
.IP "autoconf macro"
87
87
on a large amount of different operating systems and environments.
88
88
 
89
89
You program libcurl the same way on all platforms that libcurl runs on. There
90
 
are only very few minor considerations that differs. If you just make sure to
 
90
are only very few minor considerations that differ. If you just make sure to
91
91
write your code portable enough, you may very well create yourself a very
92
92
portable program. libcurl shouldn't stop you from that.
93
93
 
113
113
.IP CURL_GLOBAL_SSL
114
114
which only does anything on libcurls compiled and built SSL-enabled. On these
115
115
systems, this will make libcurl initialize the SSL library properly for this
116
 
application. This is only needed to do once for each application so if your
 
116
application. This only needs to be done once for each application so if your
117
117
program or another library already does this, this bit should not be needed.
118
118
.RE
119
119
 
167
167
the same options.
168
168
 
169
169
Many of the options you set in libcurl are "strings", pointers to data
170
 
terminated with a zero byte. Keep in mind that when you set strings with
171
 
\fIcurl_easy_setopt(3)\fP, libcurl will not copy the data. It will merely
172
 
point to the data. You MUST make sure that the data remains available for
173
 
libcurl to use until finished or until you use the same option again to point
174
 
to something else.
 
170
terminated with a zero byte. When you set strings with
 
171
\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they don't
 
172
need to be kept around in your application after being set[4].
175
173
 
176
174
One of the most basic properties to set in the handle is the URL. You set
177
175
your preferred URL to transfer with CURLOPT_URL in a manner similar to:
193
191
 
194
192
 curl_easy_setopt(easyhandle, CURLOPT_WRITEFUNCTION, write_data);
195
193
 
196
 
You can control what data your function get in the forth argument by setting
197
 
another property:
 
194
You can control what data your callback function gets in the fourth argument
 
195
by setting another property:
198
196
 
199
197
 curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct);
200
198
 
202
200
and the function that gets invoked by libcurl. libcurl itself won't touch the
203
201
data you pass with \fICURLOPT_WRITEDATA\fP.
204
202
 
205
 
libcurl offers its own default internal callback that'll take care of the data
 
203
libcurl offers its own default internal callback that will take care of the data
206
204
if you don't set the callback with \fICURLOPT_WRITEFUNCTION\fP. It will then
207
205
simply output the received data to stdout. You can have the default callback
208
206
write the data to a different file handle by passing a 'FILE *' to a file
245
243
you intend to make another transfer. libcurl will then attempt to re-use the
246
244
previous connection.
247
245
 
 
246
For some protocols, downloading a file can involve a complicated process of
 
247
logging in, setting the transfer mode, changing the current directory and
 
248
finally transferring the file data. libcurl takes care of all that
 
249
complication for you. Given simply the URL to a file, libcurl will take care
 
250
of all the details needed to get the file moved from one machine to another.
 
251
 
248
252
.SH "Multi-threading Issues"
249
253
The first basic rule is that you must \fBnever\fP share a libcurl handle (be
250
254
it easy or multi or whatever) between multiple threads. Only use one handle in
251
255
one thread at a time.
252
256
 
253
257
libcurl is completely thread safe, except for two issues: signals and SSL/TLS
254
 
handlers. Signals are used timeouting name resolves (during DNS lookup) - when
255
 
built without c-ares support and not on Windows..
 
258
handlers. Signals are used for timing out name resolves (during DNS lookup) -
 
259
when built without c-ares support and not on Windows.
256
260
 
257
261
If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
258
262
then of course using the underlying SSL library multi-threaded and those libs
270
274
 
271
275
NSS
272
276
 
273
 
 is claimed to be thread-safe already without anything required
 
277
 is claimed to be thread-safe already without anything required.
274
278
 
275
279
yassl
276
280
 
277
 
 Required actions unknown
 
281
 Required actions unknown.
278
282
 
279
 
When using multiple threads you should set the CURLOPT_NOSIGNAL option to TRUE
 
283
When using multiple threads you should set the CURLOPT_NOSIGNAL option to 1
280
284
for all handles. Everything will or might work fine except that timeouts are
281
285
not honored during the DNS lookup - which you can work around by building
282
286
libcurl with c-ares support. c-ares is a library that provides asynchronous
283
 
name resolves. Unfortunately, c-ares does not yet fully support IPv6. On some
284
 
platforms, libcurl simply will not function properly multi-threaded unless
285
 
this option is set.
 
287
name resolves. On some platforms, libcurl simply will not function properly
 
288
multi-threaded unless this option is set.
286
289
 
287
290
Also, note that CURLOPT_DNS_USE_GLOBAL_CACHE is not thread-safe.
288
291
 
293
296
confuse the library which then confuses your program.
294
297
 
295
298
There's one golden rule when these things occur: set the CURLOPT_VERBOSE
296
 
option to TRUE. It'll cause the library to spew out the entire protocol
 
299
option to 1. It'll cause the library to spew out the entire protocol
297
300
details it sends, some internal info and some received protocol data as well
298
301
(especially when using FTP). If you're using HTTP, adding the headers in the
299
302
received output to study is also a clever way to get a better understanding
300
303
why the server behaves the way it does. Include headers in the normal body
301
 
output with CURLOPT_HEADER set TRUE.
 
304
output with CURLOPT_HEADER set 1.
302
305
 
303
 
Of course there are bugs left. We need to get to know about them to be able
 
306
Of course, there are bugs left. We need to know about them to be able
304
307
to fix them, so we're quite dependent on your bug reports! When you do report
305
 
suspected bugs in libcurl, please include as much details you possibly can: a
 
308
suspected bugs in libcurl, please include as many details as you possibly can: a
306
309
protocol dump that CURLOPT_VERBOSE produces, library version, as much as
307
310
possible of your code that uses libcurl, operating system name and version,
308
311
compiler name and version etc.
339
342
 
340
343
 curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, read_function);
341
344
 
342
 
 curl_easy_setopt(easyhandle, CURLOPT_INFILE, &filedata);
 
345
 curl_easy_setopt(easyhandle, CURLOPT_READDATA, &filedata);
343
346
 
344
347
Tell libcurl that we want to upload:
345
348
 
346
 
 curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, TRUE);
 
349
 curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, 1L);
347
350
 
348
351
A few protocols won't behave properly when uploads are done without any prior
349
352
knowledge of the expected file size. So, set the upload file size using the
350
353
CURLOPT_INFILESIZE_LARGE for all known file sizes like this[1]:
351
354
 
352
355
.nf
353
 
 /* in this example, file_size must be an off_t variable */
 
356
 /* in this example, file_size must be an curl_off_t variable */
354
357
 curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size);
355
358
.fi
356
359
 
378
381
libcurl also provides options to set various passwords. The user name and
379
382
password as shown embedded in the URL can instead get set with the
380
383
CURLOPT_USERPWD option. The argument passed to libcurl should be a char * to
381
 
a string in the format "user:password:". In a manner like this:
 
384
a string in the format "user:password". In a manner like this:
382
385
 
383
386
 curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret");
384
387
 
389
392
 
390
393
 curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
391
394
 
392
 
There's a long time unix "standard" way of storing ftp user names and
 
395
There's a long time UNIX "standard" way of storing ftp user names and
393
396
passwords, namely in the $HOME/.netrc file. The file should be made private
394
397
so that only the user may read it (see also the "Security Considerations"
395
398
chapter), as it might contain the password in plain text. libcurl has the
398
401
libcurl also supports this file for non-FTP protocols such as HTTP. To make
399
402
curl use this file, use the CURLOPT_NETRC option:
400
403
 
401
 
 curl_easy_setopt(easyhandle, CURLOPT_NETRC, TRUE);
 
404
 curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L);
402
405
 
403
406
And a very basic example of how such a .netrc file may look like:
404
407
 
421
424
The previous chapter showed how to set user name and password for getting
422
425
URLs that require authentication. When using the HTTP protocol, there are
423
426
many different ways a client can provide those credentials to the server and
424
 
you can control what way libcurl will (attempt to) use. The default HTTP
 
427
you can control which way libcurl will (attempt to) use them. The default HTTP
425
428
authentication method is called 'Basic', which is sending the name and
426
429
password in clear-text in the HTTP request, base64-encoded. This is insecure.
427
430
 
428
 
At the time of this writing libcurl can be built to use: Basic, Digest, NTLM,
 
431
At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM,
429
432
Negotiate, GSS-Negotiate and SPNEGO. You can tell libcurl which one to use
430
433
with CURLOPT_HTTPAUTH as in:
431
434
 
472
475
upcoming request.
473
476
 
474
477
Ok, so what if you want to post binary data that also requires you to set the
475
 
Content-Type: header of the post? Well, binary posts prevents libcurl from
 
478
Content-Type: header of the post? Well, binary posts prevent libcurl from
476
479
being able to do strlen() on the data to figure out the size, so therefore we
477
480
must tell libcurl the size of the post data. Setting headers in libcurl
478
481
requests are done in a generic way, by building a list of our own headers and
486
489
 curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, binaryptr);
487
490
 
488
491
 /* set the size of the postfields data */
489
 
 curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23);
 
492
 curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23L);
490
493
 
491
494
 /* pass our list of custom made headers */
492
495
 curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
499
502
While the simple examples above cover the majority of all cases where HTTP
500
503
POST operations are required, they don't do multi-part formposts. Multi-part
501
504
formposts were introduced as a better way to post (possibly large) binary data
502
 
and was first documented in the RFC1867. They're called multi-part because
 
505
and were first documented in the RFC1867. They're called multi-part because
503
506
they're built by a chain of parts, each being a single unit. Each part has its
504
507
own name and contents. You can in fact create and post a multi-part formpost
505
508
with the regular libcurl POST support described above, but that would require
508
511
parts to the form. When you're done adding parts, you post the whole form.
509
512
 
510
513
The following example sets two simple text parts with plain textual contents,
511
 
and then a file with binary contents and upload the whole thing.
 
514
and then a file with binary contents and uploads the whole thing.
512
515
 
513
516
.nf
514
517
 struct curl_httppost *post=NULL;
537
540
that describe the individual content-type, size etc. To enable your
538
541
application to handicraft this formpost even more, libcurl allows you to
539
542
supply your own set of custom headers to such an individual form part. You can
540
 
of course supply headers to as many parts you like, but this little example
 
543
of course supply headers to as many parts as you like, but this little example
541
544
will show how you set headers to one specific part when you add that to the
542
545
post handle:
543
546
 
554
557
 curl_easy_perform(easyhandle); /* post away! */
555
558
 
556
559
 curl_formfree(post); /* free post */
557
 
 curl_slist_free_all(post); /* free custom header list */
 
560
 curl_slist_free_all(headers); /* free custom header list */
558
561
.fi
559
562
 
560
563
Since all options on an easyhandle are "sticky", they remain the same until
561
564
changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell
562
 
curl to go back to a plain GET request if you intend to do such a one as your
563
 
next request. You force an easyhandle to back to GET by using the
 
565
curl to go back to a plain GET request if you intend to do one as your
 
566
next request. You force an easyhandle to go back to GET by using the
564
567
CURLOPT_HTTPGET option:
565
568
 
566
 
 curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, TRUE);
 
569
 curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L);
567
570
 
568
571
Just setting CURLOPT_POSTFIELDS to "" or NULL will *not* stop libcurl from
569
572
doing a POST. It will just make it POST without any data to send!
571
574
.SH "Showing Progress"
572
575
 
573
576
For historical and traditional reasons, libcurl has a built-in progress meter
574
 
that can be switched on and then makes it presents a progress meter in your
 
577
that can be switched on and then makes it present a progress meter in your
575
578
terminal.
576
579
 
577
 
Switch on the progress meter by, oddly enough, set CURLOPT_NOPROGRESS to
578
 
FALSE. This option is set to TRUE by default.
 
580
Switch on the progress meter by, oddly enough, setting CURLOPT_NOPROGRESS to
 
581
zero. This option is set to 1 by default.
579
582
 
580
583
For most applications however, the built-in progress meter is useless and
581
584
what instead is interesting is the ability to specify a progress
639
642
HTTP URL will be still be passed to the HTTP proxy to deliver back to
640
643
libcurl. This happens transparently, and an application may not need to
641
644
know. I say "may", because at times it is very important to understand that
642
 
all operations over a HTTP proxy is using the HTTP protocol. For example, you
 
645
all operations over a HTTP proxy use the HTTP protocol. For example, you
643
646
can't invoke your own custom FTP commands or even proper FTP directory
644
647
listings.
645
648
 
664
667
 
665
668
.IP "Environment Variables"
666
669
 
667
 
libcurl automatically checks and uses a set of environment variables to
668
 
know what proxies to use for certain protocols. The names of the variables
669
 
are following an ancient de facto standard and are built up as
670
 
"[protocol]_proxy" (note the lower casing). Which makes the variable
671
 
'http_proxy' checked for a name of a proxy to use when the input URL is
672
 
HTTP. Following the same rule, the variable named 'ftp_proxy' is checked
673
 
for FTP URLs. Again, the proxies are always HTTP proxies, the different
674
 
names of the variables simply allows different HTTP proxies to be used.
 
670
libcurl automatically checks and uses a set of environment variables to know
 
671
what proxies to use for certain protocols. The names of the variables are
 
672
following an ancient de facto standard and are built up as "[protocol]_proxy"
 
673
(note the lower casing). Which makes the variable \&'http_proxy' checked for a
 
674
name of a proxy to use when the input URL is HTTP. Following the same rule,
 
675
the variable named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are
 
676
always HTTP proxies, the different names of the variables simply allows
 
677
different HTTP proxies to be used.
675
678
 
676
679
The proxy environment variable contents should be in the format
677
680
\&"[protocol://][user:password@]machine[:port]". Where the protocol:// part is
725
728
 
726
729
Tell libcurl to use proxy tunneling like this:
727
730
 
728
 
 curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, TRUE);
 
731
 curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, 1L);
729
732
 
730
733
In fact, there might even be times when you want to do plain HTTP
731
734
operations using a tunnel like this, as it then enables you to operate on
735
738
.IP "Proxy Auto-Config"
736
739
 
737
740
Netscape first came up with this. It is basically a web page (usually using a
738
 
\&.pac extension) with a javascript that when executed by the browser with the
 
741
\&.pac extension) with a Javascript that when executed by the browser with the
739
742
requested URL as input, returns information to the browser on how to connect
740
743
to the URL. The returned information might be "DIRECT" (which means no proxy
741
744
should be used), "PROXY host:port" (to tell the browser where the proxy for
742
745
this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS
743
746
proxy).
744
747
 
745
 
libcurl has no means to interpret or evaluate javascript and thus it doesn't
 
748
libcurl has no means to interpret or evaluate Javascript and thus it doesn't
746
749
support this. If you get yourself in a position where you face this nasty
747
750
invention, the following advice have been mentioned and used in the past:
748
751
 
749
 
- Depending on the javascript complexity, write up a script that translates it
 
752
- Depending on the Javascript complexity, write up a script that translates it
750
753
to another language and execute that.
751
754
 
752
 
- Read the javascript code and rewrite the same logic in another language.
 
755
- Read the Javascript code and rewrite the same logic in another language.
753
756
 
754
 
- Implement a javascript interpreted, people have successfully used the
755
 
Mozilla javascript engine in the past.
 
757
- Implement a Javascript interpreted, people have successfully used the
 
758
Mozilla Javascript engine in the past.
756
759
 
757
760
- Ask your admins to stop this, for a static proxy setup or similar.
758
761
 
770
773
host again, will benefit from libcurl's session ID cache that drastically
771
774
reduces re-connection time.
772
775
 
773
 
FTP connections that are kept alive saves a lot of time, as the command-
 
776
FTP connections that are kept alive save a lot of time, as the command-
774
777
response round-trips are skipped, and also you don't risk getting blocked
775
778
without permission to login again like on many FTP servers only allowing N
776
779
persons to be logged in at the same time.
783
786
 
784
787
Each easy handle will attempt to keep the last few connections alive for a
785
788
while in case they are to be used again. You can set the size of this "cache"
786
 
with the CURLOPT_MAXCONNECTS option. Default is 5. It is very seldom any
 
789
with the CURLOPT_MAXCONNECTS option. Default is 5. There is very seldom any
787
790
point in changing this value, and if you think of changing this it is often
788
791
just a matter of thinking again.
789
792
 
790
793
To force your upcoming request to not use an already existing connection (it
791
794
will even close one first if there happens to be one alive to the same host
792
795
you're about to operate on), you can do that by setting CURLOPT_FRESH_CONNECT
793
 
to TRUE. In a similar spirit, you can also forbid the upcoming request to be
 
796
to 1. In a similar spirit, you can also forbid the upcoming request to be
794
797
"lying" around and possibly get re-used after the request by setting
795
 
CURLOPT_FORBID_REUSE to TRUE.
 
798
CURLOPT_FORBID_REUSE to 1.
796
799
 
797
800
.SH "HTTP Headers Used by libcurl"
798
801
When you use libcurl to do HTTP requests, it'll pass along a series of headers
799
 
automatically. It might be good for you to know and understand these ones. You
 
802
automatically. It might be good for you to know and understand these. You
800
803
can replace or remove them by using the CURLOPT_HTTPHEADER option.
801
804
 
802
805
.IP "Host"
820
823
.SH "Customizing Operations"
821
824
There is an ongoing development today where more and more protocols are built
822
825
upon HTTP for transport. This has obvious benefits as HTTP is a tested and
823
 
reliable protocol that is widely deployed and have excellent proxy-support.
 
826
reliable protocol that is widely deployed and has excellent proxy-support.
824
827
 
825
828
When you use one of these protocols, and even when doing other kinds of
826
829
programming you may need to change the traditional HTTP (or FTP or...)
833
836
GET, HEAD or POST is not good enough for you, CURLOPT_CUSTOMREQUEST is there
834
837
for you. It is very simple to use:
835
838
 
836
 
 curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNRUQUEST");
 
839
 curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST");
837
840
 
838
841
When using the custom request, you change the request keyword of the actual
839
 
request you are performing. Thus, by default you make GET request but you can
 
842
request you are performing. Thus, by default you make a GET request but you can
840
843
also make a POST operation (as described before) and then replace the POST
841
844
keyword if you want to. You're the boss.
842
845
 
843
846
.IP "Modify Headers"
844
847
HTTP-like protocols pass a series of headers to the server when doing the
845
848
request, and you're free to pass any amount of extra headers that you
846
 
think fit. Adding headers are this easy:
 
849
think fit. Adding headers is this easy:
847
850
 
848
851
.nf
849
852
 struct curl_slist *headers=NULL; /* init to NULL is important */
870
873
 
871
874
.IP "Delete Headers"
872
875
If you replace an existing header with one with no contents, you will prevent
873
 
the header from being sent. Like if you want to completely prevent the
874
 
\&"Accept:" header to be sent, you can disable it with code similar to this:
 
876
the header from being sent. For instance, if you want to completely prevent the
 
877
\&"Accept:" header from being sent, you can disable it with code similar to this:
875
878
 
876
879
 headers = curl_slist_append(headers, "Accept:");
877
880
 
890
893
.IP "HTTP Version"
891
894
 
892
895
All HTTP requests includes the version number to tell the server which version
893
 
we support. libcurl speak HTTP 1.1 by default. Some very old servers don't
 
896
we support. libcurl speaks HTTP 1.1 by default. Some very old servers don't
894
897
like getting 1.1-requests and when dealing with stubborn old things like that,
895
898
you can tell libcurl to use 1.0 instead by doing something like this:
896
899
 
899
902
.IP "FTP Custom Commands"
900
903
 
901
904
Not all protocols are HTTP-like, and thus the above may not help you when
902
 
you want to make for example your FTP transfers to behave differently.
 
905
you want to make, for example, your FTP transfers to behave differently.
903
906
 
904
907
Sending custom commands to a FTP server means that you need to send the
905
908
commands exactly as the FTP server expects them (RFC959 is a good guide
906
909
here), and you can only use commands that work on the control-connection
907
 
alone. All kinds of commands that requires data interchange and thus needs
908
 
a data-connection must be left to libcurl's own judgment. Also be aware
 
910
alone. All kinds of commands that require data interchange and thus need
 
911
a data-connection must be left to libcurl's own judgement. Also be aware
909
912
that libcurl will do its very best to change directory to the target
910
913
directory before doing any transfer, so if you change directory (with CWD
911
914
or similar) you might confuse libcurl and then it might not attempt to
935
938
commands before a transfer, no transfer will actually take place when a quote
936
939
command has failed.
937
940
 
938
 
If you set the CURLOPT_HEADER to true, you will tell libcurl to get
 
941
If you set the CURLOPT_HEADER to 1, you will tell libcurl to get
939
942
information about the target file and output "headers" about it. The headers
940
943
will be in "HTTP-style", looking like they do in HTTP.
941
944
 
944
947
transfer will be performed.
945
948
 
946
949
.IP "FTP Custom CUSTOMREQUEST"
947
 
If you do what list the contents of a FTP directory using your own defined FTP
 
950
If you do want to list the contents of a FTP directory using your own defined FTP
948
951
command, CURLOPT_CUSTOMREQUEST will do just that. "NLST" is the default one
949
952
for listing directories but you're free to pass in your idea of a good
950
953
alternative.
956
959
set. The conditions include that the domain name and path match and that the
957
960
cookie hasn't become too old.
958
961
 
959
 
In real-world cases, servers send new cookies to replace existing one to
 
962
In real-world cases, servers send new cookies to replace existing ones to
960
963
update them. Server use cookies to "track" users and to keep "sessions".
961
964
 
962
965
Cookies are sent from server to clients with the header Set-Cookie: and
969
972
 
970
973
In many cases, that is not enough. You might want to dynamically save
971
974
whatever cookies the remote server passes to you, and make sure those cookies
972
 
are then use accordingly on later requests.
 
975
are then used accordingly on later requests.
973
976
 
974
977
One way to do this, is to save all headers you receive in a plain file and
975
978
when you make a request, you tell libcurl to read the previous headers to
976
 
figure out which cookies to use. Set header file to read cookies from with
 
979
figure out which cookies to use. Set the header file to read cookies from with
977
980
CURLOPT_COOKIEFILE.
978
981
 
979
982
The CURLOPT_COOKIEFILE option also automatically enables the cookie parser in
982
985
parser is enabled the cookies will be understood and the cookies will be kept
983
986
in memory and used properly in subsequent requests when the same handle is
984
987
used. Many times this is enough, and you may not have to save the cookies to
985
 
disk at all. Note that the file you specify to CURLOPT_COOKIEFILE doesn't
986
 
have to exist to enable the parser, so a common way to just enable the parser
987
 
and not read able might be to use a file name you know doesn't exist.
 
988
disk at all. Note that the file you specify to CURLOPT_COOKIEFILE doesn't have
 
989
to exist to enable the parser, so a common way to just enable the parser and
 
990
not read any cookies is to use the name of a file you know doesn't exist.
988
991
 
989
 
If you rather use existing cookies that you've previously received with your
990
 
Netscape or Mozilla browsers, you can make libcurl use that cookie file as
991
 
input. The CURLOPT_COOKIEFILE is used for that too, as libcurl will
 
992
If you would rather use existing cookies that you've previously received with
 
993
your Netscape or Mozilla browsers, you can make libcurl use that cookie file
 
994
as input. The CURLOPT_COOKIEFILE is used for that too, as libcurl will
992
995
automatically find out what kind of file it is and act accordingly.
993
996
 
994
 
The perhaps most advanced cookie operation libcurl offers, is saving the
 
997
Perhaps the most advanced cookie operation libcurl offers, is saving the
995
998
entire internal cookie state back into a Netscape/Mozilla formatted cookie
996
999
file. We call that the cookie-jar. When you set a file name with
997
1000
CURLOPT_COOKIEJAR, that file name will be created and all received cookies
998
 
will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enabled
 
1001
will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables
999
1002
cookies to get passed on properly between multiple handles without any
1000
1003
information getting lost.
1001
1004
 
1003
1006
 
1004
1007
FTP transfers use a second TCP/IP connection for the data transfer. This is
1005
1008
usually a fact you can forget and ignore but at times this fact will come
1006
 
back to haunt you. libcurl offers several different ways to custom how the
 
1009
back to haunt you. libcurl offers several different ways to customize how the
1007
1010
second connection is being made.
1008
1011
 
1009
1012
libcurl can either connect to the server a second time or tell the server to
1015
1018
and does not exist nor work on all FTP servers.)
1016
1019
 
1017
1020
You can prevent libcurl from first trying the EPSV command by setting
1018
 
CURLOPT_FTP_USE_EPSV to FALSE.
 
1021
CURLOPT_FTP_USE_EPSV to zero.
1019
1022
 
1020
1023
In some cases, you will prefer to have the server connect back to you for the
1021
1024
second connection. This might be when the server is perhaps behind a firewall
1029
1032
 
1030
1033
When doing the "PORT" approach, libcurl will attempt to use the EPRT and the
1031
1034
LPRT before trying PORT, as they work with more protocols. You can disable
1032
 
this behavior by setting CURLOPT_FTP_USE_EPRT to FALSE.
 
1035
this behavior by setting CURLOPT_FTP_USE_EPRT to zero.
1033
1036
 
1034
1037
.SH "Headers Equal Fun"
1035
1038
 
1036
1039
Some protocols provide "headers", meta-data separated from the normal
1037
1040
data. These headers are by default not included in the normal data stream,
1038
1041
but you can make them appear in the data stream by setting CURLOPT_HEADER to
1039
 
TRUE.
 
1042
1.
1040
1043
 
1041
1044
What might be even more useful, is libcurl's ability to separate the headers
1042
1045
from the data and thus make the callbacks differ. You can for example set a
1059
1062
 
1060
1063
.SH "Security Considerations"
1061
1064
 
1062
 
libcurl is in itself not insecure. If used the right way, you can use libcurl
1063
 
to transfer data pretty safely.
 
1065
The libcurl project takes security seriously.  The library is written with
 
1066
caution and precautions are taken to mitigate many kinds of risks encountered
 
1067
while operating with potentially malicious servers on the Internet.  It is a
 
1068
powerful library, however, which allows application writers to make trade offs
 
1069
between ease of writing and exposure to potential risky operations.  If
 
1070
used the right way, you can use libcurl to transfer data pretty safely.
1064
1071
 
1065
 
There are of course many things to consider that may loosen up this
1066
 
situation:
 
1072
Many applications are used in closed networks where users and servers
 
1073
can be trusted, but many others are used on arbitrary servers and are fed
 
1074
input from potentially untrusted users.  Following is a discussion about
 
1075
some risks in the ways in which applications commonly use libcurl and
 
1076
potential mitigations of those risks. It is by no means comprehensive, but
 
1077
shows classes of attacks that robust applications should consider. The
 
1078
Common Weakness Enumeration project at http://cwe.mitre.org/ is a good
 
1079
reference for many of these and similar types of weaknesses of which
 
1080
application writers should be aware.
1067
1081
 
1068
1082
.IP "Command Lines"
1069
1083
If you use a command line tool (such as curl) that uses libcurl, and you give
1070
 
option to the tool on the command line those options can very likely get read
 
1084
options to the tool on the command line those options can very likely get read
1071
1085
by other users of your system when they use 'ps' or other tools to list
1072
1086
currently running processes.
1073
1087
 
1074
1088
To avoid this problem, never feed sensitive things to programs using command
1075
 
line options.
 
1089
line options. Write them to a protected file and use the \-K option to
 
1090
avoid this.
1076
1091
 
1077
1092
.IP ".netrc"
1078
1093
\&.netrc is a pretty handy file/feature that allows you to login quickly and
1088
1103
.IP "Clear Text Passwords"
1089
1104
Many of the protocols libcurl supports send name and password unencrypted as
1090
1105
clear text (HTTP Basic authentication, FTP, TELNET etc). It is very easy for
1091
 
anyone on your network or a network nearby yours, to just fire up a network
 
1106
anyone on your network or a network nearby yours to just fire up a network
1092
1107
analyzer tool and eavesdrop on your passwords. Don't let the fact that HTTP
1093
 
uses base64 encoded passwords fool you. They may not look readable at a first
1094
 
glance, but they very easily "deciphered" by anyone within seconds.
1095
 
 
1096
 
To avoid this problem, use protocols that don't let snoopers see your
1097
 
password: HTTPS, FTPS and FTP-kerberos are a few examples. HTTP Digest
1098
 
authentication allows this too, but isn't supported by libcurl as of this
1099
 
writing.
 
1108
Basic uses base64 encoded passwords fool you. They may not look readable at a
 
1109
first glance, but they very easily "deciphered" by anyone within seconds.
 
1110
 
 
1111
To avoid this problem, use HTTP authentication methods or other protocols that
 
1112
don't let snoopers see your password: HTTP with Digest, NTLM or GSS
 
1113
authentication, HTTPS, FTPS, SCP, SFTP and FTP-Kerberos are a few examples.
 
1114
 
 
1115
.IP "Redirects"
 
1116
The CURLOPT_FOLLOWLOCATION option automatically follows HTTP redirects sent
 
1117
by a remote server.  These redirects can refer to any kind of URL, not just
 
1118
HTTP.  A redirect to a file: URL would cause the libcurl to read (or write)
 
1119
arbitrary files from the local filesystem.  If the application returns
 
1120
the data back to the user (as would happen in some kinds of CGI scripts),
 
1121
an attacker could leverage this to read otherwise forbidden data (e.g.
 
1122
file://localhost/etc/passwd).
 
1123
 
 
1124
If authentication credentials are stored in the ~/.netrc file, or Kerberos
 
1125
is in use, any other URL type (not just file:) that requires
 
1126
authentication is also at risk.  A redirect such as
 
1127
ftp://some-internal-server/private-file would then return data even when
 
1128
the server is password protected.
 
1129
 
 
1130
In the same way, if an unencrypted SSH private key has been configured for
 
1131
the user running the libcurl application, SCP: or SFTP: URLs could access
 
1132
password or private-key protected resources,
 
1133
e.g. sftp://user@some-internal-server/etc/passwd
 
1134
 
 
1135
The CURLOPT_REDIR_PROTOCOLS and CURLOPT_NETRC options can be used to
 
1136
mitigate against this kind of attack.
 
1137
 
 
1138
A redirect can also specify a location available only on the machine running
 
1139
libcurl, including servers hidden behind a firewall from the attacker.
 
1140
e.g. http://127.0.0.1/ or http://intranet/delete-stuff.cgi?delete=all or
 
1141
tftp://bootp-server/pc-config-data
 
1142
 
 
1143
Apps can mitigate against this by disabling CURLOPT_FOLLOWLOCATION and
 
1144
handling redirects itself, sanitizing URLs as necessary. Alternately, an
 
1145
app could leave CURLOPT_FOLLOWLOCATION enabled but set CURLOPT_REDIR_PROTOCOLS
 
1146
and install a CURLOPT_OPENSOCKETFUNCTION callback function in which addresses
 
1147
are sanitized before use.
 
1148
 
 
1149
.IP "Private Resources"
 
1150
A user who can control the DNS server of a domain being passed in within
 
1151
a URL can change the address of the host to a local, private address
 
1152
which the libcurl application will then use. e.g. The innocuous URL
 
1153
http://fuzzybunnies.example.com/ could actually resolve to the IP address
 
1154
of a server behind a firewall, such as 127.0.0.1 or 10.1.2.3
 
1155
Apps can mitigate against this by setting a CURLOPT_OPENSOCKETFUNCTION
 
1156
and checking the address before a connection.
 
1157
 
 
1158
All the malicious scenarios regarding redirected URLs apply just as well
 
1159
to non-redirected URLs, if the user is allowed to specify an arbitrary URL
 
1160
that could point to a private resource. For example, a web app providing
 
1161
a translation service might happily translate file://localhost/etc/passwd
 
1162
and display the result.  Apps can mitigate against this with the
 
1163
CURLOPT_PROTOCOLS option as well as by similar mitigation techniques for
 
1164
redirections.
 
1165
 
 
1166
A malicious FTP server could in response to the PASV command return an
 
1167
IP address and port number for a server local to the app running libcurl
 
1168
but behind a firewall.  Apps can mitigate against this by using the
 
1169
CURLOPT_FTP_SKIP_PASV_IP option or CURLOPT_FTPPORT.
 
1170
 
 
1171
.IP Uploads
 
1172
When uploading, a redirect can cause a local (or remote) file to be
 
1173
overwritten.  Apps must not allow any unsanitized URL to be passed in
 
1174
for uploads.  Also, CURLOPT_FOLLOWLOCATION should not be used on uploads.
 
1175
Instead, the app should handle redirects itself, sanitizing each URL first.
 
1176
 
 
1177
.IP Authentication
 
1178
Use of CURLOPT_UNRESTRICTED_AUTH could cause authentication information to
 
1179
be sent to an unknown second server.  Apps can mitigate against this
 
1180
by disabling CURLOPT_FOLLOWLOCATION and handling redirects itself,
 
1181
sanitizing where necessary.
 
1182
 
 
1183
Use of the CURLAUTH_ANY option to CURLOPT_HTTPAUTH could result in user
 
1184
name and password being sent in clear text to an HTTP server.  Instead,
 
1185
use CURLAUTH_ANYSAFE which ensures that the password is encrypted over
 
1186
the network, or else fail the request.
 
1187
 
 
1188
Use of the CURLUSESSL_TRY option to CURLOPT_USE_SSL could result in user
 
1189
name and password being sent in clear text to an FTP server.  Instead,
 
1190
use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or
 
1191
else fail the request.
 
1192
 
 
1193
.IP Cookies
 
1194
If cookies are enabled and cached, then a user could craft a URL which
 
1195
performs some malicious action to a site whose authentication is already
 
1196
stored in a cookie. e.g. http://mail.example.com/delete-stuff.cgi?delete=all
 
1197
Apps can mitigate against this by disabling cookies or clearing them
 
1198
between requests.
 
1199
 
 
1200
.IP "Dangerous URLs"
 
1201
SCP URLs can contain raw commands within the scp: URL, which is a side effect
 
1202
of how the SCP protocol is designed. e.g. 
 
1203
scp://user:pass@host/a;date >/tmp/test;
 
1204
Apps must not allow unsanitized SCP: URLs to be passed in for downloads.
 
1205
 
 
1206
.IP "Denial of Service"
 
1207
A malicious server could cause libcurl to effectively hang by sending
 
1208
a trickle of data through, or even no data at all but just keeping the TCP
 
1209
connection open.  This could result in a denial-of-service attack. The
 
1210
CURLOPT_TIMEOUT and/or CURLOPT_LOW_SPEED_LIMIT options can be used to
 
1211
mitigate against this.
 
1212
 
 
1213
A malicious server could cause libcurl to effectively hang by starting to
 
1214
send data, then severing the connection without cleanly closing the
 
1215
TCP connection.  The app could install a CURLOPT_SOCKOPTFUNCTION callback
 
1216
function and set the TCP SO_KEEPALIVE option to mitigate against this.
 
1217
Setting one of the timeout options would also work against this attack.
 
1218
 
 
1219
A malicious server could cause libcurl to download an infinite amount of
 
1220
data, potentially causing all of memory or disk to be filled. Setting
 
1221
the CURLOPT_MAXFILESIZE_LARGE option is not sufficient to guard against this.
 
1222
Instead, the app should monitor the amount of data received within the
 
1223
write or progress callback and abort once the limit is reached.
 
1224
 
 
1225
A malicious HTTP server could cause an infinite redirection loop, causing a 
 
1226
denial-of-service. This can be mitigated by using the CURLOPT_MAXREDIRS
 
1227
option.
 
1228
 
 
1229
.IP "Arbitrary Headers"
 
1230
User-supplied data must be sanitized when used in options like
 
1231
CURLOPT_USERAGENT, CURLOPT_HTTPHEADER, CURLOPT_POSTFIELDS and others that
 
1232
are used to generate structured data. Characters like embedded carriage
 
1233
returns or ampersands could allow the user to create additional headers or
 
1234
fields that could cause malicious transactions.
 
1235
 
 
1236
.IP "Server Certificates"
 
1237
A secure application should never use the CURLOPT_SSL_VERIFYPEER option to
 
1238
disable certificate validation. There are numerous attacks that are enabled
 
1239
by apps that fail to properly validate server TLS/SSL certificates,
 
1240
thus enabling a malicious server to spoof a legitimate one. HTTPS without
 
1241
validated certificates is potentially as insecure as a plain HTTP connection.
1100
1242
 
1101
1243
.IP "Showing What You Do"
1102
1244
On a related issue, be aware that even in situations like when you have
1103
1245
problems with libcurl and ask someone for help, everything you reveal in order
1104
1246
to get best possible help might also impose certain security related
1105
 
risks. Host names, user names, paths, operating system specifics etc (not to
 
1247
risks. Host names, user names, paths, operating system specifics, etc (not to
1106
1248
mention passwords of course) may in fact be used by intruders to gain
1107
1249
additional information of a potential target.
1108
1250
 
1113
1255
.SH "Multiple Transfers Using the multi Interface"
1114
1256
 
1115
1257
The easy interface as described in detail in this document is a synchronous
1116
 
interface that transfers one file at a time and doesn't return until its
 
1258
interface that transfers one file at a time and doesn't return until it is
1117
1259
done.
1118
1260
 
1119
 
The multi interface on the other hand, allows your program to transfer
1120
 
multiple files in both directions at the same time, without forcing you to
1121
 
use multiple threads.
 
1261
The multi interface, on the other hand, allows your program to transfer
 
1262
multiple files in both directions at the same time, without forcing you
 
1263
to use multiple threads.  The name might make it seem that the multi
 
1264
interface is for multi-threaded programs, but the truth is almost the
 
1265
reverse.  The multi interface can allow a single-threaded application
 
1266
to perform the same kinds of multiple, simultaneous transfers that
 
1267
multi-threaded programs can perform.  It allows many of the benefits
 
1268
of multi-threaded transfers without the complexity of managing and
 
1269
synchronizing many threads.
1122
1270
 
1123
1271
To use this interface, you are better off if you first understand the basics
1124
1272
of how to use the easy interface. The multi interface is simply a way to make
1125
 
multiple transfers at the same time, by adding up multiple easy handles in to
 
1273
multiple transfers at the same time by adding up multiple easy handles into
1126
1274
a "multi stack".
1127
1275
 
1128
1276
You create the easy handles you want and you set all the options just like you
1131
1279
with \fIcurl_multi_add_handle(3)\fP.
1132
1280
 
1133
1281
When you've added the handles you have for the moment (you can still add new
1134
 
ones at any time), you start the transfers by call
 
1282
ones at any time), you start the transfers by calling
1135
1283
\fIcurl_multi_perform(3)\fP.
1136
1284
 
1137
1285
\fIcurl_multi_perform(3)\fP is asynchronous. It will only execute as little as
1150
1298
When you then call select(), it'll return when one of the file handles signal
1151
1299
action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do
1152
1300
what it wants to do. Take note that libcurl does also feature some time-out
1153
 
code so we advice you to never use very long timeouts on select() before you
 
1301
code so we advise you to never use very long timeouts on select() before you
1154
1302
call \fIcurl_multi_perform(3)\fP, which thus should be called unconditionally
1155
1303
every now and then even if none of its file descriptors have signaled
1156
1304
ready. Another precaution you should use: always call
1181
1329
 
1182
1330
.IP "[1]"
1183
1331
libcurl 7.10.3 and later have the ability to switch over to chunked
1184
 
Transfer-Encoding in cases were HTTP uploads are done with data of an unknown
 
1332
Transfer-Encoding in cases where HTTP uploads are done with data of an unknown
1185
1333
size.
1186
1334
.IP "[2]"
1187
1335
This happens on Windows machines when libcurl is built and used as a
1188
1336
DLL. However, you can still do this on Windows if you link with a static
1189
1337
library.
1190
1338
.IP "[3]"
1191
 
The curl-config tool is generated at build-time (on unix-like systems) and
 
1339
The curl-config tool is generated at build-time (on UNIX-like systems) and
1192
1340
should be installed with the 'make install' or similar instruction that
1193
1341
installs the library, header files, man pages etc.
 
1342
.IP "[4]"
 
1343
This behavior was different in versions before 7.17.0, where strings had to
 
1344
remain valid past the end of the \fIcurl_easy_setopt(3)\fP call.