HTTP "auth done right". See lib/README.httpauth

10 files changed, 214 insertions, 19 deletions

diff --git a/docs/TODO b/docs/TODO
index 94507ea98..888b9d371 100644
--- a/docs/TODO
+++ b/docs/TODO
@@ -38,6 +38,11 @@ TODO
 
  LIBCURL - multi interface
 
+ * Add a curl_multi_fdset() alternative that returns only two arrays with file
+   desrciptors for reading and writing to allow the app to use whatever
+   function it prefers. Plus, this allows apps to avoid the FD_SETSIZE problem
+   with select().
+
  * Add curl_multi_timeout() to make libcurl's ares-functionality better.
 
  * Make sure we don't ever loop because of non-blocking sockets return
diff --git a/docs/curl.1 b/docs/curl.1
index dd022534a..e2fdc8bd9 100644
--- a/docs/curl.1
+++ b/docs/curl.1
@@ -91,6 +91,11 @@ network round-trip. This is used instead of setting a specific authentication
 method, which you can do with \fI--basic\fP, \fI--digest\fP, \fI--ntlm\fP, and
 \fI--negotiate\fP. (Added in 7.10.6)
 
+Note that using --anyauth is not recommended if you do uploads from stdin,
+since it may require data to be sent twice and then the client must be able to
+rewind. If the need should arise when uploading from stdin, the upload
+operation will fail.
+
 If this option is used several times, the following occurrences make no
 difference.
 .IP "-b/--cookie <name=data>"
diff --git a/docs/examples/Makefile.am b/docs/examples/Makefile.am
index 6425707d8..34ac520a7 100644
--- a/docs/examples/Makefile.am
+++ b/docs/examples/Makefile.am
@@ -9,7 +9,8 @@ EXTRA_DIST = README curlgtk.c sepheaders.c simple.c postit2.c		\
  ftpupload.c httpput.c simplessl.c ftpgetresp.c http-post.c		\
  post-callback.c multi-app.c multi-double.c multi-single.c		\
  multi-post.c fopen.c simplepost.c makefile.dj curlx.c https.c		\
- multi-debugcallback.c fileupload.c getinfo.c ftp3rdparty.c debug.c
+ multi-debugcallback.c fileupload.c getinfo.c ftp3rdparty.c debug.c	\
+ anyauthput.c
 
 all:
 	@echo "done"
