GNU libmicrohttpd 1.0.0
Loading...
Searching...
No Matches
Macros | Functions
HTTP authentication

Macros

#define MHD_MD5_DIGEST_SIZE   16
 
#define MHD_SHA256_DIGEST_SIZE   32
 
#define MHD_SHA512_256_DIGEST_SIZE   32
 
#define MHD_INVALID_NONCE   -1
 

Functions

_MHD_EXTERN size_t MHD_digest_get_hash_size (enum MHD_DigestAuthAlgo3 algo3)
 
_MHD_EXTERN enum MHD_Result MHD_digest_auth_calc_userhash (enum MHD_DigestAuthAlgo3 algo3, const char *username, const char *realm, void *userhash_bin, size_t bin_buf_size)
 
_MHD_EXTERN enum MHD_Result MHD_digest_auth_calc_userhash_hex (enum MHD_DigestAuthAlgo3 algo3, const char *username, const char *realm, char *userhash_hex, size_t hex_buf_size)
 
_MHD_EXTERN struct MHD_DigestAuthInfo * MHD_digest_auth_get_request_info3 (struct MHD_Connection *connection)
 
_MHD_EXTERN struct MHD_DigestAuthUsernameInfo * MHD_digest_auth_get_username3 (struct MHD_Connection *connection)
 
_MHD_EXTERN enum MHD_DigestAuthResult MHD_digest_auth_check3 (struct MHD_Connection *connection, const char *realm, const char *username, const char *password, unsigned int nonce_timeout, uint32_t max_nc, enum MHD_DigestAuthMultiQOP mqop, enum MHD_DigestAuthMultiAlgo3 malgo3)
 
_MHD_EXTERN enum MHD_Result MHD_digest_auth_calc_userdigest (enum MHD_DigestAuthAlgo3 algo3, const char *username, const char *realm, const char *password, void *userdigest_bin, size_t bin_buf_size)
 
_MHD_EXTERN enum MHD_DigestAuthResult MHD_digest_auth_check_digest3 (struct MHD_Connection *connection, const char *realm, const char *username, const void *userdigest, size_t userdigest_size, unsigned int nonce_timeout, uint32_t max_nc, enum MHD_DigestAuthMultiQOP mqop, enum MHD_DigestAuthMultiAlgo3 malgo3)
 
_MHD_EXTERN enum MHD_Result MHD_queue_auth_required_response3 (struct MHD_Connection *connection, const char *realm, const char *opaque, const char *domain, struct MHD_Response *response, int signal_stale, enum MHD_DigestAuthMultiQOP mqop, enum MHD_DigestAuthMultiAlgo3 algo, int userhash_support, int prefer_utf8)
 
_MHD_EXTERN char * MHD_digest_auth_get_username (struct MHD_Connection *connection)
 
_MHD_EXTERN 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)
 
_MHD_EXTERN int MHD_digest_auth_check (struct MHD_Connection *connection, const char *realm, const char *username, const char *password, unsigned int nonce_timeout)
 
_MHD_EXTERN int MHD_digest_auth_check_digest2 (struct MHD_Connection *connection, const char *realm, const char *username, const uint8_t *digest, size_t digest_size, unsigned int nonce_timeout, enum MHD_DigestAuthAlgorithm algo)
 
_MHD_EXTERN int MHD_digest_auth_check_digest (struct MHD_Connection *connection, const char *realm, const char *username, const uint8_t digest[MHD_MD5_DIGEST_SIZE], unsigned int nonce_timeout)
 
_MHD_EXTERN enum MHD_Result MHD_queue_auth_fail_response2 (struct MHD_Connection *connection, const char *realm, const char *opaque, struct MHD_Response *response, int signal_stale, enum MHD_DigestAuthAlgorithm algo)
 
_MHD_EXTERN enum MHD_Result MHD_queue_auth_fail_response (struct MHD_Connection *connection, const char *realm, const char *opaque, struct MHD_Response *response, int signal_stale)
 
