| [Top] | [Contents] | [Index] | [ ? ] |
This tutorial documents GNU libmicrohttpd version 0.9.48, last updated 2 April 2016.
Copyright (c) 2008 Sebastian Gerhardt.
Copyright (c) 2010, 2011, 2012, 2013, 2016, 2021 Christian Grothoff.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This tutorial is for developers who want to learn how they can add HTTP serving capabilities to their applications with the GNU libmicrohttpd library, abbreviated MHD. The reader will learn how to implement basic HTTP functions from simple executable sample programs that implement various features.
The text is supposed to be a supplement to the API reference manual of GNU libmicrohttpd and for that reason does not explain many of the parameters. Therefore, the reader should always consult the manual to find the exact meaning of the functions used in the tutorial. Furthermore, the reader is encouraged to study the relevant RFCs, which document the HTTP standard.
GNU libmicrohttpd is assumed to be already installed. This tutorial is written for version 0.9.48. At the time being, this tutorial has only been tested on GNU/Linux machines even though efforts were made not to rely on anything that would prevent the samples from being built on similar systems.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This tutorial was originally written by Sebastian Gerhardt for MHD 0.4.0. It was slightly polished and updated to MHD 0.9.0 by Christian Grothoff.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The most basic task for a HTTP server is to deliver a static text message to any client connecting to it. Given that this is also easy to implement, it is an excellent problem to start with.
For now, the particular URI the client asks for shall have no effect on the message that will be returned. In addition, the server shall end the connection after the message has been sent so that the client will know there is nothing more to expect.
The C program hellobrowser.c, which is to be found in the examples section, does just that.
If you are very eager, you can compile and start it right away but it is advisable to type the
lines in by yourself as they will be discussed and explained in detail.
After the necessary includes and the definition of the port which our server should listen on
#include <sys/types.h> #include <sys/select.h> #include <sys/socket.h> #include <microhttpd.h> #define PORT 8888
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.
The function we are going to write now will be called by GNU libmicrohttpd every time an
appropriate request comes in. While the name of this callback function is arbitrary, its parameter
list has to follow a certain layout. So please, ignore the lot of parameters for now, they will be
explained at the point they are needed. We have to use only one of them,
struct MHD_Connection *connection, for the minimalistic functionality we want to achieve at the moment.
This parameter is set by the libmicrohttpd daemon and holds the necessary information to relate the call with a certain connection. Keep in mind that a server might have to satisfy hundreds of concurrent connections and we have to make sure that the correct data is sent to the destined client. Therefore, this variable is a means to refer to a particular connection if we ask the daemon to sent the reply.
Talking about the reply, it is defined as a string right after the function header
int answer_to_connection (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 **req_cls)
{
const char *page = "<html><body>Hello, browser!</body></html>";
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
MHD_create_response_from_buffer function. The last two parameters basically tell MHD
that we do not want it to dispose the message data for us when it has been sent and there also needs
no internal copy to be done because the constant string won’t change anyway.
struct MHD_Response *response;
int ret;
response = MHD_create_response_from_buffer (strlen (page),
(void*) page, MHD_RESPMEM_PERSISTENT);
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 GNU libmicrohttpd 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 connection and consequently this variable is given to the queue function.
Every HTTP response is accompanied by a status code, here "OK", so that the client knows
this response is the intended result of his request and not due to some error or malfunction.
Finally, the packet is destroyed and the return value from the queue returned, already being set at this point to either MHD_YES or MHD_NO in case of success or failure.
ret = MHD_queue_response (connection, MHD_HTTP_OK, response); MHD_destroy_response (response); return ret; }
With the primary task of our server implemented, we can start the actual server daemon which will listen
on PORT for connections. This is done in the main function.
int main ()
{
struct MHD_Daemon *daemon;
daemon = MHD_start_daemon (MHD_USE_INTERNAL_POLLING_THREAD, PORT, NULL, NULL,
&answer_to_connection, NULL, MHD_OPTION_END);
if (NULL == daemon) return 1;
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.
We will allow all clients to connect regardless of their name or location, therefore we do not check them on connection and set the third and fourth parameter to NULL.
Parameter five is the address of the function we want to be called whenever a new connection has been
established. Our answer_to_connection knows best what the client wants and needs no additional
information (which could be passed via the next parameter) so the next (sixth) parameter is NULL. Likewise,
we do not need to pass extra options to the daemon so we just write the MHD_OPTION_END as the last parameter.
As the server daemon runs in the background in its own thread, the execution flow in our main function will continue right after the call. Because of this, we must delay the execution flow in the main thread or else the program will terminate prematurely. We let it pause in a processing-time friendly manner by waiting for the enter key to be pressed. In the end, we stop the daemon so it can do its cleanup tasks.
getchar (); MHD_stop_daemon (daemon); return 0; }
The first example is now complete.
Compile it with
cc hellobrowser.c -o hellobrowser -I$PATH_TO_LIBMHD_INCLUDES -L$PATH_TO_LIBMHD_LIBS -lmicrohttpd
with the two paths set accordingly and run it.
Now open your favorite Internet browser and go to the address http://localhost:8888/, provided that 8888
is the port you chose. If everything works as expected, the browser will present the message of the
static HTML page it got from our minimal server.
To keep this first example as small as possible, some drastic shortcuts were taken and are to be discussed now.
Firstly, there is no distinction made between the kinds of requests a client could send. We implied
that the client sends a GET request, that means, that he actually asked for some data. Even when
it is not intended to accept POST requests, a good server should at least recognize that this
request does not constitute a legal request and answer with an error code. This can be easily
implemented by checking if the parameter method equals the string "GET" and returning a
MHD_NO if not so.
Secondly, the above practice of queuing a response upon the first call of the callback function
brings with it some limitations. This is because the content of the message body will not be
received if a response is queued in the first iteration. Furthermore, the connection will be closed
right after the response has been transferred then. This is typically not what you want as it
disables HTTP pipelining. The correct approach is to simply not queue a message on the first
callback unless there is an error. The void** argument to the callback provides a location
for storing information about the history of the connection; for the first call, the pointer
will point to NULL. A simplistic way to differentiate the first call from others is to check
if the pointer is NULL and set it to a non-NULL value during the first call.
Both of these issues you will find addressed in the official minimal_example.c residing in
the src/examples directory of the MHD package. The source code of this
program should look very familiar to you by now and easy to understand.
For our example, we create the response from a static (persistent) buffer in memory and thus pass MHD_RESPMEM_PERSISTENT to the response construction
function. In the usual case, responses are not transmitted immediately
after being queued. For example, there might be other data on the system that needs to be sent with
a higher priority. Nevertheless, the queue function will return successfully—raising the problem
that the data we have pointed to may be invalid by the time it is about being sent. This is not an
issue here because we can expect the page string, which is a constant string literal
here, to be static. That means it will be present and unchanged for as long as the program runs.
For dynamic data, one could choose to either have MHD free the memory page points
to itself when it is not longer needed (by passing MHD_RESPMEM_MUST_FREE) or, alternatively, have the library to make and manage
its own copy of it (by passing MHD_RESPMEM_MUST_COPY). Naturally, this last option is the most expensive.
telnet or netcat to connect to it. Try to form a
valid HTTP 1.1 request yourself like
GET /dontcare HTTP/1.1 Host: itsme <enter>
and see what the server returns to you.
MHD_USE_PEDANTIC_CHECKS to the start function of the daemon in main.
Mind the special format of the parameter list here which is described in the manual. How indulgent
is the server now to your input?
argv[1] to
the MHD_start_daemon function as the sixth parameter. The address of this string will be
passed to the callback function via the cls variable. Decorate the text given at the command
line when the server is started with proper HTML tags and send it as the response instead of the
former static string.
answer_to_connection. Remember to free the memory of the string
every time after satisfying the request.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter will deal with the information which the client sends to the server at every request. We are going to examine the most useful fields of such an request and print them out in a readable manner. This could be useful for logging facilities.
The starting point is the hellobrowser program with the former response removed.
This time, we just want to collect information in the callback function, thus we will just return MHD_NO after we have probed the request. This way, the connection is closed without much ado by the server.
static int
answer_to_connection (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 **req_cls)
{
...
return MHD_NO;
}
The ellipsis marks the position where the following instructions shall be inserted.
We begin with the most obvious information available to the server, the request line. You should
already have noted that a request consists of a command (or "HTTP method") and a URI (e.g. a filename).
It also contains a string for the version of the protocol which can be found in version.
To call it a "new request" is justified because we return only MHD_NO, thus ensuring the
function will not be called again for this connection.
printf ("New %s request for %s using version %s\n", method, url, version);
The rest of the information is a bit more hidden. Nevertheless, there is lot of it sent from common Internet browsers. It is stored in "key-value" pairs and we want to list what we find in the header. As there is no mandatory set of keys a client has to send, each key-value pair is printed out one by one until there are no more left. We do this by writing a separate function which will be called for each pair just like the above function is called for each HTTP request. It can then print out the content of this pair.
int print_out_key (void *cls, enum MHD_ValueKind kind,
const char *key, const char *value)
{
printf ("%s: %s\n", key, value);
return MHD_YES;
}
To start the iteration process that calls our new function for every key, the line
MHD_get_connection_values (connection, MHD_HEADER_KIND, &print_out_key, NULL);
needs to be inserted in the connection callback function too. The second parameter tells the function
that we are only interested in keys from the general HTTP header of the request. Our iterating
function print_out_key does not rely on any additional information to fulfill its duties
so the last parameter can be NULL.
All in all, this constitutes the complete logging.c program for this chapter which can be
found in the examples section.
Connecting with any modern Internet browser should yield a handful of keys. You should try to interpret them with the aid of RFC 2616. Especially worth mentioning is the "Host" key which is often used to serve several different websites hosted under one single IP address but reachable by different domain names (this is called virtual hosting).
The introduced capabilities to itemize the content of a simple GET request—especially the URI—should already allow the server to satisfy clients’ requests for small specific resources (e.g. files) or even induce alteration of server state. However, the latter is not recommended as the GET method (including its header data) is by convention considered a "safe" operation, which should not change the server’s state in a significant way. By convention, GET operations can thus be performed by crawlers and other automatic software. Naturally actions like searching for a passed string are fine.
Of course, no transmission can occur while the return value is still set to MHD_NO in the
callback function.
url string and delivering responses accordingly, implement a small server for
"virtual" files. When asked for /index.htm{l}, let the response consist of a HTML page
containing a link to /another.html page which is also to be created "on the fly" in case of
being requested. If neither of these two pages are requested, MHD_HTTP_NOT_FOUND shall be
returned accompanied by an informative message.
static int on_client_connect (void *cls,
const struct sockaddr *addr,
socklen_t addrlen)
that prints out the IP address in an appropriate format. You might want to use the POSIX function
inet_ntoa but bear in mind that addr is actually just a structure containing other
substructures and is not the variable this function expects.
Make sure to return MHD_YES so that the library knows the client is allowed to connect
(and to then process the request). If one wanted to limit access basing on IP addresses, this would be the place
to do it. The address of your on_client_connect function must be passed as the third parameter to the
MHD_start_daemon call.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Now that we are able to inspect the incoming request in great detail, this chapter discusses the means to enrich the outgoing responses likewise.
As you have learned in the Hello, Browser chapter, some obligatory header fields are added and set automatically for simple responses by the library itself but if more advanced features are desired, additional fields have to be created. One of the possible fields is the content type field and an example will be developed around it. This will lead to an application capable of correctly serving different types of files.
When we responded with HTML page packed in the static string previously, the client had no choice but guessing about how to handle the response, because the server had not told him. What if we had sent a picture or a sound file? Would the message have been understood or merely been displayed as an endless stream of random characters in the browser? This is what the mime content types are for. The header of the response is extended by certain information about how the data is to be interpreted.
To introduce the concept, a picture of the format PNG will be sent to the client
and labeled accordingly with image/png.
Once again, we can base the new example on the hellobrowser program.
#define FILENAME "picture.png"
#define MIMETYPE "image/png"
static enum MHD_Result
answer_to_connection (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 **req_cls)
{
unsigned char *buffer = NULL;
struct MHD_Response *response;
We want the program to open the file for reading and determine its size:
int fd;
enum MHD_Result ret;
struct stat sbuf;
if (0 != strcmp (method, "GET"))
return MHD_NO;
if ( (-1 == (fd = open (FILENAME, O_RDONLY))) ||
(0 != fstat (fd, &sbuf)) )
{
/* error accessing file */
/* ... (see below) */
}
/* ... (see below) */
When dealing with files, there is a lot that could go wrong on the
server side and if so, the client should be informed with MHD_HTTP_INTERNAL_SERVER_ERROR.
/* error accessing file */
if (fd != -1) close (fd);
const char *errorstr =
"<html><body>An internal server error has occurred!\
</body></html>";
response =
MHD_create_response_from_buffer (strlen (errorstr),
(void *) errorstr,
MHD_RESPMEM_PERSISTENT);
if (response)
{
ret =
MHD_queue_response (connection, MHD_HTTP_INTERNAL_SERVER_ERROR,
response);
MHD_destroy_response (response);
return MHD_YES;
}
else
return MHD_NO;
if (!ret)
{
const char *errorstr = "<html><body>An internal server error has occurred!\
</body></html>";
if (buffer) free(buffer);
response = MHD_create_response_from_buffer (strlen(errorstr), (void*) errorstr,
MHD_RESPMEM_PERSISTENT);
if (response)
{
ret = MHD_queue_response (connection,
MHD_HTTP_INTERNAL_SERVER_ERROR,
response);
MHD_destroy_response (response);
return MHD_YES;
}
else return MHD_NO;
}
Note that we nevertheless have to create a response object even for sending a simple error code. Otherwise, the connection would just be closed without comment, leaving the client curious about what has happened.
But in the case of success a response will be constructed directly from the file descriptor:
/* error accessing file */
/* ... (see above) */
}
response =
MHD_create_response_from_fd_at_offset (sbuf.st_size, fd, 0);
MHD_add_response_header (response, "Content-Type", MIMETYPE);
ret = MHD_queue_response (connection, MHD_HTTP_OK, response);
MHD_destroy_response (response);
Note that the response object will take care of closing the file descriptor for us.
Up to this point, there was little new. The actual novelty is that we enhance the header with the meta data about the content. Aware of the field’s name we want to add, it is as easy as that:
MHD_add_response_header(response, "Content-Type", MIMETYPE);
We do not have to append a colon expected by the protocol behind the first field—GNU libhttpdmicro will take care of this.
The function finishes with the well-known lines
ret = MHD_queue_response (connection, MHD_HTTP_OK, response); MHD_destroy_response (response); return ret; }
The complete program responseheaders.c is in the examples section as usual.
Find a PNG file you like and save it to the directory the example is run from under the name
picture.png. You should find the image displayed on your browser if everything worked well.
The include file of the MHD library comes with the header types mentioned in RFC 2616
already defined as macros. Thus, we could have written MHD_HTTP_HEADER_CONTENT_TYPE instead
of "Content-Type" as well. However, one is not limited to these standard headers and could
add custom response headers without violating the protocol. Whether, and how, the client would react
to these custom header is up to the receiver. Likewise, the client is allowed to send custom request
headers to the server as well, opening up yet more possibilities how client and server could
communicate with each other.
The method of creating the response from a file on disk only works for static content. Serving dynamically created responses will be a topic of a future chapter.
sleep function for 30 seconds
if the file /big.png is requested (but deliver the same as above). A request for
/picture.png should provide just the same but without any artificial delays.
Now start two instances of your browser (or even use two machines) and see how the second client is put on hold while the first waits for his request on the slow file to be fulfilled.
Finally, change the sourcecode to use MHD_USE_THREAD_PER_CONNECTION when the daemon is
started and try again.
t and implement a response simulating a countdown that reaches 0 at
t+60. Returning a message saying on which point the countdown is, the response should
ultimately be to reply "Done" if the program has been running long enough,
An unofficial, but widely understood, response header line is Refresh: DELAY; url=URL with
the uppercase words substituted to tell the client it should request the given resource after
the given delay again. Improve your program in that the browser (any modern browser should work)
automatically reconnects and asks for the status again every 5 seconds or so. The URL would have
to be composed so that it begins with "http://", followed by the URI the server is reachable
from the client’s point of view.
Maybe you want also to visualize the countdown as a status bar by creating a
<table> consisting of one row and n columns whose fields contain small images of either
a red or a green light.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
With the small exception of IP address based access control, requests from all connecting clients where served equally until now. This chapter discusses a first method of client’s authentication and its limits.
A very simple approach feasible with the means already discussed would be to expect the password in the URI string before granting access to the secured areas. The password could be separated from the actual resource identifier by a certain character, thus the request line might look like
GET /picture.png?mypassword
In the rare situation where the client is customized enough and the connection occurs through secured lines (e.g., a embedded device directly attached to another via wire) and where the ability to embed a password in the URI or to pass on a URI with a password are desired, this can be a reasonable choice.
But when it is assumed that the user connecting does so with an ordinary Internet browser, this implementation brings some problems about. For example, the URI including the password stays in the address field or at least in the history of the browser for anybody near enough to see. It will also be inconvenient to add the password manually to any new URI when the browser does not know how to compose this automatically.
At least the convenience issue can be addressed by employing the simplest built-in password facilities of HTTP compliant browsers, hence we want to start there. It will, however, turn out to have still severe weaknesses in terms of security which need consideration.
Before we will start implementing Basic Authentication as described in RFC 2617, we will also abandon the simplistic and generally problematic practice of responding every request the first time our callback is called for a given connection. Queuing a response upon the first request is akin to generating an error response (even if it is a "200 OK" reply!). The reason is that MHD usually calls the callback in three phases:
MHD_queue_response.
If there is no upload data, this phase is skipped.
But how can we tell whether the callback has been called before for the
particular request? Initially, the pointer this parameter references is
set by MHD in the callback. But it will also be "remembered" on the
next call (for the same request). Thus, we can use the req_cls
location to keep track of the request state. For now, we will simply
generate no response until the parameter is non-null—implying the callback
was called before at least once. We do not need to share information between
different calls of the callback, so we can set the parameter to any address
that is assured to be not null. The pointer to the connection structure
will be pointing to a legal address, so we take this.
The first time answer_to_connection is called, we will not even look at the headers.
static int
answer_to_connection (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 **req_cls)
{
if (0 != strcmp(method, "GET")) return MHD_NO;
if (NULL == *req_cls) {*req_cls = connection; return MHD_YES;}
...
/* else respond accordingly */
...
}
Note how we lop off the connection on the first condition (no "GET" request),
but return asking for more on the other one with MHD_YES. With this
minor change, we can proceed to implement the actual authentication process.
Let us assume we had only files not intended to be handed out without the
correct username/password, so every "GET" request will be challenged.
RFC 7617 describes how the server shall ask for authentication by
adding a WWW-Authenticate response header with the name of the
realm protected. MHD can generate and queue such a failure response
for you using the MHD_queue_basic_auth_fail_response API. The only
thing you need to do is construct a response with the error page to be shown
to the user if he aborts basic authentication. But first, you should check if
the proper credentials were already supplied using the
MHD_basic_auth_get_username_password call.
Your code would then look like this:
static enum MHD_Result
answer_to_connection (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 **req_cls)
{
struct MHD_BasicAuthInfo *auth_info;
enum MHD_Result ret;
struct MHD_Response *response;
if (0 != strcmp (method, "GET"))
return MHD_NO;
if (NULL == *req_cls)
{
*req_cls = connection;
return MHD_YES;
}
auth_info = MHD_basic_auth_get_username_password3 (connection);
if (NULL == auth_info)
{
static const char *page =
"<html><body>Authorization required</body></html>";
response = MHD_create_response_from_buffer_static (strlen (page), page);
ret = MHD_queue_basic_auth_fail_response3 (connection,
"admins",
MHD_YES,
response);
}
else if ((strlen ("root") != auth_info->username_len) ||
(0 != memcmp (auth_info->username, "root",
auth_info->username_len)) ||
/* The next check against NULL is optional,
* if 'password' is NULL then 'password_len' is always zero. */
(NULL == auth_info->password) ||
(strlen ("pa$$w0rd") != auth_info->password_len) ||
(0 != memcmp (auth_info->password, "pa$$w0rd",
auth_info->password_len)))
{
static const char *page =
"<html><body>Wrong username or password</body></html>";
response = MHD_create_response_from_buffer_static (strlen (page), page);
ret = MHD_queue_basic_auth_fail_response3 (connection,
"admins",
MHD_YES,
response);
}
else
{
static const char *page = "<html><body>A secret.</body></html>";
response = MHD_create_response_from_buffer_static (strlen (page), page);
ret = MHD_queue_response (connection, MHD_HTTP_OK, response);
}
if (NULL != auth_info)
MHD_free (auth_info);
MHD_destroy_response (response);
return ret;
}
See the examples directory for the complete example file.
For a proper server, the conditional statements leading to a return of MHD_NO should yield a
response with a more precise status code instead of silently closing the connection. For example,
failures of memory allocation are best reported as internal server error and unexpected
authentication methods as 400 bad request.
AcceptPolicyCallback function denies connection (temporally).
netcat connect and log the response of a "GET" request as you
did in the exercise of the first example, this time to a file. Now stop the server and let netcat
listen on the same port the server used to listen on and have it fake being the proper server by giving
the file’s content as the response (e.g. cat log | nc -l -p 8888). Pretending to think your were
connecting to the actual server, browse to the eavesdropper and give the correct credentials.
Copy and paste the encoded string you see in netcat’s output to some of the Base64 decode tools available online
and see how both the user’s name and password could be completely restored.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The previous chapters already have demonstrated a variety of possibilities to send information to the HTTP server, but it is not recommended that the GET method is used to alter the way the server operates. To induce changes on the server, the POST method is preferred over and is much more powerful than GET and will be introduced in this chapter.
We are going to write an application that asks for the visitor’s name and, after the user has posted it, composes an individual response text. Even though it was not mandatory to use the POST method here, as there is no permanent change caused by the POST, it is an illustrative example on how to share data between different functions for the same connection. Furthermore, the reader should be able to extend it easily.
When the first GET request arrives, the server shall respond with a HTML page containing an edit field for the name.
const char* askpage = "<html><body>\
What's your name, Sir?<br>\
<form action=\"/namepost\" method=\"post\">\
<input name=\"name\" type=\"text\"\
<input type=\"submit\" value=\" Send \"></form>\
</body></html>";
The action entry is the URI to be called by the browser when posting, and the
name will be used later to be sure it is the editbox’s content that has been posted.
We also prepare the answer page, where the name is to be filled in later, and an error page as the response for anything but proper GET and POST requests:
const char* greatingpage="<html><body><h1>Welcome, %s!</center></h1></body></html>"; const char* errorpage="<html><body>This doesn't seem to be right.</body></html>";
Whenever we need to send a page, we use an extra function
int send_page(struct MHD_Connection *connection, const char* page)
for this, which does not contain anything new and whose implementation is therefore
not discussed further in the tutorial.
Posted data can be of arbitrary and considerable size; for example, if a user uploads a big image to the server. Similar to the case of the header fields, there may also be different streams of posted data, such as one containing the text of an editbox and another the state of a button. Likewise, we will have to register an iterator function that is going to be called maybe several times not only if there are different POSTs but also if one POST has only been received partly yet and needs processing before another chunk can be received.
Such an iterator function is called by a postprocessor, which must be created upon arriving
of the post request. We want the iterator function to read the first post data which is tagged
name and to create an individual greeting string based on the template and the name.
But in order to pass this string to other functions and still be able to differentiate different
connections, we must first define a structure to share the information, holding the most import entries.
struct connection_info_struct
{
int connectiontype;
char *answerstring;
struct MHD_PostProcessor *postprocessor;
};
With these information available to the iterator function, it is able to fulfill its task.
Once it has composed the greeting string, it returns MHD_NO to inform the post processor
that it does not need to be called again. Note that this function does not handle processing
of data for the same key. If we were to expect that the name will be posted in several
chunks, we had to expand the namestring dynamically as additional parts of it with the same key
came in. But in this example, the name is assumed to fit entirely inside one single packet.
static enum MHD_Result
iterate_post (void *coninfo_cls, enum MHD_ValueKind kind, const char *key,
const char *filename, const char *content_type,
const char *transfer_encoding, const char *data,
uint64_t off, size_t size)
{
struct connection_info_struct *con_info = coninfo_cls;
if (0 == strcmp (key, "name"))
{
if ((size > 0) && (size <= MAXNAMESIZE))
{
char *answerstring;
answerstring = malloc (MAXANSWERSIZE);
if (!answerstring) return MHD_NO;
snprintf (answerstring, MAXANSWERSIZE, greatingpage, data);
con_info->answerstring = answerstring;
}
else con_info->answerstring = NULL;
return MHD_NO;
}
return MHD_YES;
}
Once a connection has been established, it can be terminated for many reasons. As these reasons include unexpected events, we have to register another function that cleans up any resources that might have been allocated for that connection by us, namely the post processor and the greetings string. This cleanup function must take into account that it will also be called for finished requests other than POST requests.
void
request_completed (void *cls, struct MHD_Connection *connection,
void **req_cls,
enum MHD_RequestTerminationCode toe)
{
struct connection_info_struct *con_info = *req_cls;
if (NULL == con_info)
return;
if (con_info->connectiontype == POST)
{
MHD_destroy_post_processor (con_info->postprocessor);
if (con_info->answerstring) free (con_info->answerstring);
}
free (con_info);
*req_cls = NULL;
}
GNU libmicrohttpd is informed that it shall call the above function when the daemon is started in the main function.
...
daemon = MHD_start_daemon (MHD_USE_INTERNAL_POLLING_THREAD, PORT, NULL, NULL,
&answer_to_connection, NULL,
MHD_OPTION_NOTIFY_COMPLETED, &request_completed, NULL,
MHD_OPTION_END);
...
With all other functions prepared, we can now discuss the actual request handling.
On the first iteration for a new request, we start by allocating a new instance of a
struct connection_info_struct structure, which will store all necessary information for later
iterations and other functions.
static enum MHD_Result
answer_to_connection (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 **req_cls)
{
if(NULL == *req_cls)
{
struct connection_info_struct *con_info;
con_info = malloc (sizeof (struct connection_info_struct));
if (NULL == con_info) return MHD_NO;
con_info->answerstring = NULL;
If the new request is a POST, the postprocessor must be created now. In addition, the type of the request is stored for convenience.
if (0 == strcmp (method, "POST"))
{
con_info->postprocessor
= MHD_create_post_processor (connection, POSTBUFFERSIZE,
iterate_post, (void*) con_info);
if (NULL == con_info->postprocessor)
{
free (con_info);
return MHD_NO;
}
con_info->connectiontype = POST;
}
else con_info->connectiontype = GET;
The address of our structure will both serve as the indicator for successive iterations and to remember the particular details about the connection.
*req_cls = (void*) con_info;
return MHD_YES;
}
The rest of the function will not be executed on the first iteration. A GET request is easily satisfied by sending the question form.
if (0 == strcmp (method, "GET"))
{
return send_page (connection, askpage);
}
In case of POST, we invoke the post processor for as long as data keeps incoming, setting
*upload_data_size to zero in order to indicate that we have processed—or at least have
considered—all of it.
if (0 == strcmp (method, "POST"))
{
struct connection_info_struct *con_info = *req_cls;
if (*upload_data_size != 0)
{
MHD_post_process (con_info->postprocessor, upload_data,
*upload_data_size);
*upload_data_size = 0;
return MHD_YES;
}
else if (NULL != con_info->answerstring)
return send_page (connection, con_info->answerstring);
}
Finally, if they are neither GET nor POST requests, the error page is returned.
return send_page(connection, errorpage); }
These were the important parts of the program simplepost.c.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The previous chapter introduced a way to upload data to the server, but the developed example program has some shortcomings, such as not being able to handle larger chunks of data. In this chapter, we are going to discuss a more advanced server program that allows clients to upload a file in order to have it stored on the server’s filesystem. The server shall also watch and limit the number of clients concurrently uploading, responding with a proper busy message if necessary.
We choose to operate the server with the SELECT_INTERNALLY method. This makes it easier to
synchronize the global states at the cost of possible delays for other connections if the processing
of a request is too slow. One of these variables that needs to be shared for all connections is the
total number of clients that are uploading.
#define MAXCLIENTS 2 static unsigned int nr_of_uploading_clients = 0;
If there are too many clients uploading, we want the server to respond to all requests with a busy message.
const char* busypage = "<html><body>This server is busy, please try again later.</body></html>";
Otherwise, the server will send a form that informs the user of the current number of uploading clients, and ask her to pick a file on her local filesystem which is to be uploaded.
const char* askpage = "<html><body>\n\
Upload a file, please!<br>\n\
There are %u clients uploading at the moment.<br>\n\
<form action=\"/filepost\" method=\"post\" \
enctype=\"multipart/form-data\">\n\
<input name=\"file\" type=\"file\">\n\
<input type=\"submit\" value=\" Send \"></form>\n\
</body></html>";
If the upload has succeeded, the server will respond with a message saying so.
const char* completepage = "<html><body>The upload has been completed.</body></html>";
We want the server to report internal errors, such as memory shortage or file access problems, adequately.
const char* servererrorpage = "<html><body>An internal server error has occurred.</body></html>"; const char* fileexistspage = "<html><body>This file already exists.</body></html>";
It would be tolerable to send all these responses undifferentiated with a 200 HTTP_OK
status code but in order to improve the HTTP conformance of our server a bit, we extend the
send_page function so that it accepts individual status codes.
static enum MHD_Result
send_page (struct MHD_Connection *connection,
const char* page, int status_code)
{
enum MHD_Result ret;
struct MHD_Response *response;
response = MHD_create_response_from_buffer (strlen (page), (void*) page,
MHD_RESPMEM_MUST_COPY);
if (!response) return MHD_NO;
ret = MHD_queue_response (connection, status_code, response);
MHD_destroy_response (response);
return ret;
}
Note how we ask MHD to make its own copy of the message data. The reason behind this will become clear later.
The decision whether the server is busy or not is made right at the beginning of the connection. To
do that at this stage is especially important for POST requests because if no response is
queued at this point, and MHD_YES returned, MHD will not sent any queued messages until
a postprocessor has been created and the post iterator is called at least once.
static enum MHD_Result
answer_to_connection (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 **req_cls)
{
if (NULL == *req_cls)
{
struct connection_info_struct *con_info;
if (nr_of_uploading_clients >= MAXCLIENTS)
return send_page(connection, busypage, MHD_HTTP_SERVICE_UNAVAILABLE);
If the server is not busy, the connection_info structure is initialized as usual, with
the addition of a filepointer for each connection.
con_info = malloc (sizeof (struct connection_info_struct));
if (NULL == con_info) return MHD_NO;
con_info->fp = 0;
if (0 == strcmp (method, "POST"))
{
...
}
else con_info->connectiontype = GET;
*req_cls = (void*) con_info;
return MHD_YES;
}
For POST requests, the postprocessor is created and we register a new uploading client. From
this point on, there are many possible places for errors to occur that make it necessary to interrupt
the uploading process. We need a means of having the proper response message ready at all times.
Therefore, the connection_info structure is extended to hold the most current response
message so that whenever a response is sent, the client will get the most informative message. Here,
the structure is initialized to "no error".
if (0 == strcmp (method, "POST"))
{
con_info->postprocessor
= MHD_create_post_processor (connection, POSTBUFFERSIZE,
iterate_post, (void*) con_info);
if (NULL == con_info->postprocessor)
{
free (con_info);
return MHD_NO;
}
nr_of_uploading_clients++;
con_info->connectiontype = POST;
con_info->answercode = MHD_HTTP_OK;
con_info->answerstring = completepage;
}
else con_info->connectiontype = GET;
If the connection handler is called for the second time, GET requests will be answered with the form. We can keep the buffer under function scope, because we asked MHD to make its own copy of it for as long as it is needed.
if (0 == strcmp (method, "GET"))
{
char buffer[1024];
sprintf (buffer, askpage, nr_of_uploading_clients);
return send_page (connection, buffer, MHD_HTTP_OK);
}
The rest of the answer_to_connection function is very similar to the simplepost.c
example, except the more flexible content of the responses. The POST data is processed until
there is none left and the execution falls through to return an error page if the connection
constituted no expected request method.
if (0 == strcmp (method, "POST"))
{
struct connection_info_struct *con_info = *req_cls;
if (0 != *upload_data_size)
{
MHD_post_process (con_info->postprocessor,
upload_data, *upload_data_size);
*upload_data_size = 0;
return MHD_YES;
}
else
return send_page (connection, con_info->answerstring,
con_info->answercode);
}
return send_page(connection, errorpage, MHD_HTTP_BAD_REQUEST);
}
Unlike the simplepost.c example, here it is to be expected that post iterator will be called
several times now. This means that for any given connection (there might be several concurrent of them)
the posted data has to be written to the correct file. That is why we store a file handle in every
connection_info, so that the it is preserved between successive iterations.
static enum MHD_Result
iterate_post (void *coninfo_cls, enum MHD_ValueKind kind,
const char *key,
const char *filename, const char *content_type,
const char *transfer_encoding, const char *data,
uint64_t off, size_t size)
{
struct connection_info_struct *con_info = coninfo_cls;
Because the following actions depend heavily on correct file processing, which might be error prone, we default to reporting internal errors in case anything will go wrong.
con_info->answerstring = servererrorpage; con_info->answercode = MHD_HTTP_INTERNAL_SERVER_ERROR;
In the "askpage" form, we told the client to label its post data with the "file" key. Anything else would be an error.
if (0 != strcmp (key, "file")) return MHD_NO;
If the iterator is called for the first time, no file will have been opened yet. The filename
string contains the name of the file (without any paths) the user selected on his system. We want to
take this as the name the file will be stored on the server and make sure no file of that name exists
(or is being uploaded) before we create one (note that the code below technically contains a
race between the two "fopen" calls, but we will overlook this for portability sake).
if (!con_info->fp)
{
if (NULL != (fp = fopen (filename, "rb")) )
{
fclose (fp);
con_info->answerstring = fileexistspage;
con_info->answercode = MHD_HTTP_FORBIDDEN;
return MHD_NO;
}
con_info->fp = fopen (filename, "ab");
if (!con_info->fp) return MHD_NO;
}
Occasionally, the iterator function will be called even when there are 0 new bytes to process. The server only needs to write data to the file if there is some.
if (size > 0)
{
if (!fwrite (data, size, sizeof(char), con_info->fp))
return MHD_NO;
}
If this point has been reached, everything worked well for this iteration and the response can be set to success again. If the upload has finished, this iterator function will not be called again.
con_info->answerstring = completepage; con_info->answercode = MHD_HTTP_OK; return MHD_YES; }
The new client was registered when the postprocessor was created. Likewise, we unregister the client on destroying the postprocessor when the request is completed.
void
request_completed (void *cls, struct MHD_Connection *connection,
void **req_cls,
enum MHD_RequestTerminationCode toe)
{
struct connection_info_struct *con_info = *req_cls;
if (NULL == con_info) return;
if (con_info->connectiontype == POST)
{
if (NULL != con_info->postprocessor)
{
MHD_destroy_post_processor (con_info->postprocessor);
nr_of_uploading_clients--;
}
if (con_info->fp) fclose (con_info->fp);
}
free (con_info);
*req_cls = NULL;
}
This is essentially the whole example largepost.c.
Now that the clients are able to create files on the server, security aspects are becoming even more important than before. Aside from proper client authentication, the server should always make sure explicitly that no files will be created outside of a dedicated upload directory. In particular, filenames must be checked to not contain strings like "../".
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter discusses how one should manage sessions, that is, share state between multiple HTTP requests from the same user. We use a simple example where the user submits multiple forms and the server is supposed to accumulate state from all of these forms. Naturally, as this is a network protocol, our session mechanism must support having many users with many concurrent sessions at the same time.
In order to track users, we use a simple session cookie. A session cookie expires when the user closes the browser. Changing from session cookies to persistent cookies only requires adding an expiration time to the cookie. The server creates a fresh session cookie whenever a request without a cookie is received, or if the supplied session cookie is not known to the server.
Since MHD parses the HTTP cookie header for us, looking up an existing cookie is straightforward:
const char *value;
value = MHD_lookup_connection_value (connection,
MHD_COOKIE_KIND,
"KEY");
Here, "KEY" is the name we chose for our session cookie.
MHD requires the user to provide the full cookie format string in order to set cookies. In order to generate a unique cookie, our example creates a random 64-character text string to be used as the value of the cookie:
char value[128];
char raw_value[65];
for (unsigned int i=0;i<sizeof (raw_value);i++)
raw_value = 'A' + (rand () % 26); /* bad PRNG! */
raw_value[64] = '\0';
snprintf (value, sizeof (value),
"%s=%s",
"KEY",
raw_value);
Given this cookie value, we can then set the cookie header in our HTTP response as follows:
assert (MHD_YES ==
MHD_set_connection_value (connection,
MHD_HEADER_KIND,
MHD_HTTP_HEADER_SET_COOKIE,
value));
It is of course possible that clients stop their interaction with the server at any time. In order to avoid using too much storage, the server must thus discard inactive sessions at some point. Our example implements this by discarding inactive sessions after a certain amount of time. Alternatively, the implementation may limit the total number of active sessions. Which bounds are used for idle sessions or the total number of sessions obviously depends largely on the type of the application and available server resources.
A sample application implementing a website with multiple
forms (which are dynamically created using values from previous
POST requests from the same session) is available
as the example sessions.c.
Note that the example uses a simple, $O(n)$ linked list traversal to look up sessions and to expire old sessions. Using a hash table and a heap would be more appropriate if a large number of concurrent sessions is expected.
Naturally, it is quite conceivable to store session data in a database instead of in memory. Still, having mechanisms to expire data associated with long-time idle sessions (where the business process has still not finished) is likely a good idea.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
We left the basic authentication chapter with the unsatisfactory conclusion that any traffic, including the credentials, could be intercepted by anyone between the browser client and the server. Protecting the data while it is sent over unsecured lines will be the goal of this chapter.
Since version 0.4, the MHD library includes support for encrypting the traffic by employing SSL/TSL. If GNU libmicrohttpd has been configured to support these, encryption and decryption can be applied transparently on the data being sent, with only minimal changes to the actual source code of the example.
First, a private key for the server will be generated. With this key, the server will later be able to authenticate itself to the client—preventing anyone else from stealing the password by faking its identity. The OpenSSL suite, which is available on many operating systems, can generate such a key. For the scope of this tutorial, we will be content with a 1024 bit key:
> openssl genrsa -out server.key 1024
In addition to the key, a certificate describing the server in human readable tokens is also needed. This certificate will be attested with our aforementioned key. In this way, we obtain a self-signed certificate, valid for one year.
> openssl req -days 365 -out server.pem -new -x509 -key server.key
To avoid unnecessary error messages in the browser, the certificate needs to have a name that matches the URI, for example, "localhost" or the domain. If you plan to have a publicly reachable server, you will need to ask a trusted third party, called Certificate Authority, or CA, to attest the certificate for you. This way, any visitor can make sure the server’s identity is real.
Whether the server’s certificate is signed by us or a third party, once it has been accepted by the client, both sides will be communicating over encrypted channels. From this point on, it is the client’s turn to authenticate itself. But this has already been implemented in the basic authentication scheme.
We merely have to extend the server program so that it loads the two files into memory,
int
main ()
{
struct MHD_Daemon *daemon;
char *key_pem;
char *cert_pem;
key_pem = load_file (SERVERKEYFILE);
cert_pem = load_file (SERVERCERTFILE);
if ((key_pem == NULL) || (cert_pem == NULL))
{
printf ("The key/certificate files could not be read.\n");
return 1;
}
and then we point the MHD daemon to it upon initialization.
daemon = MHD_start_daemon (MHD_USE_INTERNAL_POLLING_THREAD | MHD_USE_SSL,
PORT, NULL, NULL,
&answer_to_connection, NULL,
MHD_OPTION_HTTPS_MEM_KEY, key_pem,
MHD_OPTION_HTTPS_MEM_CERT, cert_pem,
MHD_OPTION_END);
if (NULL == daemon)
{
printf ("%s\n", cert_pem);
free (key_pem);
free (cert_pem);
return 1;
}
The rest consists of little new besides some additional memory cleanups.
getchar (); MHD_stop_daemon (daemon); free (key_pem); free (cert_pem); return 0; }
The rather unexciting file loader can be found in the complete example tlsauthentication.c.
https://localhost:8888 explicitly when you test the example, or the browser will not know how to
handle the answer properly.
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 gnutls. Next, when you start the MHD daemon, you must specify the root CA that you’re willing to trust:
daemon = MHD_start_daemon (MHD_USE_INTERNAL_POLLING_THREAD | MHD_USE_SSL,
PORT, NULL, NULL,
&answer_to_connection, NULL,
MHD_OPTION_HTTPS_MEM_KEY, key_pem,
MHD_OPTION_HTTPS_MEM_CERT, cert_pem,
MHD_OPTION_HTTPS_MEM_TRUST, root_ca_pem,
MHD_OPTION_END);
With this, you can then obtain client certificates for each session.
In order to obtain the identity of the client, you first need to
obtain the raw GnuTLS session handle from MHD using
MHD_get_connection_info.
#include <gnutls/gnutls.h>
#include <gnutls/x509.h>
gnutls_session_t tls_session;
union MHD_ConnectionInfo *ci;
ci = MHD_get_connection_info (connection,
MHD_CONNECTION_INFO_GNUTLS_SESSION);
tls_session = (gnutls_session_t) ci->tls_session;
You can then extract the client certificate:
/**
* 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;
if (0 != client_cert_status)
{
fprintf (stderr,
"Failed client certificate invalid: %d\n",
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;
}
Using the client certificate, you can then get the client’s distinguished name and alternative names:
/**
* 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_t 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;
}
Finally, you should release the memory associated with the client certificate:
gnutls_x509_crt_deinit (client_cert);
SNI enables hosting multiple domains under one IP address with TLS. So SNI is the TLS-equivalent of virtual hosting. To use SNI with MHD, you need at least GnuTLS 3.0. The main change compared to the simple hosting of one domain is that you need to provide a callback instead of the key and certificate. For example, when you start the MHD daemon, you could do this:
daemon = MHD_start_daemon (MHD_USE_INTERNAL_POLLING_THREAD | MHD_USE_SSL,
PORT, NULL, NULL,
&answer_to_connection, NULL,
MHD_OPTION_HTTPS_CERT_CALLBACK, &sni_callback,
MHD_OPTION_END);
Here, sni_callback is the name of a function that you will have to
implement to retrieve the X.509 certificate for an incoming connection.
The callback has type gnutls_certificate_retrieve_function2 and
is documented in the GnuTLS API for the gnutls_certificate_set_retrieve_function2
as follows:
is only used in X.509 certificates. Contains a list with the CA names that the server considers trusted. Normally we should send a certificate that is signed by one of these CAs. These names are DER encoded. To get a more meaningful value use the function gnutls_x509_rdn_get().
contains a list with server’s acceptable signature algorithms. The certificate returned should support the server’s given algorithms.
should contain a single certificate and public or a list of them.
is the size of the previous list.
is the private key.
A possible implementation of this callback would look like this:
struct Hosts
{
struct Hosts *next;
const char *hostname;
gnutls_pcert_st pcrt;
gnutls_privkey_t key;
};
static struct Hosts *hosts;
int
sni_callback (gnutls_session_t session,
const gnutls_datum_t* req_ca_dn,
int nreqs,
const gnutls_pk_algorithm_t* pk_algos,
int pk_algos_length,
gnutls_pcert_st** pcert,
unsigned int *pcert_length,
gnutls_privkey_t * pkey)
{
char name[256];
size_t name_len;
struct Hosts *host;
unsigned int type;
name_len = sizeof (name);
if (GNUTLS_E_SUCCESS !=
gnutls_server_name_get (session,
name,
&name_len,
&type,
0 /* index */))
return -1;
for (host = hosts; NULL != host; host = host->next)
if (0 == strncmp (name, host->hostname, name_len))
break;
if (NULL == host)
{
fprintf (stderr,
"Need certificate for %.*s\n",
(int) name_len,
name);
return -1;
}
fprintf (stderr,
"Returning certificate for %.*s\n",
(int) name_len,
name);
*pkey = host->key;
*pcert_length = 1;
*pcert = &host->pcrt;
return 0;
}
Note that MHD cannot offer passing a closure or any other additional information to this callback, as the GnuTLS API unfortunately does not permit this at this point.
The hosts list can be initialized by loading the private keys and X.509
certificates from disk as follows:
static void
load_keys(const char *hostname,
const char *CERT_FILE,
const char *KEY_FILE)
{
int ret;
gnutls_datum_t data;
struct Hosts *host;
host = malloc (sizeof (struct Hosts));
host->hostname = hostname;
host->next = hosts;
hosts = host;
ret = gnutls_load_file (CERT_FILE, &data);
if (ret < 0)
{
fprintf (stderr,
"*** Error loading certificate file %s.\n",
CERT_FILE);
exit(1);
}
ret =
gnutls_pcert_import_x509_raw (&host->pcrt, &data, GNUTLS_X509_FMT_PEM,
0);
if (ret < 0)
{
fprintf(stderr,
"*** Error loading certificate file: %s\n",
gnutls_strerror (ret));
exit(1);
}
gnutls_free (data.data);
ret = gnutls_load_file (KEY_FILE, &data);
if (ret < 0)
{
fprintf (stderr,
"*** Error loading key file %s.\n",
KEY_FILE);
exit(1);
}
gnutls_privkey_init (&host->key);
ret =
gnutls_privkey_import_x509_raw (host->key,
&data, GNUTLS_X509_FMT_PEM,
NULL, 0);
if (ret < 0)
{
fprintf (stderr,
"*** Error loading key file: %s\n",
gnutls_strerror (ret));
exit(1);
}
gnutls_free (data.data);
}
The code above was largely lifted from GnuTLS. You can find other methods for initializing certificates and keys in the GnuTLS manual and source code.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Websockets are a genuine way to implement push notifications, where the server initiates the communication while the client can be idle. Usually a HTTP communication is half-duplex and always requested by the client, but websockets are full-duplex and only initialized by the client. In the further communication both sites can use the websocket at any time to send data to the other site.
To initialize a websocket connection the client sends a special HTTP request to the server and initializes a handshake between client and server which switches from the HTTP protocol to the websocket protocol. Thus both the server as well as the client must support websockets. If proxys are used, they must support websockets too. In this chapter we take a look on server and client, but with a focus on the server with libmicrohttpd.
Since version 0.9.52 libmicrohttpd supports upgrading requests, which is required for switching from the HTTP protocol. Since version 0.9.74 the library libmicrohttpd_ws has been added to support the websocket protocol.
To support websockets we need to enable upgrading of HTTP connections first.
This is done by passing the flag MHD_ALLOW_UPGRADE to
MHD_start_daemon().
daemon = MHD_start_daemon (MHD_USE_INTERNAL_POLLING_THREAD |
MHD_USE_THREAD_PER_CONNECTION |
MHD_ALLOW_UPGRADE |
MHD_USE_ERROR_LOG,
PORT, NULL, NULL,
&access_handler, NULL,
MHD_OPTION_END);
The next step is to turn a specific request into an upgraded connection.
This done in our access_handler by calling
MHD_create_response_for_upgrade().
An upgrade_handler will be passed to perform the low-level actions
on the socket.
Please note that the socket here is just a regular socket as provided by the operating system. To use it as a websocket, some more steps from the following chapters are required.
static enum MHD_Result
access_handler (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)
{
/* ... */
/* some code to decide whether to upgrade or not */
/* ... */
/* create the response for upgrade */
response = MHD_create_response_for_upgrade (&upgrade_handler,
NULL);
/* ... */
/* additional headers, etc. */
/* ... */
ret = MHD_queue_response (connection,
MHD_HTTP_SWITCHING_PROTOCOLS,
response);
MHD_destroy_response (response);
return ret;
}
In the upgrade_handler we receive the low-level socket,
which is used for the communication with the specific client.
In addition to the low-level socket we get:
struct MHD_UpgradeResponseHandle which is used to perform
special actions like closing, corking or uncorking the socket.
These commands are executed by passing the handle
to MHD_upgrade_action().
Depending of the flags specified while calling MHD_start_deamon()
our upgrade_handler is either executed in the same thread
as our daemon or in a thread specific for each connection.
If it is executed in the same thread then upgrade_handler is
a blocking call for our webserver and
we should finish it as fast as possible (i. e. by creating a thread and
passing the information there).
If MHD_USE_THREAD_PER_CONNECTION was passed to
MHD_start_daemon() then a separate thread is used and
thus our upgrade_handler needs not to start a separate thread.
An upgrade_handler, which is called with a separate thread
per connection, could look like this:
static void
upgrade_handler (void *cls,
struct MHD_Connection *connection,
void *req_cls,
const char *extra_in,
size_t extra_in_size,
MHD_socket fd,
struct MHD_UpgradeResponseHandle *urh)
{
/* ... */
/* do something with the socket `fd` like `recv()` or `send()` */
/* ... */
/* close the socket when it is not needed anymore */
MHD_upgrade_action (urh,
MHD_UPGRADE_ACTION_CLOSE);
}
This is all you need to know for upgrading connections with libmicrohttpd. The next chapters focus on using the websocket protocol with libmicrohttpd_ws.
To request a websocket connection the client must send the following information with the HTTP request:
GET request must be sent.
Host header field must be sent
Upgrade header field containing the keyword "websocket"
(case-insensitive).
Please note that the client could pass multiple protocols separated by comma.
Connection header field that includes the token "Upgrade"
(case-insensitive).
Please note that the client could pass multiple tokens separated by comma.
Sec-WebSocket-Key header field with a base64-encoded value.
The decoded the value is 16 bytes long
and has been generated randomly by the client.
Sec-WebSocket-Version header field with the value "13".
Optionally the client can also send the following information:
Origin header field can be used to determine the source
of the client (i. e. the website).
Sec-WebSocket-Protocol header field can contain a list
of supported protocols by the client, which can be sent over the websocket.
Sec-WebSocket-Extensions header field which may contain extensions
to the websocket protocol. The extensions must be registered by IANA.
A valid example request from the client could look like this:
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13
To complete the handshake the server must respond with some specific response headers:
101 Switching Protocols must be answered.
Upgrade header field containing the value "websocket" must be sent.
Connection header field containing the value "Upgrade" must be sent.
Sec-WebSocket-Accept header field containing a value, which
has been calculated from the Sec-WebSocket-Key request header field,
must be sent.
Optionally the server may send following headers:
Sec-WebSocket-Protocol header field containing a protocol
of the list specified in the corresponding request header field.
Sec-WebSocket-Extension header field containing all used extensions
of the list specified in the corresponding request header field.
A valid websocket HTTP response could look like this:
HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
To upgrade a connection to a websocket the libmicrohttpd_ws provides
some helper functions for the access_handler callback function:
MHD_websocket_check_http_version() checks whether the HTTP version
is 1.1 or above.
MHD_websocket_check_connection_header() checks whether the value
of the Connection request header field contains
an "Upgrade" token (case-insensitive).
MHD_websocket_check_upgrade_header() checks whether the value
of the Upgrade request header field contains
the "websocket" keyword (case-insensitive).
MHD_websocket_check_version_header() checks whether the value
of the Sec-WebSocket-Version request header field is "13".
MHD_websocket_create_accept_header() takes the value from
the Sec-WebSocket-Key request header and calculates the value
for the Sec-WebSocket-Accept response header field.
The access_handler example of the previous chapter can now be
extended with these helper functions to perform the websocket handshake:
static enum MHD_Result
access_handler (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)
{
static int aptr;
struct MHD_Response *response;
enum MHD_Result ret;
(void) cls; /* Unused. Silent compiler warning. */
(void) upload_data; /* Unused. Silent compiler warning. */
(void) upload_data_size; /* Unused. Silent compiler warning. */
if (0 != strcmp (method, "GET"))
return MHD_NO; /* unexpected method */
if (&aptr != *ptr)
{
/* do never respond on first call */
*ptr = &aptr;
return MHD_YES;
}
*ptr = NULL; /* reset when done */
if (0 == strcmp (url, "/"))
{
/* Default page for visiting the server */
struct MHD_Response *response = MHD_create_response_from_buffer (
strlen (PAGE),
PAGE,
MHD_RESPMEM_PERSISTENT);
ret = MHD_queue_response (connection,
MHD_HTTP_OK,
response);
MHD_destroy_response (response);
}
else if (0 == strcmp (url, "/chat"))
{
char is_valid = 1;
const char* value = NULL;
char sec_websocket_accept[29];
if (0 != MHD_websocket_check_http_version (version))
{
is_valid = 0;
}
value = MHD_lookup_connection_value (connection,
MHD_HEADER_KIND,
MHD_HTTP_HEADER_CONNECTION);
if (0 != MHD_websocket_check_connection_header (value))
{
is_valid = 0;
}
value = MHD_lookup_connection_value (connection,
MHD_HEADER_KIND,
MHD_HTTP_HEADER_UPGRADE);
if (0 != MHD_websocket_check_upgrade_header (value))
{
is_valid = 0;
}
value = MHD_lookup_connection_value (connection,
MHD_HEADER_KIND,
MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION);
if (0 != MHD_websocket_check_version_header (value))
{
is_valid = 0;
}
value = MHD_lookup_connection_value (connection,
MHD_HEADER_KIND,
MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY);
if (0 != MHD_websocket_create_accept_header (value, sec_websocket_accept))
{
is_valid = 0;
}
if (1 == is_valid)
{
/* upgrade the connection */
response = MHD_create_response_for_upgrade (&upgrade_handler,
NULL);
MHD_add_response_header (response,
MHD_HTTP_HEADER_CONNECTION,
"Upgrade");
MHD_add_response_header (response,
MHD_HTTP_HEADER_UPGRADE,
"websocket");
MHD_add_response_header (response,
MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT,
sec_websocket_accept);
ret = MHD_queue_response (connection,
MHD_HTTP_SWITCHING_PROTOCOLS,
response);
MHD_destroy_response (response);
}
else
{
/* return error page */
struct MHD_Response*response = MHD_create_response_from_buffer (
strlen (PAGE_INVALID_WEBSOCKET_REQUEST),
PAGE_INVALID_WEBSOCKET_REQUEST,
MHD_RESPMEM_PERSISTENT);
ret = MHD_queue_response (connection,
MHD_HTTP_BAD_REQUEST,
response);
MHD_destroy_response (response);
}
}
else
{
struct MHD_Response*response = MHD_create_response_from_buffer (
strlen (PAGE_NOT_FOUND),
PAGE_NOT_FOUND,
MHD_RESPMEM_PERSISTENT);
ret = MHD_queue_response (connection,
MHD_HTTP_NOT_FOUND,
response);
MHD_destroy_response (response);
}
return ret;
}
Please note that we skipped the check of the Host header field here, because we don’t know the host for this example.
Once the websocket connection is established you can receive/send frame data
with the low-level socket functions recv() and send().
The frame data which goes over the low-level socket is encoded according
to the websocket protocol.
To use received payload data, you need to decode the frame data first.
To send payload data, you need to encode it into frame data first.
libmicrohttpd_ws provides several functions for encoding of payload data and decoding of frame data:
MHD_websocket_decode() decodes received frame data.
The payload data may be of any kind, depending upon what the client has sent.
So this decode function is used for all kind of frames and returns
the frame type along with the payload data.
MHD_websocket_encode_text() encodes text.
The text must be encoded with UTF-8.
MHD_websocket_encode_binary() encodes binary data.
MHD_websocket_encode_ping() encodes a ping request to
check whether the websocket is still valid and to test latency.
MHD_websocket_encode_ping() encodes a pong response to
answer a received ping request.
MHD_websocket_encode_close() encodes a close request.
MHD_websocket_free() frees data returned by the encode/decode functions.
Since you could receive or send fragmented data (i. e. due to a too
small buffer passed to recv) all of these encode/decode
functions require a pointer to a struct MHD_WebSocketStream passed
as argument.
In this structure libmicrohttpd_ws stores information
about encoding/decoding of the particular websocket.
For each websocket you need a unique struct MHD_WebSocketStream
to encode/decode with this library.
To create or destroy struct MHD_WebSocketStream
we have additional functions:
MHD_websocket_stream_init() allocates and initializes
a new struct MHD_WebSocketStream.
You can specify some options here to alter the behavior of the websocket stream.
MHD_websocket_stream_free() frees a previously allocated
struct MHD_WebSocketStream.
With these encode/decode functions we can improve our upgrade_handler
callback function from an earlier example to a working websocket:
static void
upgrade_handler (void *cls,
struct MHD_Connection *connection,
void *req_cls,
const char *extra_in,
size_t extra_in_size,
MHD_socket fd,
struct MHD_UpgradeResponseHandle *urh)
{
/* make the socket blocking (operating-system-dependent code) */
make_blocking (fd);
/* create a websocket stream for this connection */
struct MHD_WebSocketStream* ws;
int result = MHD_websocket_stream_init (&ws,
0,
0);
if (0 != result)
{
/* Couldn't create the websocket stream.
* So we close the socket and leave
*/
MHD_upgrade_action (urh,
MHD_UPGRADE_ACTION_CLOSE);
return;
}
/* Let's wait for incoming data */
const size_t buf_len = 256;
char buf[buf_len];
ssize_t got;
while (MHD_WEBSOCKET_VALIDITY_VALID == MHD_websocket_stream_is_valid (ws))
{
got = recv (fd,
buf,
buf_len,
0);
if (0 >= got)
{
/* the TCP/IP socket has been closed */
break;
}
/* parse the entire received data */
size_t buf_offset = 0;
while (buf_offset < (size_t) got)
{
size_t new_offset = 0;
char *frame_data = NULL;
size_t frame_len = 0;
int status = MHD_websocket_decode (ws,
buf + buf_offset,
((size_t) got) - buf_offset,
&new_offset,
&frame_data,
&frame_len);
if (0 > status)
{
/* an error occurred and the connection must be closed */
if (NULL != frame_data)
{
MHD_websocket_free (ws, frame_data);
}
break;
}
else
{
buf_offset += new_offset;
if (0 < status)
{
/* the frame is complete */
switch (status)
{
case MHD_WEBSOCKET_STATUS_TEXT_FRAME:
/* The client has sent some text.
* We will display it and answer with a text frame.
*/
if (NULL != frame_data)
{
printf ("Received message: %s\n", frame_data);
MHD_websocket_free (ws, frame_data);
frame_data = NULL;
}
result = MHD_websocket_encode_text (ws,
"Hello",
5, /* length of "Hello" */
0,
&frame_data,
&frame_len,
NULL);
if (0 == result)
{
send_all (fd,
frame_data,
frame_len);
}
break;
case MHD_WEBSOCKET_STATUS_CLOSE_FRAME:
/* if we receive a close frame, we will respond with one */
MHD_websocket_free (ws,
frame_data);
frame_data = NULL;
result = MHD_websocket_encode_close (ws,
0,
NULL,
0,
&frame_data,
&frame_len);
if (0 == result)
{
send_all (fd,
frame_data,
frame_len);
}
break;
case MHD_WEBSOCKET_STATUS_PING_FRAME:
/* if we receive a ping frame, we will respond */
/* with the corresponding pong frame */
{
char *pong = NULL;
size_t pong_len = 0;
result = MHD_websocket_encode_pong (ws,
frame_data,
frame_len,
&pong,
&pong_len);
if (0 == result)
{
send_all (fd,
pong,
pong_len);
}
MHD_websocket_free (ws,
pong);
}
break;
default:
/* Other frame types are ignored
* in this minimal example.
* This is valid, because they become
* automatically skipped if we receive them unexpectedly
*/
break;
}
}
if (NULL != frame_data)
{
MHD_websocket_free (ws, frame_data);
}
}
}
}
/* free the websocket stream */
MHD_websocket_stream_free (ws);
/* close the socket when it is not needed anymore */
MHD_upgrade_action (urh,
MHD_UPGRADE_ACTION_CLOSE);
}
/* This helper function is used for the case that
* we need to resend some data
*/
static void
send_all (MHD_socket fd,
const char *buf,
size_t len)
{
ssize_t ret;
size_t off;
for (off = 0; off < len; off += ret)
{
ret = send (fd,
&buf[off],
(int) (len - off),
0);
if (0 > ret)
{
if (EAGAIN == errno)
{
ret = 0;
continue;
}
break;
}
if (0 == ret)
break;
}
}
/* This helper function contains operating-system-dependent code and
* is used to make a socket blocking.
*/
static void
make_blocking (MHD_socket fd)
{
#if defined(MHD_POSIX_SOCKETS)
int flags;
flags = fcntl (fd, F_GETFL);
if (-1 == flags)
return;
if ((flags & ~O_NONBLOCK) != flags)
if (-1 == fcntl (fd, F_SETFL, flags & ~O_NONBLOCK))
abort ();
#elif defined(MHD_WINSOCK_SOCKETS)
unsigned long flags = 0;
ioctlsocket (fd, FIONBIO, &flags);
#endif /* MHD_WINSOCK_SOCKETS */
}
Please note that the websocket in this example is only half-duplex.
It waits until the blocking recv() call returns and
only does then something.
In this example all frame types are decoded by libmicrohttpd_ws,
but we only do something when a text, ping or close frame is received.
Binary and pong frames are ignored in our code.
This is legit, because the server is only required to implement at
least support for ping frame or close frame (the other frame types
could be skipped in theory, because they don’t require an answer).
The pong frame doesn’t require an answer and whether text frames or
binary frames get an answer simply belongs to your server application.
So this is a valid minimal example.
Until this point you’ve learned everything you need to basically use websockets with libmicrohttpd and libmicrohttpd_ws. These libraries offer much more functions for some specific cases.
The further chapters of this tutorial focus on some specific problems and the client site programming.
To use full-duplex websockets you can simply create two threads
per websocket connection.
One of these threads is used for receiving data with
a blocking recv() call and the other thread is triggered
by the application internal codes and sends the data.
A full-duplex websocket example is implemented in the example file
websocket_chatserver_example.c.
The most functions of libmicrohttpd_ws return a value
of enum MHD_WEBSOCKET_STATUS.
The values of this enumeration can be converted into an integer
and have an easy interpretation:
MHD_websocket_decode()
(of the functions with this return enumeration type).
A websocket stream can also get broken when invalid frame data is received.
Also the other site could send a close frame which puts the stream into
a state where it may not be used for regular communication.
Whether a stream has become broken, can be checked with
MHD_websocket_stream_is_valid().
In addition to the regular TCP/IP fragmentation the websocket protocol also
supports fragmentation.
Fragmentation could be used for continuous payload data such as video data
from a webcam.
Whether or not you want to receive fragmentation is specified upon
initialization of the websocket stream.
If you pass MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS in the flags parameter
of MHD_websocket_stream_init() then you can receive fragments.
If you don’t pass this flag (in the most cases you just pass zero as flags)
then you don’t want to handle fragments on your own.
libmicrohttpd_ws removes then the fragmentation for you
in the background.
You only get the completely assembled frames.
Upon encoding you specify whether or not you want to create a fragmented frame
by passing a flag to the corresponding encode function.
Only MHD_websocket_encode_text() and MHD_websocket_encode_binary()
can be used for fragmentation, because the other frame types may
not be fragmented.
Encoding fragmented frames is independent of
the MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS flag upon initialization.
Websockets are supported in all modern web browsers.
You initialize a websocket connection by creating an instance of
the WebSocket class provided by the web browser.
There are some simple rules for using websockets in the browser:
ws://
(for not encrypted websocket protocol) or wss://
(for TLS-encrypted websocket protocol).
IMPORTANT: If your website is accessed via https://
then you are in a security context, which means that you are only allowed to
access other secure protocols.
So you can only use wss:// for websocket connections then.
If you try to ws:// instead then your websocket connection will
automatically fail.
Here is a short example for receiving/sending data to the same host as the website is running on:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Websocket Demo</title>
<script>
let url = 'ws' + (window.location.protocol === 'https:' ? 's' : '') + '://' +
window.location.host + '/chat';
let socket = null;
window.onload = function(event) {
socket = new WebSocket(url);
socket.onopen = function(event) {
document.write('The websocket connection has been established.<br>');
// Send some text
socket.send('Hello from JavaScript!');
}
socket.onclose = function(event) {
document.write('The websocket connection has been closed.<br>');
}
socket.onerror = function(event) {
document.write('An error occurred during the websocket communication.<br>');
}
socket.onmessage = function(event) {
document.write('Websocket message received: ' + event.data + '<br>');
}
}
</script>
</head>
<body>
</body>
</html>
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
For those readers understanding German or French, there is an excellent document both for learning HTML and for reference, whose English version unfortunately has been discontinued. http://de.selfhtml.org/ and http://fr.selfhtml.org/
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Version 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. http://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. |
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. |
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
|
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| C.1 hellobrowser.c | ||
| C.2 logging.c | ||
| C.3 responseheaders.c | ||
| C.4 basicauthentication.c | ||
| C.5 simplepost.c | ||
| C.6 largepost.c | ||
| C.7 sessions.c | ||
| C.8 tlsauthentication.c | ||
| C.9 websocket.c |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
|
| [Top] | [Contents] | [Index] | [ ? ] |
| [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on August 16, 2025 using texi2html 1.82.
The buttons in the navigation panels have the following meaning:
| Button | Name | Go to | From 1.2.3 go to |
|---|---|---|---|
| [ < ] | Back | Previous section in reading order | 1.2.2 |
| [ > ] | Forward | Next section in reading order | 1.2.4 |
| [ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
| [ Up ] | Up | Up section | 1.2 |
| [ >> ] | FastForward | Next chapter | 2 |
| [Top] | Top | Cover (top) of document | |
| [Contents] | Contents | Table of contents | |
| [Index] | Index | Index | |
| [ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on August 16, 2025 using texi2html 1.82.