websocket update

- added API documentation to libmicrohttpd.texi
- added websocket tutorial chapter to libmicrohttpd-tutorial and an much easier example for the tutorial
- added additional helper functions to ease the HTTP websocket handshake
- the code can now be compiled on Linux without errors
- changed sha1.c and sha1.h to the files provided by Evgeny (I replaced those files in src/microhttpd_ws/ with the files from src/microhttpd/ - maybe there is a smarter way...?)
- removed dependency for "htons" and "htonl" (these functions are now implemented in MHD_websocket.c; no need for OS-dependent files anymore)
- added an additional test script for testing of the library with any webbrowser (for manual practice test)
- several bugfixes
- parameters renamed
- special things clarified (fragmentation, RNG for client mode)

The new version of the API is at some points incompatible with the old version, but since it was in an experimental phase and it didn't compile on Linux, I guess this shouldn't bother anyone.
From my point of view, I am now finished with the library and it could go out of experimental.

1 files changed, 105 insertions, 140 deletions

diff --git a/src/microhttpd_ws/sha1.h b/src/microhttpd_ws/sha1.h
index be0d190b..851a4429 100644
--- a/src/microhttpd_ws/sha1.h
+++ b/src/microhttpd_ws/sha1.h
@@ -1,145 +1,110 @@
-/* Declarations of functions and data types used for SHA1 sum
-   library functions.
-   Copyright (C) 2000-2021 Free Software Foundation, Inc.
-
-   This program is free software; you can redistribute it and/or modify it
-   under the terms of the GNU General Public License as published by the
-   Free Software Foundation; either version 3, or (at your option) any
-   later version.
-
-   This program is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU General Public License for more details.
-
-   You should have received a copy of the GNU General Public License
-   along with this program; if not, write to the Free Software Foundation,
-   Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
-
-#ifndef SHA1_H
-# define SHA1_H 1
-
-#include <stdio.h>
-
-#if defined HAVE_LIMITS_H || _LIBC
-# include <limits.h>
-#endif
-
-/*#include "ansidecl.h"*/
-
-/* The following contortions are an attempt to use the C preprocessor
-   to determine an unsigned integral type that is 32 bits wide.  An
-   alternative approach is to use autoconf's AC_CHECK_SIZEOF macro, but
-   doing that would require that the configure script compile and *run*
-   the resulting executable.  Locally running cross-compiled executables
-   is usually not possible.  */
-
-#ifdef _LIBC
-# include <sys/types.h>
-typedef u_int32_t sha1_uint32;
-typedef uintptr_t sha1_uintptr;
-#elif defined (HAVE_SYS_TYPES_H) && defined (HAVE_STDINT_H)
+/*
+     This file is part of libmicrohttpd
+     Copyright (C) 2019-2021 Karlson2k (Evgeny Grin)
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library.
+     If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @file microhttpd/sha1.h
+ * @brief  Calculation of SHA-1 digest
+ * @author Karlson2k (Evgeny Grin)
+ */
+
+#ifndef MHD_SHA1_H
+#define MHD_SHA1_H 1
+
+#include "mhd_options.h"
 #include <stdint.h>