_MHD_EXTERN struct MHD_BasicAuthInfo * MHD_basic_auth_get_username_password3 (struct MHD_Connection *connection)
 
_MHD_EXTERN enum MHD_Result MHD_queue_basic_auth_required_response3 (struct MHD_Connection *connection, const char *realm, int prefer_utf8, struct MHD_Response *response)
 
_MHD_EXTERN char * MHD_basic_auth_get_username_password (struct MHD_Connection *connection, char **password)
 
_MHD_EXTERN enum MHD_Result MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, const char *realm, struct MHD_Response *response)
 
static enum MHD_DigestAuthResult digest_auth_check_all_inner (struct MHD_Connection *connection, const char *realm, const char *username, const char *password, const uint8_t *userdigest, unsigned int nonce_timeout, uint32_t max_nc, enum MHD_DigestAuthMultiQOP mqop, enum MHD_DigestAuthMultiAlgo3 malgo3, char **pbuf, struct DigestAlgorithm *da)
 
static enum MHD_DigestAuthResult digest_auth_check_all (struct MHD_Connection *connection, const char *realm, const char *username, const char *password, const uint8_t *userdigest, unsigned int nonce_timeout, uint32_t max_nc, enum MHD_DigestAuthMultiQOP mqop, enum MHD_DigestAuthMultiAlgo3 malgo3)
 
static enum MHD_Result queue_auth_required_response3_inner (struct MHD_Connection *connection, const char *realm, const char *opaque, const char *domain, struct MHD_Response *response, int signal_stale, enum MHD_DigestAuthMultiQOP mqop, enum MHD_DigestAuthMultiAlgo3 malgo3, int userhash_support, int prefer_utf8, char **buf_ptr, struct DigestAlgorithm *da)
 

Detailed Description

MHD API related to basic and digest HTTP authentication.

Macro Definition Documentation

◆ MHD_INVALID_NONCE

#define MHD_INVALID_NONCE   -1

Constant to indicate that the nonce of the provided authentication code was wrong. Used as return code by MHD_digest_auth_check(), MHD_digest_auth_check2(), MHD_digest_auth_check_digest(), MHD_digest_auth_check_digest2().

Definition at line 5751 of file microhttpd.h.

Referenced by MHD_digest_auth_check2(), and MHD_digest_auth_check_digest2().

◆ MHD_MD5_DIGEST_SIZE

#define MHD_MD5_DIGEST_SIZE   16

Length of the binary output of the MD5 hash function.

See also
MHD_digest_get_hash_size()

Definition at line 4683 of file microhttpd.h.

Referenced by digest_get_hash_size(), and MHD_digest_auth_check_digest().

◆ MHD_SHA256_DIGEST_SIZE

#define MHD_SHA256_DIGEST_SIZE   32

Length of the binary output of the SHA-256 hash function.

See also
MHD_digest_get_hash_size()

Definition at line 4690 of file microhttpd.h.

Referenced by digest_get_hash_size().

◆ MHD_SHA512_256_DIGEST_SIZE

#define MHD_SHA512_256_DIGEST_SIZE   32

Length of the binary output of the SHA-512/256 hash function.

Warning
While this value is the same as the MHD_SHA256_DIGEST_SIZE, the calculated digests for SHA-256 and SHA-512/256 are different.
See also
MHD_digest_get_hash_size()
Note
Available since MHD_VERSION 0x00097701

Definition at line 4700 of file microhttpd.h.

Referenced by digest_get_hash_size().

Function Documentation

◆ digest_auth_check_all()

static enum MHD_DigestAuthResult digest_auth_check_all ( struct MHD_Connection * connection,
const char * realm,
const char * username,
const char * password,
const uint8_t * userdigest,
unsigned int nonce_timeout,
uint32_t max_nc,
enum MHD_DigestAuthMultiQOP mqop,
enum MHD_DigestAuthMultiAlgo3 malgo3 )
static

Authenticates the authorization header sent by the client

