[GNUnet-SVN] r12847 - in libmicrohttpd: doc src/daemon

[gnunet]

Author: grothoff
Date: 2010-09-05 13:58:38 +0200 (Sun, 05 Sep 2010)
New Revision: 12847

Modified:
   libmicrohttpd/doc/microhttpd.texi
   libmicrohttpd/src/daemon/digestauth.c
Log:
  Hi Christian,
        Please see attached a patch for digest authentication documentation.

Thanks,
Amr Ali


Modified: libmicrohttpd/doc/microhttpd.texi
===================================================================
--- libmicrohttpd/doc/microhttpd.texi   2010-09-05 10:04:49 UTC (rev 12846)
+++ libmicrohttpd/doc/microhttpd.texi   2010-09-05 11:58:38 UTC (rev 12847)
@@ -117,6 +117,7 @@
 * microhttpd-inspect::          Implementing external @code{select}.
 * microhttpd-requests::         Handling requests.
 * microhttpd-responses::        Building responses to requests.
+* microhttpd-dauth::                   Utilizing Digest Authentication.
 * microhttpd-post::             Adding a @code{POST} processor.
 * microhttpd-info::             Obtaining status information.
 
@@ -451,6 +452,17 @@
 are acceptable for the application.  The string is passed
 unchanged to gnutls_priority_init.  If this option is not
 specified, ``NORMAL'' is used.
+
address@hidden MHD_OPTION_DIGEST_AUTH_RANDOM
address@hidden digest auth
address@hidden random
+Digest Authentication nonce's seed.
+This option must be followed by an "const char *" argument
+specifying a NULL terminated array of randomly generated values
+to be used in generating the server nonce when using digest authentication.
+It is a MUST to supply these values before utilizing any of MHD
+digest authentication functions, as otherwise, it will read from
+an arbitrary address in memory which results in an undefined behavior.
   
 @item MHD_OPTION_LISTEN_SOCKET
 @cindex systemd
@@ -1330,6 +1342,113 @@
 @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 @c ------------------------------------------------------------
address@hidden microhttpd-dauth
address@hidden Utilizing Digest Authentication
+
address@hidden {char *} MHD_digest_auth_get_username(struct MHD_Connection 
*connection)
+Find and return a pointer to the username value from the request header.
+Return @mynull{} if the value is not found or header does not exist.
+If returned value is not @mynull{}, the value must be free()'ed.
address@hidden deftypefun
+
address@hidden int MHD_digest_auth_check(struct MHD_Connection *connection, 
const char *realm, const char *username, const char *password, unsigned int 
nonce_timeout)
+Checks if the provided values in the WWW-Authenticate header are valid
+and sound according to RFC2716. If valid return MHD_YES, otherwise return 
MHD_NO.
+
address@hidden must reference to a zero-terminated string representing the 
realm.
+
address@hidden must reference to a zero-terminated string representing the 
username,
+it is usually the returned value from MHD_digest_auth_get_username.
+
address@hidden must reference to a zero-terminated string representing the 
password,
+most probably it will be the result of a lookup of the username against a 
local database.
+
address@hidden is the amount of time in seconds for a nonce to be invalid.
+Most of the time it is sound to specify 300 seconds as its values.
address@hidden deftypefun
+
address@hidden int MHD_queue_auth_fail_response(struct MHD_Connection 
*connection, const char *realm, const char *opaque, struct MHD_Response 
*response, int signal_stale)
+Queues a response to request authentication from the client,
+return MHD_YES if successful, otherwise MHD_NO.
+
address@hidden must reference to a zero-terminated string representing a value
+that gets passed to the client and expected to be passed again to the server
+as-is. This value can be a hexadecimal or base64 string.
+
address@hidden a response structure to specify what shall be presented to the
+client with a 401 HTTP status.
+
address@hidden a value that signals "stale=true" in the response header to
+indicate the invalidity of the nonce and no need to ask for authentication
+parameters and only a new nonce gets generated. MHD_YES to generate a new
+nonce, MHD_NO to ask for authentication parameters.
address@hidden deftypefun
+
+Example: handling digest authentication requests and responses.
+
address@hidden
+#define PAGE "<html><head><title>libmicrohttpd demo</title></head><body>Access 
granted</body></html>"
+#define DENIED "<html><head><title>libmicrohttpd 
demo</title></head><body>Access denied</body></html>"
+#define OPAQUE "11733b200778ce33060f31c9af70a870ba96ddd4"
+
+static int
+ahc_echo (void *cls,
+          struct MHD_Connection *connection,
+          const char *url,
+          const char *method,
+          const char *version,
+          const char *upload_data, size_t *upload_data_size, void **ptr)
+{
+  struct MHD_Response *response;
+  char *username;
+  const char *password = "testpass";
+  const char *realm = "address@hidden";
+  int ret;
+
+  username = MHD_digest_auth_get_username(connection);
+  if (username == NULL) 
+    {
+      response = MHD_create_response_from_data(strlen (DENIED), 
+                                              DENIED,
+                                              MHD_NO, MHD_NO);  
+      ret = MHD_queue_auth_fail_response(connection, realm,
+                                        OPAQUE,
+                                        response,
+                                        MHD_NO);    
+      MHD_destroy_response(response);  
+      return ret;
+    }
+  ret = MHD_digest_auth_check(connection, realm,
+                             username, 
+                             password, 
+                             300);
+  free(username);
+  if ( (ret == MHD_INVALID_NONCE) ||
+       (ret == MHD_NO) )
+    {
+      response = MHD_create_response_from_data(strlen (DENIED), 
+                                              DENIED,
+                                              MHD_NO, MHD_NO);  
+      if (NULL == response) 
+       return MHD_NO;
+      ret = MHD_queue_auth_fail_response(connection, realm,
+                                        OPAQUE,
+                                        response,
+                                        (ret == MHD_INVALID_NONCE) ? MHD_YES : 
MHD_NO);  
+      MHD_destroy_response(response);  
+      return ret;
+    }
+  response = MHD_create_response_from_data(strlen(PAGE), PAGE,
+                                          MHD_NO, MHD_NO);
+  ret = MHD_queue_response(connection, MHD_HTTP_OK, response);  
+  MHD_destroy_response(response);
+  return ret;
+}
address@hidden example
+
address@hidden ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
address@hidden ------------------------------------------------------------
 @node microhttpd-post
 @chapter Adding a @code{POST} processor
 @cindex POST method

Modified: libmicrohttpd/src/daemon/digestauth.c
===================================================================
--- libmicrohttpd/src/daemon/digestauth.c       2010-09-05 10:04:49 UTC (rev 
12846)
+++ libmicrohttpd/src/daemon/digestauth.c       2010-09-05 11:58:38 UTC (rev 
12847)
@@ -309,14 +309,16 @@
 
 
 /**
- * FIXME: document
+ * Calculate the server nonce so that it mitigates replay attacks
+ * The current format of the nonce is ...
+ * H(timestamp ":" method ":" random ":" uri ":" realm) + Hex(timestamp)
  *
- * @param nonce_time  FIXME: document
- * @param method  FIXME: document
- * @param rnd  FIXME: document
- * @param uri  FIXME: document
- * @param realm  FIXME: document
- * @param nonce  FIXME: document
+ * @param nonce_time The amount of time in seconds for a nonce to be invalid
+ * @param method HTTP method
+ * @param rnd A pointer to a character array for the random seed
+ * @param uri HTTP URI
+ * @param realm A string of characters that describes the realm of auth.
+ * @param nonce A pointer to a character array for the nonce to put in
  */
 static void
 calculate_nonce (uint32_t nonce_time,