1 files changed, 207 insertions, 0 deletions

diff --git a/doc/chapters/basicauthentication.inc b/doc/chapters/basicauthentication.inc
new file mode 100644
index 00000000..8e7f4c60
--- /dev/null
+++ b/doc/chapters/basicauthentication.inc
@@ -0,0 +1,207 @@
+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 @emph{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
+@verbatim
+GET /picture.png?mypassword
+@end verbatim
+@noindent
+
+In a 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),
+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 @emph{Basic Authentication} as described in @emph{RFC 2617},
+we should finally abandon the bad practice of responding every request the first time our callback
+is called for a given connection. This is becoming more important now because the client and 
+the server will have to talk in a more bi-directional way than before to 
+
+But how can we tell whether the callback has been called before for the particular connection?
+Initially, the pointer this parameter references is set by @emph{MHD} in the callback. But it will 
+also be "remembered" on the next call (for the same connection).
+Thus, we will 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 adress that is assured to be not null. The pointer to the 
+@code{connection} structure will be pointing to a legal adress, so we take this.
+
+Not even the headers will be looked at on the first iteration.
+
+@verbatim
+int answer_to_connection (void *cls, struct MHD_Connection *connection,
+                          const char *url, const char *method, const char *version, 
+                          const char *upload_data, unsigned int *upload_data_size,
+                          void **con_cls)
+{
+  if (0 != strcmp(method, "GET")) return MHD_NO;
+  if (NULL == *con_cls) {*con_cls = connection; return MHD_YES;}
+
+  ... 
+  /* else respond accordingly */
+  ...
+}
+@end verbatim
+@noindent
+
+Note how we lop off the connection on the first condition, but return asking for more on 
+the other one with @code{MHD_YES}.
+With the framework improved, we can proceed to implement the actual authentication process.
+
+@heading Request for authentication 
+
+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.
+@emph{RFC 2617} describes how the server shall ask for authentication by adding a
+@emph{WWW-Authenticate} response header with the name of the @emph{realm} protected.
+
+We let an extra function function do this.
+@verbatim
+int ask_for_authentication (struct MHD_Connection *connection, const char *realm)
+{
+  int ret;
+  struct MHD_Response *response;
+  char *headervalue;
+  const char *strbase = "Basic realm=";
+  
+  response = MHD_create_response_from_data (0, NULL, MHD_NO, MHD_NO);
+  if (!response) return MHD_NO;
+  
+  headervalue = malloc (strlen (strbase) + strlen (realm) + 1);
+  if (!headervalue) return MHD_NO;  
+
+  strcpy (headervalue, strbase);
+  strcat (headervalue, realm);
+  
+  ret = MHD_add_response_header (response, "WWW-Authenticate", headervalue);
+  free (headervalue);  
+  if (!ret) {MHD_destroy_response (response); return MHD_NO;}
+
+  ret = MHD_queue_response (connection, MHD_HTTP_UNAUTHORIZED, response);
+  
+  MHD_destroy_response (response);
+
+  return ret;
+}
+@end verbatim
+@noindent
+
+@code{#define} the realm name according to your own taste, e.g. "Maintenance" or "Area51" but
+it will need to have extra quotes.
+
+But the client may send the authentication right away, so it would be wrong to ask for
+it without checking the request's header--where the authentication is expected to be found.
+
+@heading Authentication in detail
+Checking @emph{RFC 2617} again, we find that the client will pack the username and password, by
+whatever means he might have obtained them, in a line separated by a colon---and then encodes
+them to @emph{Base64}. The actual implementation of this encoding are not within the scope of
+this tutorial although a working function is included in the complete source file of the example.
+
+An unencoded word describing the authentication method (here "Basic") will precede the code
+and the resulting line is the value of a request header of the type "Authorization".  
+
+This header line thus is of interest to the function checking a connection for a given username/password:
+@verbatim
+int is_authenticated (struct MHD_Connection *connection,
+                      const char *username, const char *password)
+{
+  const char *headervalue;
+  ...
+
+  headervalue = MHD_lookup_connection_value (connection, MHD_HEADER_KIND,
+                                             "Authorization");
+  if (NULL == headervalue) return 0;
+@end verbatim
+@noindent
+
+where, firstly, the authentication method will be checked.
+@verbatim
+const char *strbase = "Basic ";
+...
+if (0 != strncmp (headervalue, strbase, strlen (strbase))) return 0;
+@end verbatim
+@noindent
+
+Of course, we could decode the passed credentials in the next step and compare them directly to
+the given strings. But as this would involve string parsing, which is more complicated then string
+composing, it is done the other way around---the clear text credentials will be encoded to @emph{Base64}
+and then compared against the headerline. The authentication method string will be left out here as
+it has been checked already at this point.
+@verbatim
+  char *expected_b64, *expected;
+  int authenticated;
+
+  ...
+  strcpy (expected, username);
+  strcat (expected, ":");
+  strcat (expected, password);  
+
+  expected_b64 = string_to_base64 (expected);
+  if (NULL == expected_b64) return 0;
+ 
+  strcpy (expected, strbase);
+  authenticated = (strcmp (headervalue + strlen (strbase), expected_b64) == 0);
+
+  free (expected_b64);
+
+  return authenticated;
+}
+@end verbatim
+@noindent
+
+These two functions---together with a response function in case of positive authentication doing little 
+new---allow the rest of the callback function to be rather short. 
+@verbatim
+  if (!is_authenticated (connection, USER, PASSWORD)) 
+    return ask_for_authentication (connection, REALM); 
+  
+  return secret_page (connection);
+}
+@end verbatim
+@noindent
+
+See the @code{examples} directory for the complete example file.
+
+@heading Remarks
+For a proper server, the conditional statements leading to a return of @code{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 @emph{internal server error} and unexpected 
+authentication methods as @emph{400 bad request}.
+
+@heading Exercises
+@itemize @bullet
+@item
+Make the server respond to wrong credentials (but else correct requests) with the recommended
+@emph{401 unauthorized} status code. If the client still does not authenticate correctly within the
+same connection, close it and store the client's IP address for a certain time. (It is OK to check for
+expiration not until the main thread wakes up again on the next connection.) If the client fails
+authenticating three times during this period, add it to another list whose entries the 
+@code{AcceptPolicyCallback} function denies connection (temporally).
+
+@item
+With the network utility @emph{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 @emph{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. @code{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.
+
+@end itemize
+
+