If RFC2069 mode is allowed by setting bit MHD_DIGEST_AUTH_QOP_NONE in mqop and the client uses this mode, then server generated nonces are used as one-time nonces because nonce-count is not supported in this old RFC. Communication in this mode is very inefficient, especially if the client requests several resources one-by-one as for every request new nonce must be generated and client repeat all requests twice (the first time to get a new nonce and the second time to perform an authorised request).

Parameters
connectionthe MHD connection structure
realmthe realm for authorization of the client
usernamethe username to be authenticated, must be in clear text even if userhash is used by the client
passwordthe password used in the authentication, must be NULL if userdigest is not NULL
userdigestthe precalculated binary hash of the string "username:realm:password", must be NULL if password is not NULL
nonce_timeoutthe period of seconds since nonce generation, when the nonce is recognised as valid and not stale; if set to zero then daemon's default value is used
max_ncthe maximum allowed nc (Nonce Count) value, if client's nc exceeds the specified value then MHD_DAUTH_NONCE_STALE is returned; if set to zero then daemon's default value is used
mqopthe QOP to use
malgo3digest algorithms allowed to use, fail if algorithm specified by the client is not allowed by this parameter
Returns
MHD_DAUTH_OK if authenticated, error code otherwise.

Definition at line 3081 of file digestauth.c.

References MHD_Connection::daemon, digest_auth_check_all_inner(), digest_deinit, digest_setup_zero, and NULL.

Referenced by MHD_digest_auth_check3(), and MHD_digest_auth_check_digest3().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ digest_auth_check_all_inner()

static enum MHD_DigestAuthResult digest_auth_check_all_inner ( struct MHD_Connection * connection,
const char * realm,
const char * username,
const char * password,
const uint8_t * userdigest,
unsigned int nonce_timeout,
uint32_t max_nc,
enum MHD_DigestAuthMultiQOP mqop,
enum MHD_DigestAuthMultiAlgo3 malgo3,
char ** pbuf,
struct DigestAlgorithm * da )
static

Authenticates the authorization header sent by the client

If RFC2069 mode is allowed by setting bit MHD_DIGEST_AUTH_QOP_NONE in mqop and the client uses this mode, then server generated nonces are used as one-time nonces because nonce-count is not supported in this old RFC. Communication in this mode is very inefficient, especially if the client requests several resources one-by-one as for every request new nonce must be generated and client repeat all requests twice (the first time to get a new nonce and the second time to perform an authorised request).

Parameters
connectionthe MHD connection structure
realmthe realm for authorization of the client
usernamethe username to be authenticated, must be in clear text even if userhash is used by the client
passwordthe password used in the authentication, must be NULL if userdigest is not NULL
userdigestthe precalculated binary hash of the string "username:realm:password", must be NULL if password is not NULL
nonce_timeoutthe period of seconds since nonce generation, when the nonce is recognised as valid and not stale; unlike digest_auth_check_all() zero is used literally
max_ncthe maximum allowed nc (Nonce Count) value, if client's nc exceeds the specified value then MHD_DAUTH_NONCE_STALE is returned; unlike digest_auth_check_all() zero is treated as "no limit"
mqopthe QOP to use
malgo3digest algorithms allowed to use, fail if algorithm specified by the client is not allowed by this parameter
[out]pbufthe pointer to pointer to internally malloc'ed buffer, to be freed if not NULL upon return
Returns
MHD_DAUTH_OK if authenticated, error code otherwise.

< Client's algorithm

< Client's QOP

Temporal buffer in stack for unquoting and other needs

< Temporal malloc'ed buffer for unquoting

< The size of tmp2 buffer

Definition at line 2534 of file digestauth.c.

