diff options
author | Evgeny Grin (Karlson2k) <k2k@narod.ru> | 2022-05-13 17:23:22 +0300 |
---|---|---|
committer | Evgeny Grin (Karlson2k) <k2k@narod.ru> | 2022-05-13 17:23:22 +0300 |
commit | 15ea1533a8bb7c9d8eafb25defe4aeba6fa3f7f2 (patch) | |
tree | 48623a3ae228a59fe7d27252f173e8a82268f910 | |
parent | 001b6b87fddcb14eb176411ba96ae7d985c88c12 (diff) | |
download | libmicrohttpd-15ea1533a8bb7c9d8eafb25defe4aeba6fa3f7f2.tar.gz libmicrohttpd-15ea1533a8bb7c9d8eafb25defe4aeba6fa3f7f2.zip |
Updated .texi with the new digest auth functions
-rw-r--r-- | doc/libmicrohttpd.texi | 93 |
1 files changed, 83 insertions, 10 deletions
diff --git a/doc/libmicrohttpd.texi b/doc/libmicrohttpd.texi index dfe8a686..f86eacd9 100644 --- a/doc/libmicrohttpd.texi +++ b/doc/libmicrohttpd.texi | |||
@@ -71,10 +71,10 @@ Free Documentation License". | |||
71 | 71 | ||
72 | Appendices | 72 | Appendices |
73 | 73 | ||
74 | * GNU-LGPL:: The GNU Lesser General Public License says how you | 74 | * GNU-LGPL:: The GNU Lesser General Public License says how you |
75 | can copy and share almost all of `libmicrohttpd'. | 75 | can copy and share almost all of `libmicrohttpd'. |
76 | * eCos License:: The eCos License says how you can copy and share some parts of `libmicrohttpd'. | 76 | * eCos License:: The eCos License says how you can copy and share some parts of `libmicrohttpd'. |
77 | * GNU-GPL:: The GNU General Public License (with eCos extension) says how you can copy and share some parts of `libmicrohttpd'. | 77 | * GNU-GPL:: The GNU General Public License (with eCos extension) says how you can copy and share some parts of `libmicrohttpd'. |
78 | * GNU-FDL:: The GNU Free Documentation License says how you | 78 | * GNU-FDL:: The GNU Free Documentation License says how you |
79 | can copy and share the documentation of `libmicrohttpd'. | 79 | can copy and share the documentation of `libmicrohttpd'. |
80 | 80 | ||
@@ -3100,8 +3100,8 @@ machine and user authentication). A code example for using | |||
3100 | client certificates is presented in the MHD tutorial. | 3100 | client certificates is presented in the MHD tutorial. |
3101 | 3101 | ||
3102 | @menu | 3102 | @menu |
3103 | * microhttpd-dauth basic:: Using Basic Authentication. | 3103 | * microhttpd-dauth basic:: Using Basic Authentication. |
3104 | * microhttpd-dauth digest:: Using Digest Authentication. | 3104 | * microhttpd-dauth digest:: Using Digest Authentication. |
3105 | @end menu | 3105 | @end menu |
3106 | 3106 | ||
3107 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | 3107 | @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
@@ -3159,6 +3159,42 @@ Force use of SHA-256. | |||
3159 | @end table | 3159 | @end table |
3160 | @end deftp | 3160 | @end deftp |
3161 | 3161 | ||
3162 | @deftp {Enumeration} MHD_DigestAuthResult | ||
3163 | The result of digest authentication of the client. | ||
3164 | |||
3165 | @table @code | ||
3166 | @item MHD_DAUTH_OK | ||
3167 | Authentication OK. | ||
3168 | |||
3169 | @item MHD_DAUTH_ERROR | ||
3170 | General error, like ``out of memory''. | ||
3171 | |||
3172 | @item MHD_DAUTH_WRONG_HEADER | ||
3173 | No ``Authorization'' header or wrong format of the header. | ||
3174 | |||
3175 | @item MHD_DAUTH_WRONG_USERNAME | ||
3176 | Wrong ``username''. | ||
3177 | |||
3178 | @item MHD_DAUTH_WRONG_REALM | ||
3179 | Wrong ``realm''. | ||
3180 | |||
3181 | @item MHD_DAUTH_WRONG_URI | ||
3182 | Wrong ``URI'' (or URI parameters). | ||
3183 | |||
3184 | @item MHD_DAUTH_NONCE_STALE | ||
3185 | The ``nonce'' is too old. Suggest the client to retry with the same username and | ||
3186 | password to get the fresh ``nonce''. | ||
3187 | The validity of the 'nonce' may not be checked. | ||
3188 | |||
3189 | @item MHD_DAUTH_NONCE_WRONG | ||
3190 | The ``nonce'' is wrong. May indicate an attack attempt. | ||
3191 | |||
3192 | @item MHD_DAUTH_RESPONSE_WRONG | ||
3193 | The ``response'' is wrong. May indicate an attack attempt. | ||
3194 | |||
3195 | @end table | ||
3196 | @end deftp | ||
3197 | |||
3162 | 3198 | ||
3163 | @deftypefun {char *} MHD_digest_auth_get_username (struct MHD_Connection *connection) | 3199 | @deftypefun {char *} MHD_digest_auth_get_username (struct MHD_Connection *connection) |
3164 | Find and return a pointer to the username value from the request header. | 3200 | Find and return a pointer to the username value from the request header. |
@@ -3166,6 +3202,24 @@ Return @code{NULL} if the value is not found or header does not exist. | |||
3166 | If returned value is not @code{NULL}, the value must be @code{MHD_free()}'ed. | 3202 | If returned value is not @code{NULL}, the value must be @code{MHD_free()}'ed. |
3167 | @end deftypefun | 3203 | @end deftypefun |
3168 | 3204 | ||
3205 | @deftypefun enum MHD_DigestAuthResult MHD_digest_auth_check3 (struct MHD_Connection *connection, const char *realm, const char *username, const char *password, unsigned int nonce_timeout, enum MHD_DigestAuthAlgorithm algo) | ||
3206 | Checks if the provided values in the WWW-Authenticate header are valid | ||
3207 | and sound according to RFC7616. If valid return @code{MHD_DAUTH_OK}, otherwise return the error code. | ||
3208 | |||
3209 | @var{realm} must reference to a zero-terminated string representing the realm. | ||
3210 | |||
3211 | @var{username} must reference to a zero-terminated string representing the username, | ||
3212 | it is usually the returned value from MHD_digest_auth_get_username. | ||
3213 | |||
3214 | @var{password} must reference to a zero-terminated string representing the password, | ||
3215 | most probably it will be the result of a lookup of the username against a local database. | ||
3216 | |||
3217 | @var{nonce_timeout} the nonce validity duration in seconds. | ||
3218 | Most of the time it is sound to specify 300 seconds as its values. | ||
3219 | |||
3220 | @var{algo} which digest algorithm should we use. | ||
3221 | @end deftypefun | ||
3222 | |||
3169 | @deftypefun int MHD_digest_auth_check2 (struct MHD_Connection *connection, const char *realm, const char *username, const char *password, unsigned int nonce_timeout, enum MHD_DigestAuthAlgorithm algo) | 3223 | @deftypefun int MHD_digest_auth_check2 (struct MHD_Connection *connection, const char *realm, const char *username, const char *password, unsigned int nonce_timeout, enum MHD_DigestAuthAlgorithm algo) |
3170 | Checks if the provided values in the WWW-Authenticate header are valid | 3224 | Checks if the provided values in the WWW-Authenticate header are valid |
3171 | and sound according to RFC2716. If valid return @code{MHD_YES}, otherwise return @code{MHD_NO}. | 3225 | and sound according to RFC2716. If valid return @code{MHD_YES}, otherwise return @code{MHD_NO}. |
@@ -3205,6 +3259,25 @@ Most of the time it is sound to specify 300 seconds as its values. | |||
3205 | 3259 | ||
3206 | 3260 | ||
3207 | 3261 | ||
3262 | @deftypefun enum MHD_DigestAuthResult MHD_digest_auth_check_digest3 (struct MHD_Connection *connection, const char *realm, const char *username, const uint8_t *digest, unsigned int nonce_timeout, enum MHD_DigestAuthAlgorithm algo) | ||
3263 | Checks if the provided values in the WWW-Authenticate header are valid | ||
3264 | and sound according to RFC7616. If valid return @code{MHD_DAUTH_OK}, otherwise return the error code. | ||
3265 | |||
3266 | @var{realm} must reference to a zero-terminated string representing the realm. | ||
3267 | |||
3268 | @var{username} must reference to a zero-terminated string representing the username, | ||
3269 | it is usually the returned value from MHD_digest_auth_get_username. | ||
3270 | |||
3271 | @var{digest} the pointer to the binary digest for the precalculated hash value ``username:realm:password'' with specified @var{algo}. | ||
3272 | |||
3273 | @var{digest_size} the number of bytes in @var{digest} (the size must match @var{algo}!) | ||
3274 | |||
3275 | @var{nonce_timeout} the nonce validity duration in seconds. | ||
3276 | Most of the time it is sound to specify 300 seconds as its values. | ||
3277 | |||
3278 | @var{algo} digest authentication algorithm to use. | ||
3279 | @end deftypefun | ||
3280 | |||
3208 | @deftypefun int MHD_digest_auth_check_digest2 (struct MHD_Connection *connection, const char *realm, const char *username, const uint8_t *digest, unsigned int nonce_timeout, enum MHD_DigestAuthAlgorithm algo) | 3281 | @deftypefun int MHD_digest_auth_check_digest2 (struct MHD_Connection *connection, const char *realm, const char *username, const uint8_t *digest, unsigned int nonce_timeout, enum MHD_DigestAuthAlgorithm algo) |
3209 | Checks if the provided values in the WWW-Authenticate header are valid | 3282 | Checks if the provided values in the WWW-Authenticate header are valid |
3210 | and sound according to RFC2716. If valid return @code{MHD_YES}, otherwise return @code{MHD_NO}. | 3283 | and sound according to RFC2716. If valid return @code{MHD_YES}, otherwise return @code{MHD_NO}. |
@@ -3540,9 +3613,9 @@ of this function. | |||
3540 | 3613 | ||
3541 | 3614 | ||
3542 | @menu | 3615 | @menu |
3543 | * microhttpd-info daemon:: State information about an MHD daemon | 3616 | * microhttpd-info daemon:: State information about an MHD daemon |
3544 | * microhttpd-info conn:: State information about a connection | 3617 | * microhttpd-info conn:: State information about a connection |
3545 | * microhttpd-option conn:: Modify per-connection options | 3618 | * microhttpd-option conn:: Modify per-connection options |
3546 | @end menu | 3619 | @end menu |
3547 | 3620 | ||
3548 | 3621 | ||
@@ -3808,8 +3881,8 @@ zero for no timeout. | |||
3808 | 3881 | ||
3809 | 3882 | ||
3810 | @menu | 3883 | @menu |
3811 | * microhttpd-util feature:: Test supported MHD features | 3884 | * microhttpd-util feature:: Test supported MHD features |
3812 | * microhttpd-util unescape:: Unescape strings | 3885 | * microhttpd-util unescape:: Unescape strings |
3813 | @end menu | 3886 | @end menu |
3814 | 3887 | ||
3815 | 3888 | ||