Basic access authentication

Collaboration diagram for Basic access authentication:

Data Structures
struct	_AUTH_BASIC_ENTRY
	Basic authorization entry structure. More...
Typedefs
typedef struct _AUTH_BASIC_ENTRY	AUTH_BASIC_ENTRY
	Basic authorization entry type.
Functions
int	HttpRegisterAuthBasic (const char *path, const char *login, const char *realm)
	Register a basic authorization.
int	HttpAuthBasicValidate (HTTPD_SESSION *hs)
	Validate an authentication for a specified realm.
const AUTH_BASIC_ENTRY *	HttpAuthBasicLookup (const char *realm, const char *login, int best)
	Look up a basic authorization entry.

---

Detailed Description

$Id$

---

Typedef Documentation

typedef struct _AUTH_BASIC_ENTRY AUTH_BASIC_ENTRY

Basic authorization entry type.

---

Function Documentation

int HttpRegisterAuthBasic	(	const char *	path,
		const char *	login,
		const char *	realm
	)

Register a basic authorization.

Protect a specified URL from unauthorized access. Resources, which are not registered by this function are accessible by anyone.

It is allowed to specify several different logins for the same resource.

Alternatively it is possible to unprotect a previously protected resource by passing a NULL pointer instead of a login string.

Usage example:

 #include <pro/uhttp/modules/mod_auth_basic.h>

 if (HttpRegisterAuthBasic("dir", "User:Pass") == 0) {
     puts("Resource is protected.");
     ...
 } else {
     puts("Failed to protect resource.");
     ...
 }

 if (HttpRegisterAuthBasic("dir", NULL) == 0) {
     puts("Resource is unprotected.");
     ...
 } else {
     puts("Failed to remove protection.");
     ...
 }

Parameters:

path	Path to the protected resource.
login	Required login to access the given resource or NULL to remove any previously registered protection for the given resource . To protect a resource, this string must contain a user name, followed by a colon followed by an unencrypted password.
realm	Description of the protected resource. This optional parameter can be a NULL pointer, in which case the path is used instead.

Returns:

0 on success or -1 on error. Trying to add duplicate entries will be silently ignored.

References _AUTH_BASIC_ENTRY::auth_login, _AUTH_BASIC_ENTRY::auth_path, _AUTH_BASIC_ENTRY::auth_realm, calloc, free(), HTTP_ASSERT, HttpAuthBasicValidate(), httpd_auth_validator, ISC_LIST_APPEND, ISC_LIST_HEAD, ISC_LIST_INSERTBEFORE, ISC_LIST_NEXT, ISC_LIST_PREV, ISC_LIST_UNLINK_TYPE, NULL, rc, strcasecmp, strcmp(), and strdup().

Here is the call graph for this function:

int HttpAuthBasicValidate

(

HTTPD_SESSION *

hs

)

Validate an authentication for a specified realm.

If the requested resource had been previously protected by a call to HttpRegisterAuthBasic() and if the client of the specified session hasn't provided a valid authentication, then access is rejected. In the this case the caller should return a 401 response code to the client. This will typically prompt the user to enter a valid user/password pair.

Parameters:

hs	Pointer to a _HTTPD_SESSION structure, which should contain the requested resource and a valid authentication.

Returns:

0 if access is granted, -1 if not.

References _AUTH_BASIC_ENTRY::auth_path, _AUTH_BASIC_ENTRY::auth_realm, HTTP_ASSERT, HttpAuthBasicLookup(), HttpDecodeBase64(), NULL, rc, _HTTP_REQUEST::req_auth, _HTTP_REQUEST::req_realm, _HTTP_REQUEST::req_url, _HTTPD_SESSION::s_req, strdup(), and strncasecmp.

Referenced by HttpRegisterAuthBasic().

Here is the call graph for this function:

const AUTH_BASIC_ENTRY* HttpAuthBasicLookup	(	const char *	realm,
		const char *	login,
		int	best
	)

Look up a basic authorization entry.

This low level routine can be used to retrieve a previously registered authorization entry. Note, that the structure layout of authorization entries may change in future versions.

Usage example:

 #include <pro/uhttp/modules/mod_auth_basic.h>

 if (HttpAuthBasicLookup("/dir/index.html", NULL, 1) == NULL) {
     puts("Resource is unprotected.");
     ...
 } else {
     puts("Resource is protected.");
     ...
 }

 if (HttpAuthBasicLookup("/dir/index.html", "User:Pass", 1)) {
     puts("Access is granted.");
     ...
 } else {
     puts("Access is rejected.");
     ...
 }

Parameters:

realm	Requested resource realm, case insensitive.
login	Requested authentication user and password, separated by a colon. This pointer may be NULL, if the caller only wants to check if the specified resource is protected or not.
best	Set to 1 to find the best matching realm. If 0, then an exact match is requested.

Returns:

Pointer to the AUTH_BASIC_ENTRY structure or NULL if the requested entry doesn't exists.

Referenced by HttpAuthBasicValidate().