References _, _MHD_AUTH_DIGEST_MAX_PARAM_SIZE, _MHD_STATIC_UNQ_BUFFER_SIZE, _MHD_UNQ_OK, MHD_Connection::addr, MHD_Connection::addr_len, calc_userdigest(), calc_userhash(), calculate_nonce(), check_nonce_nc(), check_uri_match(), MHD_Connection::daemon, digest_calc_hash(), digest_ext_error, digest_get_size(), digest_init_one_time(), digest_reset(), digest_update(), digest_update_str(), digest_update_with_colon(), get_base_digest_algo(), get_buffer_for_size(), get_nonce_timestamp(), get_rq_extended_uname_copy_z(), get_unquoted_param(), get_unquoted_param_copy(), MHD_Request::headers_received, MHD_Request::http_mthd, is_param_equal(), is_param_equal_caseless(), _MHD_mstr_w_len::len, _MHD_str_w_len::len, MHD_Request::method, mhd_assert, MHD_bin_to_hex(), MHD_CHECK_NONCENC_OK, MHD_CHECK_NONCENC_STALE, MHD_CHECK_NONCENC_WRONG, MHD_DAUTH_BIND_NONCE_NONE, MHD_DAUTH_ERROR, MHD_DAUTH_EXT_PARAM_MIN_LEN, MHD_DAUTH_NONCE_OTHER_COND, MHD_DAUTH_NONCE_STALE, MHD_DAUTH_NONCE_WRONG, MHD_DAUTH_OK, MHD_DAUTH_RESPONSE_WRONG, MHD_DAUTH_TOO_LARGE, MHD_DAUTH_WRONG_ALGO, MHD_DAUTH_WRONG_HEADER, MHD_DAUTH_WRONG_QOP, MHD_DAUTH_WRONG_REALM, MHD_DAUTH_WRONG_URI, MHD_DAUTH_WRONG_USERNAME, MHD_DIGEST_AUTH_ALGO3_SESSION, MHD_DIGEST_AUTH_QOP_AUTH_INT, MHD_DIGEST_AUTH_QOP_NONE, MHD_DIGEST_BASE_ALGO_MD5, MHD_DIGEST_BASE_ALGO_SHA256, MHD_DIGEST_BASE_ALGO_SHA512_256, MHD_get_master(), MHD_hex_to_bin(), MHD_monotonic_msec_counter(), MHD_PANIC, MHD_strx_to_uint64_n_(), NONCE_STD_LEN, NULL, MHD_Connection::rq, _MHD_mstr_w_len::str, _MHD_str_w_len::str, TRIM_TO_TIMESTAMP, MHD_Request::url, and MHD_Request::url_len.

Referenced by digest_auth_check_all().

Here is the caller graph for this function:

◆ MHD_basic_auth_get_username_password()

_MHD_EXTERN char * MHD_basic_auth_get_username_password ( struct MHD_Connection * connection,
char ** password )

Get the username and password from the basic authorization header sent by the client

Parameters
connectionThe MHD connection structure
[out]passworda pointer for the password, free using MHD_free().
Returns
NULL if no username could be found, a pointer to the username if found, free using MHD_free().

Get the username and password from the basic authorization header sent by the client

Parameters
connectionThe MHD connection structure
[out]passworda pointer for the password, free using MHD_free().
Returns
NULL if no username could be found, a pointer to the username if found, free using MHD_free().

Definition at line 137 of file basicauth.c.

References _, MHD_Connection::daemon, mhd_assert, MHD_basic_auth_get_username_password3(), NULL, MHD_BasicAuthInfo::password, MHD_BasicAuthInfo::password_len, MHD_BasicAuthInfo::username, and MHD_BasicAuthInfo::username_len.

Here is the call graph for this function:

◆ MHD_basic_auth_get_username_password3()

_MHD_EXTERN struct MHD_BasicAuthInfo * MHD_basic_auth_get_username_password3 ( struct MHD_Connection * connection)

Get the username and password from the Basic Authorisation header sent by the client

Parameters
connectionthe MHD connection structure
Returns
NULL if no valid Basic Authentication header is present in current request, or pointer to structure with username and password, which must be freed by MHD_free().
Note
Available since MHD_VERSION 0x00097701

Definition at line 49 of file basicauth.c.

References _, MHD_Connection::daemon, _MHD_str_w_len::len, mhd_assert, NULL, MHD_BasicAuthInfo::password, MHD_BasicAuthInfo::password_len, _MHD_str_w_len::str, MHD_RqBAuth::token68, MHD_BasicAuthInfo::username, and MHD_BasicAuthInfo::username_len.

