[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r14085 - libmicrohttpd-docs/WWW
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] r14085 - libmicrohttpd-docs/WWW |
|
Date: |
Sat, 25 Dec 2010 23:19:02 +0100 |
Author: grothoff
Date: 2010-12-25 23:19:02 +0100 (Sat, 25 Dec 2010)
New Revision: 14085
Modified:
libmicrohttpd-docs/WWW/microhttpd.html
libmicrohttpd-docs/WWW/microhttpd.pdf
libmicrohttpd-docs/WWW/tutorial.html
libmicrohttpd-docs/WWW/tutorial.pdf
Log:
update
Modified: libmicrohttpd-docs/WWW/microhttpd.html
===================================================================
--- libmicrohttpd-docs/WWW/microhttpd.html 2010-12-25 22:18:51 UTC (rev
14084)
+++ libmicrohttpd-docs/WWW/microhttpd.html 2010-12-25 22:19:02 UTC (rev
14085)
@@ -1,7 +1,7 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html401/loose.dtd";>
<html>
-<!-- This manual documents GNU libmicrohttpd version 0.9.1, last
-updated 10 September 2010. It is built upon the documentation in the
+<!-- This manual documents GNU libmicrohttpd version 0.9.4, last
+updated 25 December 2010. It is built upon the documentation in the
header file microhttpd.h.
@@ -16,7 +16,7 @@
GNU libmicrohttpd is a GNU package.
-->
-<!-- Created on September 10, 2010 by texi2html 1.82
+<!-- Created on December 25, 2010 by texi2html 1.82
texi2html was written by:
Lionel Cons <address@hidden> (original author)
Karl Berry <address@hidden>
@@ -66,8 +66,8 @@
</tr></table>
<a name="The-GNU-libmicrohttpd-Library"></a>
<h1 class="settitle">The GNU libmicrohttpd Library</h1>
-<p>This manual documents GNU libmicrohttpd version 0.9.1, last
-updated 10 September 2010. It is built upon the documentation in the
+<p>This manual documents GNU libmicrohttpd version 0.9.4, last
+updated 25 December 2010. It is built upon the documentation in the
header file ‘<tt>microhttpd.h</tt>’.
</p>
@@ -92,7 +92,7 @@
<tr><td align="left" valign="top"><a href="#microhttpd_002drequests">7.
Handling requests</a></td><td> </td><td align="left"
valign="top"></td></tr>
<tr><td align="left" valign="top"><a href="#microhttpd_002dresponses">8.
Building answers to responses</a></td><td> </td><td align="left"
valign="top"> Building responses to requests.
</td></tr>
-<tr><td align="left" valign="top"><a href="#microhttpd_002ddauth">9. Utilizing
Digest Authentication</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#microhttpd_002ddauth">9. Utilizing
Authentication</a></td><td> </td><td align="left"
valign="top"></td></tr>
<tr><td align="left" valign="top"><a href="#microhttpd_002dpost">10. Adding a
<code>POST</code> processor</a></td><td> </td><td align="left"
valign="top"></td></tr>
<tr><td align="left" valign="top"><a href="#microhttpd_002dinfo">11. Obtaining
status information.</a></td><td> </td><td align="left"
valign="top"></td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
@@ -224,7 +224,7 @@
<a name="SIGPIPE"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a
href="#Including-the-microhttpd_002eh-header" title="Previous section in
reading order"> < </a>]</td>
-<td valign="middle" align="left">[<a href="#microhttpd_002dconst" title="Next
section in reading order"> > </a>]</td>
+<td valign="middle" align="left">[<a href="#MHD_005fLONG_005fLONG" title="Next
section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#microhttpd_002dintro"
title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#microhttpd_002dintro" title="Up
section"> Up </a>]</td>
@@ -275,12 +275,43 @@
"Failed to install SIGPIPE handler: %s\n", strerror
(errno));
}
</pre>
+<hr size="6">
+<a name="MHD_005fLONG_005fLONG"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SIGPIPE" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002dconst" title="Next
section in reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#microhttpd_002dintro"
title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002dintro" title="Up
section"> Up </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002dconst" title="Next
chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#Concept-Index"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section">1.3 MHD_LONG_LONG</h2>
+<a name="index-long-long"></a>
+<a name="index-IAR"></a>
+<a name="index-ARM"></a>
+<a name="index-cortex-m3"></a>
+<p>Some platforms do not support <code>long long</code>. Hence MHD defines
+a macro <code>MHD_LONG_LONG</code> which will default to <code>long
long</code>.
+If your platform does not support <code>long long</code>, you should
+change "platform.h" to define <code>MHD_LONG_LONG</code> to an
appropriate
+alternative type and also define <code>MHD_LONG_LONG_PRINTF</code> to the
+corresponding format string for printing such a data type (without
+the percent sign).
+</p>
<hr size="6">
<a name="microhttpd_002dconst"></a>
<table cellpadding="1" cellspacing="1" border="0">
-<tr><td valign="middle" align="left">[<a href="#SIGPIPE" title="Previous
section in reading order"> < </a>]</td>
+<tr><td valign="middle" align="left">[<a href="#MHD_005fLONG_005fLONG"
title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#microhttpd_002dstruct" title="Next
section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#microhttpd_002dintro"
title="Beginning of this chapter or previous chapter"> << </a>]</td>
@@ -499,17 +530,32 @@
This should be used in conjunction with ’MHD_OPTION_HTTPS_MEM_KEY’.
</p>
</dd>
-<dt> <code>MHD_OPTION_HTTPS_CRED_TYPE</code></dt>
+<dt> <code>MHD_OPTION_HTTPS_MEM_TRUST</code></dt>
<dd><a name="index-SSL-2"></a>
<a name="index-TLS-2"></a>
+<p>Memory pointer to the CA certificate to be used by the
+HTTPS daemon to authenticate and trust clients certificates.
+This option should be followed by an "const char*" argument.
+The presence of this option activates the request of certificate
+to the client. The request to the client is marked optional, and
+it is the responsability of the server to check the presence
+of the certificate if needed.
+Note that most browsers will only present a client certificate
+only if they have one matching the specified CA, not sending
+any certificate otherwise.
+</p>
+</dd>
+<dt> <code>MHD_OPTION_HTTPS_CRED_TYPE</code></dt>
+<dd><a name="index-SSL-3"></a>
+<a name="index-TLS-3"></a>
<p>Daemon credentials type. Either certificate or anonymous,
this option should be followed by one of the values listed in
"enum gnutls_credentials_type_t".
</p>
</dd>
<dt> <code>MHD_OPTION_HTTPS_PRIORITIES</code></dt>
-<dd><a name="index-SSL-3"></a>
-<a name="index-TLS-3"></a>
+<dd><a name="index-SSL-4"></a>
+<a name="index-TLS-4"></a>
<a name="index-cipher"></a>
<p>SSL/TLS protocol version and ciphers.
This option must be followwed by an "const char *" argument
@@ -632,7 +678,17 @@
(the result must be shorter than the input and still be 0-terminated).
<code>cls</code> will be set to the second argument following
MHD_OPTION_UNESCAPE_CALLBACK.
-</p></dd>
+</p>
+
+</dd>
+<dt> <code>MHD_OPTION_THREAD_STACK_SIZE</code></dt>
+<dd><a name="index-stack_002c-thread_002c-pthread"></a>
+<p>Maximum stack size for threads created by MHD. This option must be
+followed by a <code>size_t</code>). Not specifying this option or using
+a value of zero means using the system default (which is likely to
+differ based on your platform).
+</p>
+</dd>
</dl>
</dd></dl>
@@ -740,8 +796,9 @@
</p>
</dd>
<dt> <code>MHD_CONNECTION_INFO_GNUTLS_SESSION,</code></dt>
-<dd><p>Takes no extra arguments. Allows access to the underlying GNUtls
session
-(HTTPS connections only).
+<dd><p>Takes no extra arguments. Allows access to the underlying GNUtls
session,
+including access to the underlying GNUtls client certificate
+(HTTPS connections only). Takes no extra arguments.
</p>
</dd>
</dl>
@@ -1005,7 +1062,7 @@
<dl>
-<dt><a name="index-_002aMHD_005fContentReaderCallback"></a><u>Function
Pointer:</u> int <b>*MHD_ContentReaderCallback</b><i> (void *cls, uint64_t pos,
char *buf, int max)</i></dt>
+<dt><a name="index-_002aMHD_005fContentReaderCallback"></a><u>Function
Pointer:</u> int <b>*MHD_ContentReaderCallback</b><i> (void *cls, uint64_t pos,
char *buf, size_t max)</i></dt>
<dd><p>Callback used by <acronym>MHD</acronym> in order to obtain content.
The callback has to
copy at most <var>max</var> bytes of content into <var>buf</var>. The total
number of bytes that has been placed into <var>buf</var> should be returned.
@@ -1018,6 +1075,29 @@
would result in busy waiting) and cause the program to be aborted
(<code>abort()</code>).
</p>
+<p>While usually the callback simply returns the number of bytes written
+into <var>buf</var>, there are two special return value:
+</p>
+<p><code>MHD_CONTENT_READER_END_OF_STREAM</code> (-1) should be returned
+for the regular end of transmission (with chunked encoding, MHD will then
+terminate the chunk and send any HTTP footers that might be
+present; without chunked encoding and given an unknown
+response size, <acronym>MHD</acronym> will simply close the connection; note
+that while returning <code>MHD_CONTENT_READER_END_OF_STREAM</code> is not
technically
+legal if a response size was specified, MHD accepts this
+and treats it just as <code>MHD_CONTENT_READER_END_WITH_ERROR</code>.
+</p>
+<p><code>MHD_CONTENT_READER_END_WITH_ERROR</code> (-2) is used to indicate a
server
+error generating the response; this will cause <acronym>MHD</acronym> to simply
+close the connection immediately. If a response size was
+given or if chunked encoding is in use, this will indicate
+an error to the client. Note, however, that if the client
+does not know a response size and chunked encoding is not in
+use, then clients will not be able to tell the difference between
+<code>MHD_CONTENT_READER_END_WITH_ERROR</code> and
+<code>MHD_CONTENT_READER_END_OF_STREAM</code>.
+This is not a limitation of <acronym>MHD</acronym> but rather of the HTTP
protocol.
+</p>
<dl compact="compact">
<dt> <var>cls</var></dt>
<dd><p>custom value selected at callback registration time;
@@ -1371,8 +1451,7 @@
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a
href="#microhttpd_002dresponse-enqueue">8.1 Enqueuing a
response</a></td><td> </td><td align="left" valign="top"></td></tr>
-<tr><td align="left" valign="top"><a
href="#microhttpd_002dresponse-create">8.2 Creating response
objects</a></td><td> </td><td align="left" valign="top"> Creating a
response object.
-</td></tr>
+<tr><td align="left" valign="top"><a
href="#microhttpd_002dresponse-create">8.2 Creating a response
object</a></td><td> </td><td align="left" valign="top"></td></tr>
<tr><td align="left" valign="top"><a
href="#microhttpd_002dresponse-headers">8.3 Adding headers to a
response</a></td><td> </td><td align="left" valign="top"></td></tr>
<tr><td align="left" valign="top"><a
href="#microhttpd_002dresponse-inspect">8.4 Inspecting a response
object</a></td><td> </td><td align="left" valign="top"></td></tr>
</table>
@@ -1489,8 +1568,8 @@
<td valign="middle" align="left">[<a href="#Concept-Index"
title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
</tr></table>
-<a name="Creating-response-objects"></a>
-<h2 class="section">8.2 Creating response objects</h2>
+<a name="Creating-a-response-object"></a>
+<h2 class="section">8.2 Creating a response object</h2>
<dl>
@@ -1535,12 +1614,15 @@
</p>
<dl compact="compact">
<dt> <var>size</var></dt>
-<dd><p>size of the data portion of the response, <code>-1</code> for unknown;
+<dd><p>size of the data portion of the response (should be smaller or equal to
the
+size of the file)
</p>
</dd>
<dt> <var>fd</var></dt>
<dd><p>file descriptor referring to a file on disk with the data; will be
-closed when response is destroyed
+closed when response is destroyed; note that ’fd’ must be an
actual
+file descriptor (not a pipe or socket) since MHD might use
’sendfile’
+or ’seek’ on it
</p></dd>
</dl>
@@ -1549,6 +1631,33 @@
<dl>
+<dt><a
name="index-MHD_005fcreate_005fresponse_005ffrom_005ffd_005fat_005foffset"></a><u>Function:</u>
struct MHD_Response * <b>MHD_create_response_from_fd_at_offset</b><i>
(uint64_t size, int fd, off_t offset)</i></dt>
+<dd><p>Create a response object. The response object can be extended with
+header information and then it can be used any number of times.
+</p>
+<dl compact="compact">
+<dt> <var>size</var></dt>
+<dd><p>size of the data portion of the response (number of bytes to transmit
from the
+file starting at offset).
+</p>
+</dd>
+<dt> <var>fd</var></dt>
+<dd><p>file descriptor referring to a file on disk with the data; will be
+closed when response is destroyed; note that ’fd’ must be an
actual
+file descriptor (not a pipe or socket) since MHD might use
’sendfile’
+or ’seek’ on it
+</p>
+</dd>
+<dt> <var>offset</var></dt>
+<dd><p>offset to start reading from in the file
+</p></dd>
+</dl>
+
+<p>Return <code>NULL</code> on error (i.e. invalid arguments, out of memory).
+</p></dd></dl>
+
+
+<dl>
<dt><a
name="index-MHD_005fcreate_005fresponse_005ffrom_005fdata"></a><u>Function:</u>
struct MHD_Response * <b>MHD_create_response_from_data</b><i> (size_t size,
void *data, int must_free, int must_copy)</i></dt>
<dd><p>Create a response object. The response object can be extended with
header information and then it can be used any number of times.
@@ -1631,8 +1740,27 @@
<dl>
+<dt><a name="index-MHD_005fadd_005fresponse_005ffooter"></a><u>Function:</u>
int <b>MHD_add_response_footer</b><i> (struct MHD_Response *response, const
char *footer, const char *content)</i></dt>
+<dd><p>Add a footer line to the response. The strings referenced by
+<var>footer</var> and <var>content</var> must be zero-terminated and they are
+duplicated into memory blocks embedded in <var>response</var>.
+</p>
+<p>Notice that the strings must not hold newlines, carriage returns or tab
+chars. You can add response footers at any time before signalling the
+end of the response to MHD (not just before calling
’MHD_queue_response’).
+Footers are useful for adding cryptographic checksums to the reply or to
+signal errors encountered during data generation. This call was introduced
+in MHD 0.9.3.
+</p>
+<p>Return <code>MHD_NO</code> on error (i.e. invalid header or content format
or
+memory allocation error).
+</p></dd></dl>
+
+
+
+<dl>
<dt><a name="index-MHD_005fdel_005fresponse_005fheader"></a><u>Function:</u>
int <b>MHD_del_response_header</b><i> (struct MHD_Response *response, const
char *header, const char *content)</i></dt>
-<dd><p>Delete a header line from the response. Return <code>MHD_NO</code> on
error
+<dd><p>Delete a header (or footer) line from the response. Return
<code>MHD_NO</code> on error
(arguments are invalid or no such header known).
</p></dd></dl>
@@ -1690,7 +1818,7 @@
<a name="microhttpd_002ddauth"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a
href="#microhttpd_002dresponse-inspect" title="Previous section in reading
order"> < </a>]</td>
-<td valign="middle" align="left">[<a href="#microhttpd_002dpost" title="Next
section in reading order"> > </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002ddauth-basic"
title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#microhttpd_002dresponses"
title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Top" title="Up section"> Up
</a>]</td>
@@ -1704,20 +1832,114 @@
<td valign="middle" align="left">[<a href="#Concept-Index"
title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
</tr></table>
-<a name="Utilizing-Digest-Authentication"></a>
-<h1 class="chapter">9. Utilizing Digest Authentication</h1>
+<a name="Utilizing-Authentication"></a>
+<h1 class="chapter">9. Utilizing Authentication</h1>
+<p><acronym>MHD</acronym> support three types of client authentication.
+</p>
+<p>Basic authentication uses a simple authentication method based
+on BASE64 algorithm. Username and password are exchanged in clear
+between the client and the server, so this method must only be used
+for non-sensitive content or when the session is protected with https.
+When using basic authentication <acronym>MHD</acronym> will have access to the
clear
+password, possibily allowing to create a chained authentication
+toward an external authentication server.
+</p>
+<p>Digest authentication uses a one-way authentication method based
+on MD5 hash algorithm. Only the hash will transit over the network,
+hence protecting the user password. The nonce will prevent replay
+attacks. This method is appropriate for general use, especially
+when https is not used to encrypt the session.
+</p>
+<p>Client certificate authentication uses a X.509 certificate from
+the client. This is the strongest authentication mechanism but it
+requires the use of HTTPS. Client certificate authentication can
+be used simultaneously with Basic or Digest Authentication in order
+to provide a two levels authentication (like for instance separate
+machine and user authentication). A code example for using
+client certificates is presented in the <acronym>MHD</acronym> tutorial.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#microhttpd_002ddauth-basic">9.1
Using Basic Authentication</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#microhttpd_002ddauth-digest">9.2
Using Digest Authentication</a></td><td> </td><td align="left"
valign="top"></td></tr>
+</table>
+
+
+<hr size="6">
+<a name="microhttpd_002ddauth-basic"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#microhttpd_002ddauth"
title="Previous section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002ddauth-digest"
title="Next section in reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#microhttpd_002ddauth"
title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002ddauth" title="Up
section"> Up </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002dpost" title="Next
chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#Concept-Index"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<a name="Using-Basic-Authentication"></a>
+<h2 class="section">9.1 Using Basic Authentication</h2>
+
<dl>
+<dt><a
name="index-MHD_005fbasic_005fauth_005fget_005fusername_005fpassword"></a><u>Function:</u>
char * <b>MHD_basic_auth_get_username_password</b><i> (struct MHD_Connection
*connection, char** password)</i></dt>
+<dd><p>Get the username and password from the basic authorization header sent
by the client.
+Return <code>NULL</code> if no username could be found, a pointer to the
username if found.
+If returned value is not <code>NULL</code>, the value must be
<code>free()</code>’ed.
+</p>
+<p><var>password</var> reference a buffer to store the password. It can be
<code>NULL</code>.
+If returned value is not <code>NULL</code>, the value must be
<code>free()</code>’ed.
+</p></dd></dl>
+
+<dl>
+<dt><a
name="index-MHD_005fqueue_005fbasic_005fauth_005ffail_005fresponse"></a><u>Function:</u>
int <b>MHD_queue_basic_auth_fail_response</b><i> (struct MHD_Connection
*connection, const char *realm, struct MHD_Response *response)</i></dt>
+<dd><p>Queues a response to request basic authentication from the client.
+Return <code>MHD_YES</code> if successful, otherwise <code>MHD_NO</code>.
+</p>
+<p><var>realm</var> must reference to a zero-terminated string representing
the realm.
+</p>
+<p><var>response</var> a response structure to specify what shall be presented
to the
+client with a 401 HTTP status.
+</p></dd></dl>
+
+
+<hr size="6">
+<a name="microhttpd_002ddauth-digest"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#microhttpd_002ddauth-basic"
title="Previous section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002dpost" title="Next
section in reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#microhttpd_002ddauth"
title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002ddauth" title="Up
section"> Up </a>]</td>
+<td valign="middle" align="left">[<a href="#microhttpd_002dpost" title="Next
chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#Concept-Index"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<a name="Using-Digest-Authentication"></a>
+<h2 class="section">9.2 Using Digest Authentication</h2>
+
+<dl>
<dt><a
name="index-MHD_005fdigest_005fauth_005fget_005fusername"></a><u>Function:</u>
char * <b>MHD_digest_auth_get_username</b><i> (struct MHD_Connection
*connection)</i></dt>
<dd><p>Find and return a pointer to the username value from the request header.
Return <code>NULL</code> if the value is not found or header does not exist.
-If returned value is not <code>NULL</code>, the value must be free()’ed.
+If returned value is not <code>NULL</code>, the value must be
<code>free()</code>’ed.
</p></dd></dl>
<dl>
<dt><a name="index-MHD_005fdigest_005fauth_005fcheck"></a><u>Function:</u> int
<b>MHD_digest_auth_check</b><i> (struct MHD_Connection *connection, const char
*realm, const char *username, const char *password, unsigned int
nonce_timeout)</i></dt>
<dd><p>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.
+and sound according to RFC2716. If valid return <code>MHD_YES</code>,
otherwise return <code>MHD_NO</code>.
</p>
<p><var>realm</var> must reference to a zero-terminated string representing
the realm.
</p>
@@ -1734,8 +1956,10 @@
<dl>
<dt><a
name="index-MHD_005fqueue_005fauth_005ffail_005fresponse"></a><u>Function:</u>
int <b>MHD_queue_auth_fail_response</b><i> (struct MHD_Connection *connection,
const char *realm, const char *opaque, struct MHD_Response *response, int
signal_stale)</i></dt>
<dd><p>Queues a response to request authentication from the client,
-return MHD_YES if successful, otherwise MHD_NO.
+return <code>MHD_YES</code> if successful, otherwise <code>MHD_NO</code>.
</p>
+<p><var>realm</var> must reference to a zero-terminated string representing
the realm.
+</p>
<p><var>opaque</var> 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.
@@ -1745,8 +1969,8 @@
</p>
<p><var>signal_stale</var> 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.
+parameters and only a new nonce gets generated. <code>MHD_YES</code> to
generate a new
+nonce, <code>MHD_NO</code> to ask for authentication parameters.
</p></dd></dl>
<p>Example: handling digest authentication requests and responses.
@@ -1814,7 +2038,7 @@
<hr size="6">
<a name="microhttpd_002dpost"></a>
<table cellpadding="1" cellspacing="1" border="0">
-<tr><td valign="middle" align="left">[<a href="#microhttpd_002ddauth"
title="Previous section in reading order"> < </a>]</td>
+<tr><td valign="middle" align="left">[<a href="#microhttpd_002ddauth-digest"
title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#microhttpd_002dpost-api"
title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#microhttpd_002ddauth"
title="Beginning of this chapter or previous chapter"> << </a>]</td>
@@ -3679,8 +3903,10 @@
<a name="Concept-Index-1"></a>
<h1 class="unnumbered">Concept Index</h1>
-<table><tr><th valign="top">Jump to: </th><td><a
href="#Concept-Index-1_cp_letter-B" class="summary-letter"><b>B</b></a>
+<table><tr><th valign="top">Jump to: </th><td><a
href="#Concept-Index-1_cp_letter-A" class="summary-letter"><b>A</b></a>
+<a href="#Concept-Index-1_cp_letter-B" class="summary-letter"><b>B</b></a>
+
<a href="#Concept-Index-1_cp_letter-C" class="summary-letter"><b>C</b></a>
<a href="#Concept-Index-1_cp_letter-D" class="summary-letter"><b>D</b></a>
@@ -3713,6 +3939,9 @@
<table border="0" class="index-cp">
<tr><td></td><th align="left">Index Entry</th><th align="left">
Section</th></tr>
<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="Concept-Index-1_cp_letter-A">A</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#index-ARM">ARM</a></td><td
valign="top"><a href="#MHD_005fLONG_005fLONG">1.3 MHD_LONG_LONG</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
<tr><th><a name="Concept-Index-1_cp_letter-B">B</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a
href="#index-bind_002c-restricting-bind">bind, restricting bind</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td colspan="3"> <hr></td></tr>
@@ -3720,6 +3949,7 @@
<tr><td></td><td valign="top"><a href="#index-cipher">cipher</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-connection_002c-limiting-number-of-connections">connection,
limiting number of connections</a></td><td valign="top"><a
href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cookie">cookie</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-cortex-m3">cortex m3</a></td><td
valign="top"><a href="#MHD_005fLONG_005fLONG">1.3 MHD_LONG_LONG</a></td></tr>
<tr><td colspan="3"> <hr></td></tr>
<tr><th><a name="Concept-Index-1_cp_letter-D">D</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-debugging">debugging</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
@@ -3739,6 +3969,7 @@
<tr><td></td><td valign="top"><a
href="#index-GPL_002c-GNU-General-Public-License">GPL, GNU General Public
License</a></td><td valign="top"><a href="#GNU-GPL-with-eCos-Extension">GNU GPL
with eCos Extension</a></td></tr>
<tr><td colspan="3"> <hr></td></tr>
<tr><th><a name="Concept-Index-1_cp_letter-I">I</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#index-IAR">IAR</a></td><td
valign="top"><a href="#MHD_005fLONG_005fLONG">1.3 MHD_LONG_LONG</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-internationalization">internationalization</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-IPv6">IPv6</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td colspan="3"> <hr></td></tr>
@@ -3749,6 +3980,7 @@
<tr><td></td><td valign="top"><a href="#index-listen">listen</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-logging">logging</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-logging-1">logging</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-long-long">long long</a></td><td
valign="top"><a href="#MHD_005fLONG_005fLONG">1.3 MHD_LONG_LONG</a></td></tr>
<tr><td colspan="3"> <hr></td></tr>
<tr><th><a name="Concept-Index-1_cp_letter-M">M</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a
href="#index-memory_002c-limiting-memory-utilization">memory, limiting memory
utilization</a></td><td valign="top"><a href="#microhttpd_002dconst">2.
Constants</a></td></tr>
@@ -3782,6 +4014,8 @@
<tr><td></td><td valign="top"><a href="#index-SSL-1">SSL</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-SSL-2">SSL</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-SSL-3">SSL</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-SSL-4">SSL</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-stack_002c-thread_002c-pthread">stack, thread, pthread</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-systemd">systemd</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td colspan="3"> <hr></td></tr>
<tr><th><a name="Concept-Index-1_cp_letter-T">T</a></th><td></td><td></td></tr>
@@ -3792,10 +4026,13 @@
<tr><td></td><td valign="top"><a href="#index-TLS-1">TLS</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-TLS-2">TLS</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-TLS-3">TLS</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-TLS-4">TLS</a></td><td
valign="top"><a href="#microhttpd_002dconst">2. Constants</a></td></tr>
<tr><td colspan="3"> <hr></td></tr>
</table>
-<table><tr><th valign="top">Jump to: </th><td><a
href="#Concept-Index-1_cp_letter-B" class="summary-letter"><b>B</b></a>
+<table><tr><th valign="top">Jump to: </th><td><a
href="#Concept-Index-1_cp_letter-A" class="summary-letter"><b>A</b></a>
+<a href="#Concept-Index-1_cp_letter-B" class="summary-letter"><b>B</b></a>
+
<a href="#Concept-Index-1_cp_letter-C" class="summary-letter"><b>C</b></a>
<a href="#Concept-Index-1_cp_letter-D" class="summary-letter"><b>D</b></a>
@@ -3866,16 +4103,19 @@
<tr><td></td><td valign="top"><a
href="#index-_002aMHD_005fRequestCompletedCallback"><code>*MHD_RequestCompletedCallback</code></a></td><td
valign="top"><a href="#microhttpd_002dcb">4. Callback functions
definition</a></td></tr>
<tr><td colspan="3"> <hr></td></tr>
<tr><th><a
name="Function-and-Data-Index-1_fn_letter-M">M</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fadd_005fresponse_005ffooter"><code>MHD_add_response_footer</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-headers">8.3 Adding headers to
a response</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fadd_005fresponse_005fheader"><code>MHD_add_response_header</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-headers">8.3 Adding headers to
a response</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fbasic_005fauth_005fget_005fusername_005fpassword"><code>MHD_basic_auth_get_username_password</code></a></td><td
valign="top"><a href="#microhttpd_002ddauth-basic">9.1 Using Basic
Authentication</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fcreate_005fpost_005fprocessor"><code>MHD_create_post_processor</code></a></td><td
valign="top"><a href="#microhttpd_002dpost-api">10.1 Programming interface for
the <code>POST</code> processor</a></td></tr>
-<tr><td></td><td valign="top"><a
href="#index-MHD_005fcreate_005fresponse_005ffrom_005fcallback"><code>MHD_create_response_from_callback</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-create">8.2 Creating response
objects</a></td></tr>
-<tr><td></td><td valign="top"><a
href="#index-MHD_005fcreate_005fresponse_005ffrom_005fdata"><code>MHD_create_response_from_data</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-create">8.2 Creating response
objects</a></td></tr>
-<tr><td></td><td valign="top"><a
href="#index-MHD_005fcreate_005fresponse_005ffrom_005ffd"><code>MHD_create_response_from_fd</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-create">8.2 Creating response
objects</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fcreate_005fresponse_005ffrom_005fcallback"><code>MHD_create_response_from_callback</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-create">8.2 Creating a response
object</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fcreate_005fresponse_005ffrom_005fdata"><code>MHD_create_response_from_data</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-create">8.2 Creating a response
object</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fcreate_005fresponse_005ffrom_005ffd"><code>MHD_create_response_from_fd</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-create">8.2 Creating a response
object</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fcreate_005fresponse_005ffrom_005ffd_005fat_005foffset"><code>MHD_create_response_from_fd_at_offset</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-create">8.2 Creating a response
object</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fdel_005fresponse_005fheader"><code>MHD_del_response_header</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-headers">8.3 Adding headers to
a response</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fdestroy_005fpost_005fprocessor"><code>MHD_destroy_post_processor</code></a></td><td
valign="top"><a href="#microhttpd_002dpost-api">10.1 Programming interface for
the <code>POST</code> processor</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fdestroy_005fresponse"><code>MHD_destroy_response</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-enqueue">8.1 Enqueuing a
response</a></td></tr>
-<tr><td></td><td valign="top"><a
href="#index-MHD_005fdigest_005fauth_005fcheck"><code>MHD_digest_auth_check</code></a></td><td
valign="top"><a href="#microhttpd_002ddauth">9. Utilizing Digest
Authentication</a></td></tr>
-<tr><td></td><td valign="top"><a
href="#index-MHD_005fdigest_005fauth_005fget_005fusername"><code>MHD_digest_auth_get_username</code></a></td><td
valign="top"><a href="#microhttpd_002ddauth">9. Utilizing Digest
Authentication</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fdigest_005fauth_005fcheck"><code>MHD_digest_auth_check</code></a></td><td
valign="top"><a href="#microhttpd_002ddauth-digest">9.2 Using Digest
Authentication</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fdigest_005fauth_005fget_005fusername"><code>MHD_digest_auth_get_username</code></a></td><td
valign="top"><a href="#microhttpd_002ddauth-digest">9.2 Using Digest
Authentication</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fget_005fconnection_005finfo"><code>MHD_get_connection_info</code></a></td><td
valign="top"><a href="#microhttpd_002dinfo-conn">11.2 Obtaining state
information about a connection</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fget_005fconnection_005fvalues"><code>MHD_get_connection_values</code></a></td><td
valign="top"><a href="#microhttpd_002drequests">7. Handling
requests</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fget_005fdaemon_005finfo"><code>MHD_get_daemon_info</code></a></td><td
valign="top"><a href="#microhttpd_002dinfo-daemon">11.1 Obtaining state
information about an MHD daemon</a></td></tr>
@@ -3885,7 +4125,8 @@
<tr><td></td><td valign="top"><a
href="#index-MHD_005fget_005ftimeout"><code>MHD_get_timeout</code></a></td><td
valign="top"><a href="#microhttpd_002dinspect">6. Implementing external
<code>select</code></a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005flookup_005fconnection_005fvalue"><code>MHD_lookup_connection_value</code></a></td><td
valign="top"><a href="#microhttpd_002drequests">7. Handling
requests</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fpost_005fprocess"><code>MHD_post_process</code></a></td><td
valign="top"><a href="#microhttpd_002dpost-api">10.1 Programming interface for
the <code>POST</code> processor</a></td></tr>
-<tr><td></td><td valign="top"><a
href="#index-MHD_005fqueue_005fauth_005ffail_005fresponse"><code>MHD_queue_auth_fail_response</code></a></td><td
valign="top"><a href="#microhttpd_002ddauth">9. Utilizing Digest
Authentication</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fqueue_005fauth_005ffail_005fresponse"><code>MHD_queue_auth_fail_response</code></a></td><td
valign="top"><a href="#microhttpd_002ddauth-digest">9.2 Using Digest
Authentication</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#index-MHD_005fqueue_005fbasic_005fauth_005ffail_005fresponse"><code>MHD_queue_basic_auth_fail_response</code></a></td><td
valign="top"><a href="#microhttpd_002ddauth-basic">9.1 Using Basic
Authentication</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fqueue_005fresponse"><code>MHD_queue_response</code></a></td><td
valign="top"><a href="#microhttpd_002dresponse-enqueue">8.1 Enqueuing a
response</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005frun"><code>MHD_run</code></a></td><td valign="top"><a
href="#microhttpd_002dinit">5. Starting and stopping the server</a></td></tr>
<tr><td></td><td valign="top"><a
href="#index-MHD_005fset_005fconnection_005fvalue"><code>MHD_set_connection_value</code></a></td><td
valign="top"><a href="#microhttpd_002drequests">7. Handling
requests</a></td></tr>
@@ -3979,6 +4220,7 @@
<ul class="toc">
<li><a name="toc-Including-the-microhttpd_002eh-header"
href="#Including-the-microhttpd_002eh-header">1.1 Including the microhttpd.h
header</a></li>
<li><a name="toc-SIGPIPE" href="#SIGPIPE">1.2 SIGPIPE</a></li>
+ <li><a name="toc-MHD_005fLONG_005fLONG" href="#MHD_005fLONG_005fLONG">1.3
MHD_LONG_LONG</a></li>
</ul></li>
<li><a name="toc-Constants" href="#microhttpd_002dconst">2.
Constants</a></li>
<li><a name="toc-Structures-type-definition"
href="#microhttpd_002dstruct">3. Structures type definition</a></li>
@@ -3989,11 +4231,15 @@
<li><a name="toc-Building-answers-to-responses"
href="#microhttpd_002dresponses">8. Building answers to responses</a>
<ul class="toc">
<li><a name="toc-Enqueuing-a-response"
href="#microhttpd_002dresponse-enqueue">8.1 Enqueuing a response</a></li>
- <li><a name="toc-Creating-response-objects"
href="#microhttpd_002dresponse-create">8.2 Creating response objects</a></li>
+ <li><a name="toc-Creating-a-response-object"
href="#microhttpd_002dresponse-create">8.2 Creating a response object</a></li>
<li><a name="toc-Adding-headers-to-a-response"
href="#microhttpd_002dresponse-headers">8.3 Adding headers to a
response</a></li>
<li><a name="toc-Inspecting-a-response-object"
href="#microhttpd_002dresponse-inspect">8.4 Inspecting a response
object</a></li>
</ul></li>
- <li><a name="toc-Utilizing-Digest-Authentication"
href="#microhttpd_002ddauth">9. Utilizing Digest Authentication</a></li>
+ <li><a name="toc-Utilizing-Authentication" href="#microhttpd_002ddauth">9.
Utilizing Authentication</a>
+ <ul class="toc">
+ <li><a name="toc-Using-Basic-Authentication"
href="#microhttpd_002ddauth-basic">9.1 Using Basic Authentication</a></li>
+ <li><a name="toc-Using-Digest-Authentication"
href="#microhttpd_002ddauth-digest">9.2 Using Digest Authentication</a></li>
+ </ul></li>
<li><a name="toc-Adding-a-POST-processor" href="#microhttpd_002dpost">10.
Adding a <code>POST</code> processor</a>
<ul class="toc">
<li><a name="toc-Programming-interface-for-the-POST-processor"
href="#microhttpd_002dpost-api">10.1 Programming interface for the
<code>POST</code> processor</a></li>
@@ -4033,7 +4279,7 @@
<li><a name="stoc-Implementing-external-select"
href="#microhttpd_002dinspect">6. Implementing external
<code>select</code></a></li>
<li><a name="stoc-Handling-requests" href="#microhttpd_002drequests">7.
Handling requests</a></li>
<li><a name="stoc-Building-answers-to-responses"
href="#microhttpd_002dresponses">8. Building answers to responses</a></li>
-<li><a name="stoc-Utilizing-Digest-Authentication"
href="#microhttpd_002ddauth">9. Utilizing Digest Authentication</a></li>
+<li><a name="stoc-Utilizing-Authentication" href="#microhttpd_002ddauth">9.
Utilizing Authentication</a></li>
<li><a name="stoc-Adding-a-POST-processor" href="#microhttpd_002dpost">10.
Adding a <code>POST</code> processor</a></li>
<li><a name="stoc-Obtaining-status-information_002e"
href="#microhttpd_002dinfo">11. Obtaining status information.</a></li>
<li><a name="stoc-GNU_002dLGPL-1" href="#GNU_002dLGPL">GNU-LGPL</a></li>
@@ -4054,7 +4300,7 @@
</tr></table>
<h1>About This Document</h1>
<p>
- This document was generated by <em>Christian Grothoff</em> on <em>September
10, 2010</em> using <a href="http://www.nongnu.org/texi2html/";><em>texi2html
1.82</em></a>.
+ This document was generated by <em>Christian Grothoff</em> on <em>December
25, 2010</em> using <a href="http://www.nongnu.org/texi2html/";><em>texi2html
1.82</em></a>.
</p>
<p>
The buttons in the navigation panels have the following meaning:
@@ -4156,7 +4402,7 @@
<hr size="1">
<p>
<font size="-1">
- This document was generated by <em>Christian Grothoff</em> on <em>September
10, 2010</em> using <a href="http://www.nongnu.org/texi2html/";><em>texi2html
1.82</em></a>.
+ This document was generated by <em>Christian Grothoff</em> on <em>December
25, 2010</em> using <a href="http://www.nongnu.org/texi2html/";><em>texi2html
1.82</em></a>.
</font>
<br>
Modified: libmicrohttpd-docs/WWW/microhttpd.pdf
===================================================================
(Binary files differ)
Modified: libmicrohttpd-docs/WWW/tutorial.html
===================================================================
--- libmicrohttpd-docs/WWW/tutorial.html 2010-12-25 22:18:51 UTC (rev
14084)
+++ libmicrohttpd-docs/WWW/tutorial.html 2010-12-25 22:19:02 UTC (rev
14085)
@@ -1,7 +1,7 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html401/loose.dtd";>
<html>
-<!-- This tutorial documents GNU libmicrohttpd version 0.9.0, last
-updated 26 Jul 2010.
+<!-- This tutorial documents GNU libmicrohttpd version 0.9.4, last
+updated 26 Dec 2010.
Copyright (c) 2008 Sebastian Gerhardt.
@@ -14,7 +14,7 @@
Free Documentation License".
-->
-<!-- Created on September 10, 2010 by texi2html 1.82
+<!-- Created on December 25, 2010 by texi2html 1.82
texi2html was written by:
Lionel Cons <address@hidden> (original author)
Karl Berry <address@hidden>
@@ -123,7 +123,7 @@
encouraged to study the relevant <em>RFCs</em>, which document the HTTP
standard.
</p>
<p><em>GNU libmicrohttpd</em> is assumed to be already installed. This
tutorial
-is written for version 0.9.0. At the time being,
+is written for version 0.9.4. At the time being,
this tutorial has only been tested on <em>GNU/Linux</em> machines even though
efforts were made not to rely on anything that would prevent the samples from
being
built on similar systems.
@@ -189,7 +189,9 @@
#include <microhttpd.h>
#define PORT 8888
-</pre><p>the desired behaviour of our server when HTTP request arrive has to
be implemented. We already have
+
+</pre>
+<p>the desired behaviour of our server when HTTP request arrive has to be
implemented. We already have
agreed that it should not care about the particular details of the request,
such as who is requesting
what. The server will respond merely with the same small HTML page to every
request.
</p>
@@ -213,7 +215,9 @@
size_t *upload_data_size, void **con_cls)
{
const char *page = "<html><body>Hello,
browser!</body></html>";
-</pre><p>HTTP is a rather strict protocol and the client would certainly
consider it "inappropriate" if we
+
+</pre>
+<p>HTTP is a rather strict protocol and the client would certainly consider it
"inappropriate" if we
just sent the answer string "as is". Instead, it has to be wrapped
with additional information stored in so-called headers and footers. Most of
the work in this area is done by the library for us—we
just have to ask. Our reply string packed in the necessary layers will be
called a "response".
To obtain such a response we hand our data (the reply–string) and its
size over to the
@@ -226,7 +230,9 @@
response = MHD_create_response_from_data (strlen (page),
(void*) page, MHD_NO, MHD_NO);
-</pre><p>Now that the the response has been laced up, it is ready for delivery
and can be queued for sending.
+
+</pre>
+<p>Now that the the response has been laced up, it is ready for delivery and
can be queued for sending.
This is done by passing it to another <em>GNU libmicrohttpd</em> function. As
all our work was done in
the scope of one function, the recipient is without doubt the one associated
with the
local variable <code>connection</code> and consequently this variable is given
to the queue function.
@@ -241,7 +247,9 @@
return ret;
}
-</pre><p>With the primary task of our server implemented, we can start the
actual server daemon which will listen
+
+</pre>
+<p>With the primary task of our server implemented, we can start the actual
server daemon which will listen
on <code>PORT</code> for connections. This is done in the main function.
</p><pre class="verbatim">int main ()
{
@@ -250,7 +258,9 @@
daemon = MHD_start_daemon (MHD_USE_SELECT_INTERNALLY, PORT, NULL, NULL,
&answer_to_connection, NULL, MHD_OPTION_END);
if (NULL == daemon) return 1;
-</pre><p>The first parameter is one of three possible modes of operation. Here
we want the daemon to run in
+
+</pre>
+<p>The first parameter is one of three possible modes of operation. Here we
want the daemon to run in
a separate thread and to manage all incoming connections in the same thread.
This means that while
producing the response for one connection, the other connections will be put
on hold. In this
example, where the reply is already known and therefore the request is served
quickly, this poses no problem.
@@ -274,7 +284,8 @@
return 0;
}
-</pre><p>The first example is now complete.
+</pre>
+<p>The first example is now complete.
</p>
<p>Compile it with
</p><pre class="verbatim">cc hellobrowser.c -o hellobrowser
-I$PATH_TO_LIBMHD_INCLUDES
@@ -1514,6 +1525,7 @@
<p>The rather unexciting file loader can be found in the complete example
<code>tlsauthentication.c</code>.
</p>
+
<a name="Remarks-3"></a>
<h2 class="heading">Remarks</h2>
<ul>
@@ -1536,9 +1548,171 @@
The cryptographic facilities consume memory space and computing time. For this
reason, websites usually consists
both of uncritically <em>HTTP</em> parts and secured <em>HTTPS</em>.
-
</li></ul>
+
+<a name="Client-authentication"></a>
+<h2 class="heading">Client authentication</h2>
+
+<p>You can also use MHD to authenticate the client via SSL/TLS certificates
+(as an alternative to using the password-based Basic or Digest authentication).
+To do this, you will need to link your application against <em>gnutls</em>.
+For this, you first need to obtain the raw GnuTLS session handle from
+<em>MHD</em> using <code>MHD_get_connection_info</code>.
+</p>
+<pre class="verbatim">#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+
+gnutls_session_t tls_session;
+tls_session = MHD_get_connection_info (connection,
+ MHD_CONNECTION_INFO_GNUTLS_SESSION);
+</pre>
+<p>You can then extract the client certificate:
+</p>
+<pre class="verbatim">/**
+ * Get the client's certificate
+ *
+ * @param tls_session the TLS session
+ * @return NULL if no valid client certificate could be found, a pointer
+ * to the certificate if found
+ */
+static gnutls_x509_crt_t
+get_client_certificate (gnutls_session_t tls_session)
+{
+ unsigned int listsize;
+ const gnutls_datum_t * pcert;
+ gnutls_certificate_status_t client_cert_status;
+ gnutls_x509_crt_t client_cert;
+
+ if (tls_session == NULL)
+ return NULL;
+ if (gnutls_certificate_verify_peers2(tls_session,
+ &client_cert_status))
+ return NULL;
+ pcert = gnutls_certificate_get_peers(tls_session,
+ &listsize);
+ if ( (pcert == NULL) ||
+ (listsize == 0))
+ {
+ fprintf (stderr,
+ "Failed to retrieve client certificate chain\n");
+ return NULL;
+ }
+ if (gnutls_x509_crt_init(&client_cert))
+ {
+ fprintf (stderr,
+ "Failed to initialize client certificate\n");
+ return NULL;
+ }
+ /* Note that by passing values between 0 and listsize here, you
+ can get access to the CA's certs */
+ if (gnutls_x509_crt_import(client_cert,
+ &pcert[0],
+ GNUTLS_X509_FMT_DER))
+ {
+ fprintf (stderr,
+ "Failed to import client certificate\n");
+ gnutls_x509_crt_deinit(client_cert);
+ return NULL;
+ }
+ return client_cert;
+}
+</pre>
+<p>Using the client certificate, you can then get the client’s
distinguished name
+and alternative names:
+</p>
+<pre class="verbatim">/**
+ * Get the distinguished name from the client's certificate
+ *
+ * @param client_cert the client certificate
+ * @return NULL if no dn or certificate could be found, a pointer
+ * to the dn if found
+ */
+char *
+cert_auth_get_dn(gnutls_x509_crt_c client_cert)
+{
+ char* buf;
+ size_t lbuf;
+
+ lbuf = 0;
+ gnutls_x509_crt_get_dn(client_cert, NULL, &lbuf);
+ buf = malloc(lbuf);
+ if (buf == NULL)
+ {
+ fprintf (stderr,
+ "Failed to allocate memory for certificate dn\n");
+ return NULL;
+ }
+ gnutls_x509_crt_get_dn(client_cert, buf, &lbuf);
+ return buf;
+}
+
+
+/**
+ * Get the alternative name of specified type from the client's certificate
+ *
+ * @param client_cert the client certificate
+ * @param nametype The requested name type
+ * @param index The position of the alternative name if multiple names are
+ * matching the requested type, 0 for the first matching
name
+ * @return NULL if no matching alternative name could be found, a pointer
+ * to the alternative name if found
+ */
+char *
+MHD_cert_auth_get_alt_name(gnutls_x509_crt_t client_cert,
+ int nametype,
+ unsigned int index)
+{
+ char* buf;
+ size_t lbuf;
+ unsigned int seq;
+ unsigned int subseq;
+ unsigned int type;
+ int result;
+
+ subseq = 0;
+ for (seq=0;;seq++)
+ {
+ lbuf = 0;
+ result = gnutls_x509_crt_get_subject_alt_name2(client_cert, seq, NULL,
&lbuf,
+ &type, NULL);
+ if (result == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
+ return NULL;
+ if (nametype != (int) type)
+ continue;
+ if (subseq == index)
+ break;
+ subseq++;
+ }
+ buf = malloc(lbuf);
+ if (buf == NULL)
+ {
+ fprintf (stderr,
+ "Failed to allocate memory for certificate alt
name\n");
+ return NULL;
+ }
+ result = gnutls_x509_crt_get_subject_alt_name2(client_cert,
+ seq,
+ buf,
+ &lbuf,
+ NULL, NULL);
+ if (result != nametype)
+ {
+ fprintf (stderr,
+ "Unexpected return value from gnutls: %d\n",
+ result);
+ free (buf);
+ return NULL;
+ }
+ return buf;
+}
+</pre>
+<p>Finally, you should release the memory associated with the client
+certificate:
+</p>
+<pre class="verbatim">gnutls_x509_crt_deinit (client_cert);
+</pre>
+
<hr size="6">
<a name="Bibliography"></a>
<table cellpadding="1" cellspacing="1" border="0">
@@ -3356,7 +3530,7 @@
</tr></table>
<h1>About This Document</h1>
<p>
- This document was generated by <em>Christian Grothoff</em> on <em>September
10, 2010</em> using <a href="http://www.nongnu.org/texi2html/";><em>texi2html
1.82</em></a>.
+ This document was generated by <em>Christian Grothoff</em> on <em>December
25, 2010</em> using <a href="http://www.nongnu.org/texi2html/";><em>texi2html
1.82</em></a>.
</p>
<p>
The buttons in the navigation panels have the following meaning:
@@ -3458,7 +3632,7 @@
<hr size="1">
<p>
<font size="-1">
- This document was generated by <em>Christian Grothoff</em> on <em>September
10, 2010</em> using <a href="http://www.nongnu.org/texi2html/";><em>texi2html
1.82</em></a>.
+ This document was generated by <em>Christian Grothoff</em> on <em>December
25, 2010</em> using <a href="http://www.nongnu.org/texi2html/";><em>texi2html
1.82</em></a>.
</font>
<br>
Modified: libmicrohttpd-docs/WWW/tutorial.pdf
===================================================================
(Binary files differ)
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r14085 - libmicrohttpd-docs/WWW,
gnunet <=