-#include <sys/types.h>
-typedef uint32_t sha1_uint32;
-typedef uintptr_t sha1_uintptr;
-#else
-#  define INT_MAX_32_BITS 2147483647
-
-/* If UINT_MAX isn't defined, assume it's a 32-bit type.
-   This should be valid for all systems GNU cares about because
-   that doesn't include 16-bit systems, and only modern systems
-   (that certainly have <limits.h>) have 64+-bit integral types.  */
-
-# ifndef INT_MAX
-#  define INT_MAX INT_MAX_32_BITS
-# endif
-
-# if INT_MAX == INT_MAX_32_BITS
-typedef unsigned int sha1_uint32;
-# else
-#  if SHRT_MAX == INT_MAX_32_BITS
-typedef unsigned short sha1_uint32;
-#  else
-#   if LONG_MAX == INT_MAX_32_BITS
-typedef unsigned long sha1_uint32;
-#   else
-/* The following line is intended to evoke an error.
-        Using #error is not portable enough.  */
-"Cannot determine unsigned 32-bit data type."
-#   endif
-#  endif
-# endif
-#endif
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/* Structure to save state of computation between the single steps.  */
+#ifdef HAVE_STDDEF_H
+#include <stddef.h>  /* for size_t */
+#endif /* HAVE_STDDEF_H */
+
+/**
+ *  SHA-1 digest is kept internally as 5 32-bit words.
+ */
+#define _SHA1_DIGEST_LENGTH 5
+
+/**
+ * Number of bits in single SHA-1 word
+ */
+#define SHA1_WORD_SIZE_BITS 32
+
+/**
+ * Number of bytes in single SHA-1 word
+ */
+#define SHA1_BYTES_IN_WORD (SHA1_WORD_SIZE_BITS / 8)
+
+/**
+ * Size of SHA-1 digest in bytes
+ */
+#define SHA1_DIGEST_SIZE (_SHA1_DIGEST_LENGTH * SHA1_BYTES_IN_WORD)
+
+/**
+ * Size of SHA-1 digest string in chars including termination NUL
+ */
+#define SHA1_DIGEST_STRING_SIZE ((SHA1_DIGEST_SIZE) * 2 + 1)
+
+/**
+ * Size of single processing block in bits
+ */
+#define SHA1_BLOCK_SIZE_BITS 512
+
+/**
+ * Size of single processing block in bytes
+ */
+#define SHA1_BLOCK_SIZE (SHA1_BLOCK_SIZE_BITS / 8)
+
+
 struct sha1_ctx
 {
-  sha1_uint32 A;
-  sha1_uint32 B;
-  sha1_uint32 C;
-  sha1_uint32 D;
-  sha1_uint32 E;
-
-  sha1_uint32 total[2];
-  sha1_uint32 buflen;
-  sha1_uint32 buffer[32];
+  uint32_t H[_SHA1_DIGEST_LENGTH];    /**< Intermediate hash value / digest at end of calculation */
+  uint8_t buffer[SHA1_BLOCK_SIZE];    /**< SHA256 input data buffer */
+  uint64_t count;                     /**< number of bytes, mod 2^64 */
 };
 
-
-/* Initialize structure containing state of computation. */
-extern void sha1_init_ctx (struct sha1_ctx *ctx);
-
-/* Starting with the result of former calls of this function (or the
-   initialization function update the context for the next LEN bytes
-   starting at BUFFER.
-   It is necessary that LEN is a multiple of 64!!! */
-extern void sha1_process_block (const void *buffer, size_t len,
-                                struct sha1_ctx *ctx);
-
-/* Starting with the result of former calls of this function (or the
-   initialization function update the context for the next LEN bytes
-   starting at BUFFER.
-   It is NOT required that LEN is a multiple of 64.  */
-extern void sha1_process_bytes (const void *buffer, size_t len,
-                                struct sha1_ctx *ctx);
-
-/* Process the remaining bytes in the buffer and put result from CTX
-   in first 20 bytes following RESBUF.  The result is always in little
-   endian byte order, so that a byte-wise output yields to the wanted
-   ASCII representation of the message digest.
-
-   IMPORTANT: On some systems it is required that RESBUF be correctly
-   aligned for a 32 bits value.  */
-extern void *sha1_finish_ctx (struct sha1_ctx *ctx, void *resbuf);
-
-
-/* Put result from CTX in first 20 bytes following RESBUF.  The result is
-   always in little endian byte order, so that a byte-wise output yields
-   to the wanted ASCII representation of the message digest.
-
-   IMPORTANT: On some systems it is required that RESBUF is correctly
-   aligned for a 32 bits value.  */
-extern void *sha1_read_ctx (const struct sha1_ctx *ctx, void *resbuf);
-
-
-/* Compute SHA1 message digest for bytes read from STREAM.  The
-   resulting message digest number will be written into the 20 bytes
-   beginning at RESBLOCK.  */
-extern int sha1_stream (FILE *stream, void *resblock);
-
-/* Compute SHA1 message digest for LEN bytes beginning at BUFFER.  The
-   result is always in little endian byte order, so that a byte-wise
-   output yields to the wanted ASCII representation of the message
-   digest.  */
-extern void *sha1_buffer (const char *buffer, size_t len, void *resblock);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif
+/**
+ * Initialise structure for SHA-1 calculation.
+ *
+ * @param ctx must be a `struct sha1_ctx *`
+ */
+void
+MHD_SHA1_init (void *ctx_);
+
+
+/**
+ * Process portion of bytes.
+ *
+ * @param ctx_ must be a `struct sha1_ctx *`
+ * @param data bytes to add to hash
+ * @param length number of bytes in @a data
+ */
+void
+MHD_SHA1_update (void *ctx_,
+                 const uint8_t *data,
+                 size_t length);
+
+
+/**
+ * Finalise SHA-1 calculation, return digest.
+ *
+ * @param ctx_ must be a `struct sha1_ctx *`
+ * @param[out] digest set to the hash, must be #SHA1_DIGEST_SIZE bytes
+ */
+void
+MHD_SHA1_finish (void *ctx_,
+                 uint8_t digest[SHA1_DIGEST_SIZE]);
+
+#endif /* MHD_SHA1_H */