Referenced by MHD_basic_auth_get_username_password().

Here is the caller graph for this function:

◆ MHD_digest_auth_calc_userdigest()

_MHD_EXTERN enum MHD_Result MHD_digest_auth_calc_userdigest ( enum MHD_DigestAuthAlgo3 algo3,
const char * username,
const char * realm,
const char * password,
void * userdigest_bin,
size_t bin_buf_size )

Calculate userdigest, return it as a binary data.

The "userdigest" is the hash of the "username:realm:password" string.

The "userdigest" can be used to avoid storing the password in clear text in database/files

This function is designed to improve security of stored credentials, the "userdigest" does not improve security of the authentication process.

The results can be used to store username & userdigest pairs instead of username & password pairs. To further improve security, application may store username & userhash & userdigest triplets.

Parameters
algo3the digest algorithm
usernamethe username
realmthe realm
passwordthe password
[out]userdigest_binthe output buffer for userdigest; if this function succeeds, then this buffer has #MHD_digest_get_hash_size(algo3) bytes of userdigest upon return
bin_buf_sizethe size of the userdigest_bin buffer, must be at least #MHD_digest_get_hash_size(algo3) bytes long
Returns
MHD_YES on success, MHD_NO if userdigest_bin is too small or if algo3 algorithm is not supported (or external error has occurred, see MHD_FEATURE_EXTERN_HASH).
See also
MHD_digest_auth_check_digest3()
Note
Available since MHD_VERSION 0x00097701

Definition at line 1937 of file digestauth.c.

References calc_userdigest(), digest_deinit, digest_ext_error, digest_get_size(), digest_init_one_time(), get_base_digest_algo(), MHD_NO, and MHD_YES.

Here is the call graph for this function:

◆ MHD_digest_auth_calc_userhash()

_MHD_EXTERN enum MHD_Result MHD_digest_auth_calc_userhash ( enum MHD_DigestAuthAlgo3 algo3,
const char * username,
const char * realm,
void * userhash_bin,
size_t bin_buf_size )

Calculate "userhash", return it as binary data.

The "userhash" is the hash of the string "username:realm".

The "userhash" could be used to avoid sending username in cleartext in Digest Authorization client's header.

Userhash is not designed to hide the username in local database or files, as username in cleartext is required for MHD_digest_auth_check3() function to check the response, but it can be used to hide username in HTTP headers.

This function could be used when the new username is added to the username database to save the "userhash" alongside with the username (preferably) or when loading list of the usernames to generate the userhash for every loaded username (this will cause delays at the start with the long lists).

Once "userhash" is generated it could be used to identify users by clients with "userhash" support. Avoid repetitive usage of this function for the same username/realm combination as it will cause excessive CPU load; save and re-use the result instead.

Parameters
algo3the algorithm for userhash calculations
usernamethe username
realmthe realm
[out]userhash_binthe output buffer for userhash as binary data; if this function succeeds, then this buffer has #MHD_digest_get_hash_size(algo3) bytes of userhash upon return
bin_buf_sizethe size of the userhash_bin buffer, must be at least #MHD_digest_get_hash_size(algo3) bytes long
Returns
MHD_YES on success, MHD_NO if bin_buf_size is too small or if algo3 algorithm is not supported (or external error has occurred, see MHD_FEATURE_EXTERN_HASH)
See also
MHD_digest_auth_calc_userhash_hex()
Note
Available since MHD_VERSION 0x00097701

Definition at line 2042 of file digestauth.c.

References calc_userhash(), digest_deinit, digest_ext_error, digest_get_size(), digest_init_one_time(), get_base_digest_algo(), MHD_NO, and MHD_YES.

Referenced by MHD_digest_auth_calc_userhash_hex().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ MHD_digest_auth_calc_userhash_hex()