diff --git a/docs/examples/README b/docs/examples/README
index dd053d8f0..9951241c5 100644
--- a/docs/examples/README
+++ b/docs/examples/README
@@ -1,4 +1,8 @@
-EXAMPLES
+                                  _   _ ____  _
+                              ___| | | |  _ \| |
+                             / __| | | | |_) | |
+                            | (__| |_| |  _ <| |___
+                             \___|\___/|_| \_\_____|
 
 This directory is for libcurl programming examples. They are meant to show
 some simple steps on how you can build your own application to take full
@@ -7,6 +11,8 @@ advantage of libcurl.
 If you end up with other small but still useful example sources, please mail
 them for submission in future packages and on the web site.
 
+BUILDING
+
 The Makefile.example is an example makefile that could be used to build these
 examples. Just edit the file according to your system and requirements first.
 
@@ -23,3 +29,34 @@ want you do reorganize them like:
 applications/experiments. Even if the examples in this directory use that site
 as an example URL at some places, it doesn't mean that the URLs work or that
 we expect you to actually torture our web site with your tests! Thanks.
+
+EXAMPLES
+
+anyauthput.c   - HTTP PUT using "any" authentication method
+curlgtk.c      - download using a GTK progress bar
+curlx.c        - getting file info from the remote cert data
+debug.c        - showing how to use the debug callback
+fileupload.c   - uploading to a file:// URL
+fopen.c        - fopen() layer that supports opening URLs and files
+ftp3rdparty.c  - FTP 3rd party transfer
+ftpget.c       - simple getting a file from FTP
+ftpgetresp.c   - get the response strings from the FTP server
+ftpupload.c    - upload a file to a FTP server
+getinfo.c      - get the Content-Type from the recent transfer
+getinmemory.c  - download a file to memory only
+http-post.c    - HTTP POST
+httpput.c      - HTTP PUT a local file
+https.c        - simple HTTPS transfer
+multi-app.c    - a multi-interface app
+multi-debugcallback.c - a multi-interface app using the debug callback
+multi-double.c - a multi-interface app doing two simultaneous transfers
+multi-post.c   - a multi-interface app doing a multipart formpost
+multi-single.c - a multi-interface app getting a single file
+multithread.c  - an example using multi-treading transfering multiple files
+persistant.c   - request two URLs with a persistant connection
+post-callback.c - send a HTTP POST using a callback
+postit2.c      - send a HTTP multipart formpost
+sepheaders.c   - download headers to a separate file
+simple.c       - the most simple download a URL source
+simplepost.c   - HTTP POST
+simplessl.c    - HTTPS example with certificates many options set
diff --git a/docs/examples/anyauthput.c b/docs/examples/anyauthput.c
new file mode 100644
index 000000000..c5486333e
--- /dev/null
+++ b/docs/examples/anyauthput.c
@@ -0,0 +1,135 @@
+/*****************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * $Id$
+ */
+
+#include <stdio.h>
+#include <fcntl.h>
+#include <sys/stat.h>
+
+#include <curl/curl.h>
+
+#if LIBCURL_VERSION_NUM < 0x070c03
+#error "upgrade your libcurl to no less than 7.12.3"
+#endif
+
+/*
+ * This example shows a HTTP PUT operation with authentiction using "any"
+ * type. It PUTs a file given as a command line argument to the URL also given
+ * on the command line.
+ *
+ * Since libcurl 7.12.3, using "any" auth and POST/PUT requires a set ioctl
+ * function.
+ *
+ * This example also uses its own read callback.
+ */
+
+/* ioctl callback function */
+static curlioerr my_ioctl(CURL *handle, curliocmd cmd, void *userp)
+{
+  int fd = (int)userp;
+
+  (void)handle; /* not used in here */
+
+  switch(cmd) {
+  case CURLIOCMD_RESTARTREAD:
+    /* mr libcurl kindly asks as to rewind the read data stream to start */
+    if(-1 == lseek(fd, 0, SEEK_SET))
+      /* couldn't rewind */
+      return CURLIOE_FAILRESTART;
+
+    break;
+
+  default: /* ignore unknown commands */
+    return CURLIOE_UNKNOWNCMD;
+  }
+  return CURLIOE_OK; /* success! */
+}
+
+/* read callback function, fread() look alike */
+size_t read_callback(void *ptr, size_t size, size_t nmemb, void *stream)
+{
+  size_t retcode;
+
+  int fd = (int)stream;
+
+  retcode = read(fd, ptr, size * nmemb);
+
+  fprintf(stderr, "*** We read %d bytes from file\n", retcode);
+
+  return retcode;
+}
+
+int main(int argc, char **argv)
+{
+  CURL *curl;
+  CURLcode res;
+  int hd ;
+  struct stat file_info;
+
+  char *file;
+  char *url;
+
+  if(argc < 3)
+    return 1;
+
+  file= argv[1];
+  url = argv[2];
+
+  /* get the file size of the local file */
+  hd = open(file, O_RDONLY) ;
+  fstat(hd, &file_info);
+
+  /* In windows, this will init the winsock stuff */
+  curl_global_init(CURL_GLOBAL_ALL);
+
+  /* get a curl handle */
+  curl = curl_easy_init();
+  if(curl) {
+    /* we want to use our own read function */
+    curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
+
+    /* which file to upload */
+    curl_easy_setopt(curl, CURLOPT_READDATA, hd);
+
+    /* set the ioctl function */
+    curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, my_ioctl);
+
+    /* pass the file descriptor to the ioctl callback as well */
+    curl_easy_setopt(curl, CURLOPT_IOCTLDATA, hd);
+
+    /* enable "uploading" (which means PUT when doing HTTP) */
+    curl_easy_setopt(curl, CURLOPT_UPLOAD, TRUE) ;
+
+    /* specify target URL, and note that this URL should also include a file
+       name, not only a directory (as you can do with GTP uploads) */
+    curl_easy_setopt(curl,CURLOPT_URL, url);
+
+    /* and give the size of the upload, this supports large file sizes
+       on systems that have general support for it */
+    curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, file_info.st_size);
+
+    /* tell libcurl we can use "any" auth, which lets the lib pick one, but it
+       also costs one extra round-trip and possibly sending of all the PUT
+       data twice!!! */
+    curl_easy_setopt(curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
+
+    /* set user name and password for the authentication */
+    curl_easy_setopt(curl, CURLOPT_USERPWD, "user:password");
+
+    /* Now run off and do what you've been told! */
+    res = curl_easy_perform(curl);
+
+    /* always cleanup */
+    curl_easy_cleanup(curl);
+  }
+  close(hd); /* close the local file */
+
+  curl_global_cleanup();
+  return 0;
+}
diff --git a/docs/examples/https.c b/docs/examples/https.c
index 9ce5a308b..8ce7c0b3a 100644
--- a/docs/examples/https.c
+++ b/docs/examples/https.c
@@ -1,8 +1,8 @@
 /*****************************************************************************
- *                                  _   _ ____  _     
- *  Project                     ___| | | |  _ \| |    
- *                             / __| | | | |_) | |    
- *                            | (__| |_| |  _ <| |___ 
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
  * $Id$
diff --git a/docs/examples/multi-post.c b/docs/examples/multi-post.c
index b5a436449..0f9a599ac 100644
--- a/docs/examples/multi-post.c
+++ b/docs/examples/multi-post.c
@@ -1,8 +1,8 @@
 /*****************************************************************************
- *                                  _   _ ____  _     
- *  Project                     ___| | | |  _ \| |    
- *                             / __| | | | |_) | |    
- *                            | (__| |_| |  _ <| |___ 
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
  * $Id$
diff --git a/docs/examples/persistant.c b/docs/examples/persistant.c
index 0a17031b8..673889914 100644
--- a/docs/examples/persistant.c
+++ b/docs/examples/persistant.c
@@ -1,8 +1,8 @@
 /*****************************************************************************
- *                                  _   _ ____  _     
- *  Project                     ___| | | |  _ \| |    
- *                             / __| | | | |_) | |    
- *                            | (__| |_| |  _ <| |___ 
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
  * $Id$
diff --git a/docs/examples/simplepost.c b/docs/examples/simplepost.c
index 57c1f61d7..1d156c583 100644
--- a/docs/examples/simplepost.c
+++ b/docs/examples/simplepost.c
@@ -1,8 +1,8 @@
 /*****************************************************************************
- *                                  _   _ ____  _     
- *  Project                     ___| | | |  _ \| |    
- *                             / __| | | | |_) | |    
- *                            | (__| |_| |  _ <| |___ 
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
  * $Id$
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 423858017..e75ae4a2c 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -21,7 +21,7 @@
 .\" * $Id$
 .\" **************************************************************************
 .\"
-.TH curl_easy_setopt 3 "12 Mar 2004" "libcurl 7.11.1" "libcurl Manual"
+.TH curl_easy_setopt 3 "21 Nov 2004" "libcurl 7.12.3" "libcurl Manual"
 .SH NAME
 curl_easy_setopt - set options for a curl easy handle
 .SH SYNOPSIS
@@ -142,6 +142,18 @@ don't specify a read callback, this must be a valid FILE *.
 
 This option is also known with the older name \fICURLOPT_INFILE\fP, the name
 \fICURLOPT_READDATA\fP was introduced in 7.9.7.
+.IP CURLOPT_IOCTLFUNCTION
+Function pointer that should match the \fIcurl_ioctl_callback\fP prototype
+found in \fI<curl/curl.h>\fP. This function gets called by libcurl when
+something special I/O-related needs to be done that the library can't do by
+itself. For now, rewinding the read data stream is the only action it can
+request. The rewinding of the read data stream may be necessary when doing a
+HTTP PUT or POST with a multi-pass authentication method.  (Opion added in
+7.12.3)
+.IP CURLOPT_IOCTLDATA
+Pass a pointer that will be untouched by libcurl and passed as the 3rd
+argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP.  (Option
+added in 7.12.3)
 .IP CURLOPT_PROGRESSFUNCTION
 Function pointer that should match the \fIcurl_progress_callback\fP prototype
 found in \fI<curl/curl.h>\fP. This function gets called by libcurl instead of