commit 5e5efd92797e01595ea69826cde808d8e13ae26e
parent 6bdb28d9a6e0f1a21619dfa8539c3ec1b562c337
Author: Evgeny Grin (Karlson2k) <k2k@narod.ru>
Date: Wed, 24 Aug 2022 14:07:27 +0300
microhttpd.h: doxy and other minor improvements
Diffstat:
1 file changed, 15 insertions(+), 11 deletions(-)
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
@@ -168,12 +168,6 @@ enum MHD_Result
} _MHD_FIXED_ENUM;
-
-/**
- * MHD digest auth internal code for an invalid nonce.
- */
-#define MHD_INVALID_NONCE -1
-
/**
* Constant used to indicate unknown size (use when
* creating a response).
@@ -1546,8 +1540,9 @@ typedef int
* These values can limit the scope of validity of MHD-generated nonces.
* Values can be combined with bitwise OR.
* Any value, except #MHD_DAUTH_BIND_NONCE_NONE, enforce function
- * #MHD_digest_auth_check3() (and similar) to check nonce by re-generating
- * it again with the same parameters, which is CPU-intensive operation.
+ * #MHD_digest_auth_check3() (and similar functions) to check nonce by
+ * re-generating it again with the same parameters, which is CPU-intensive
+ * operation.
* @note Available since #MHD_VERSION 0x00097531
*/
enum MHD_DAuthBindNonce
@@ -1555,13 +1550,13 @@ enum MHD_DAuthBindNonce
/**
* Generated nonces are valid for any request from any client until expired.
* This is default and recommended value.
- * #MHD_digest_auth_check3() (and similar function) would check only whether
+ * #MHD_digest_auth_check3() (and similar functions) would check only whether
* the nonce value that is used by client has been generated by MHD and not
* expired yet.
* It is recommended because RFC 7616 allows clients to use the same nonce
* for any request in the same "protection space".
* CPU is loaded less when this value is used when checking client's
- * authorisation request.
+ * authorisation requests.
* This mode gives MHD maximum flexibility for nonces generation and can
* prevent possible nonce collisions (and corresponding log warning messages)
* when clients' requests are intensive.
@@ -4815,7 +4810,7 @@ struct MHD_DigestAuthInfo
* The username string.
* Valid only if username is standard, extended, or userhash.
* For userhash this is unqoted string without decoding of the
- * hexadecimal digits (as provided by client).
+ * hexadecimal digits (as provided by the client).
* If extended notation is used, this string is pct-decoded string
* with charset and language tag removed (i.e. it is original username
* extracted from the extended notation).
@@ -4834,6 +4829,7 @@ struct MHD_DigestAuthInfo
* Used only if username type is userhash, always NULL otherwise.
* When not NULL, this points to binary sequence @a username_len /2 bytes
* long.
+ * The valid size should be #MHD_digest_get_hash_size(algo) bytes.
* @warning This is binary data, no zero termination.
* @warning To avoid buffer overruns, always check the size of the data before
* use, because @a userhash_bin can point even to zero-sized
@@ -4946,8 +4942,10 @@ struct MHD_DigestAuthUsernameInfo
/**
* The userhash decoded to binary form.
+ * Used only if username type is userhash, always NULL otherwise.
* When not NULL, this points to binary sequence @a username_len /2 bytes
* long.
+ * The valid size should be #MHD_digest_get_hash_size(algo) bytes.
* @warning This is binary data, no zero termination.
* @warning To avoid buffer overruns, always check the size of the data before
* use, because @a userhash_bin can point even to zero-sized
@@ -5251,6 +5249,12 @@ MHD_digest_auth_get_username (struct MHD_Connection *connection);
/**
+ * MHD digest auth internal code for an invalid nonce.
+ */
+#define MHD_INVALID_NONCE -1
+
+
+/**
* Which digest algorithm should MHD use for HTTP digest authentication?
* Used as parameter for #MHD_digest_auth_check2(),
* #MHD_digest_auth_check_digest2(), #MHD_queue_auth_fail_response2().