_MHD_EXTERN enum MHD_Result MHD_digest_auth_calc_userhash_hex ( enum MHD_DigestAuthAlgo3 algo3,
const char * username,
const char * realm,
char * userhash_hex,
size_t hex_buf_size )

Calculate "userhash", return it as hexadecimal string.

The "userhash" is the hash of the string "username:realm".

The "userhash" could be used to avoid sending username in cleartext in Digest Authorization client's header.

Userhash is not designed to hide the username in local database or files, as username in cleartext is required for MHD_digest_auth_check3() function to check the response, but it can be used to hide username in HTTP headers.

This function could be used when the new username is added to the username database to save the "userhash" alongside with the username (preferably) or when loading list of the usernames to generate the userhash for every loaded username (this will cause delays at the start with the long lists).

Once "userhash" is generated it could be used to identify users by clients with "userhash" support. Avoid repetitive usage of this function for the same username/realm combination as it will cause excessive CPU load; save and re-use the result instead.

Parameters
algo3the algorithm for userhash calculations
usernamethe username
realmthe realm
[out]userhash_hexthe output buffer for userhash as hex string; if this function succeeds, then this buffer has #MHD_digest_get_hash_size(algo3)*2 chars long userhash zero-terminated string
bin_buf_sizethe size of the userhash_bin buffer, must be at least #MHD_digest_get_hash_size(algo3)*2+1 chars long
Returns
MHD_YES on success, MHD_NO if bin_buf_size is too small or if algo3 algorithm is not supported (or external error has occurred, see MHD_FEATURE_EXTERN_HASH).
See also
MHD_digest_auth_calc_userhash()
Note
Available since MHD_VERSION 0x00097701

Definition at line 2117 of file digestauth.c.

References digest_get_hash_size(), MHD_bin_to_hex_z(), MHD_digest_auth_calc_userhash(), MHD_NO, and MHD_YES.

Here is the call graph for this function:

◆ MHD_digest_auth_check()

_MHD_EXTERN int MHD_digest_auth_check ( struct MHD_Connection * connection,
const char * realm,
const char * username,
const char * password,
unsigned int nonce_timeout )

Authenticates the authorization header sent by the client. Uses MHD_DIGEST_ALG_MD5 (for now, for backwards-compatibility). Note that this MAY change to MHD_DIGEST_ALG_AUTO in the future. If you want to be sure you get MD5, use MHD_digest_auth_check2() and specify MD5 explicitly.

Parameters
connectionThe MHD connection structure
realmThe realm presented to the client
usernameThe username needs to be authenticated
passwordThe password used in the authentication
nonce_timeoutThe amount of time for a nonce to be invalid in seconds
Returns
MHD_YES if authenticated, MHD_NO if not, MHD_INVALID_NONCE if nonce is invalid or stale

Authenticates the authorization header sent by the client. Uses MHD_DIGEST_ALG_MD5 (for now, for backwards-compatibility). Note that this MAY change to MHD_DIGEST_ALG_AUTO in the future. If you want to be sure you get MD5, use MHD_digest_auth_check2() and specify MD5 explicitly.

Parameters
connectionThe MHD connection structure
realmThe realm presented to the client
usernameThe username needs to be authenticated
passwordThe password used in the authentication
nonce_timeoutThe amount of time for a nonce to be invalid in seconds
Returns
MHD_YES if authenticated, MHD_NO if not, MHD_INVALID_NONCE if nonce is invalid or stale

Definition at line 3133 of file digestauth.c.

References MHD_DIGEST_ALG_MD5, and MHD_digest_auth_check2().

Here is the call graph for this function:

◆ MHD_digest_auth_check2()

_MHD_EXTERN 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 )

Authenticates the authorization header sent by the client.

Parameters
connectionThe MHD connection structure
realmThe realm presented to the client
usernameThe username needs to be authenticated
passwordThe password used in the authentication
nonce_timeoutThe amount of time for a nonce to be invalid in seconds
algodigest algorithms allowed for verification
Returns
MHD_YES if authenticated, MHD_NO if not, MHD_INVALID_NONCE if nonce is invalid or stale
Note
Available since