Detailed Description

Please see Authenticating and authorizing users for an introduction to the classes in the Authentication group.

See also: Barracuda Introduction

Classes
struct	AuthorizerIntf
	An abstract class, which you must implement, provides a method of authorizing an authenticated user. More...

struct	UserIntf
	User database interface used by the authentication classes. More...

struct	AuthenticatedUser
	Abstract base class implemented by BasicAuthUser, FormAuthUser and DigestAuthUser. More...

struct	AuthenticatorIntf
	Abstract interface class implemented by DigestAuthenticator, FormAuthenticator and BasicAuthenticator. More...

struct	LoginRespIntf
	The LoginRespIntf is an abstract class, which must be implemented when using one of DigestAuthenticator, BasicAuthenticator, and FormAuthenticator. More...

struct	AuthInfo
	An instance of the AuthInfo struct is created on the stack in the Barracuda authenticators and is used as a container object for sending information to the registered user callback methods. More...

struct	LoginTrackerIntf
	The interface between the LoginTracker and the application code. More...

struct	LoginTrackerNode
	A LoginTrackerNode keeps track of how many times a user using a specific IP address has attempted to login to the server. More...

struct	LoginTracker
	The LoginTracker class is an optional security enhancement that can be installed in an instance of one of the authenticator classes. More...

struct	Authenticator
	Combines HTTP Basic, HTTP Digest, and form-based authentication. More...

struct	BasicAuthenticator
	Implements HTTP Basic authentication. More...

struct	DavAuth
	This class implements HTTP Basic and HTTP Digest authentication. More...

struct	DigestAuthenticator
	Implements HTTP Digest authentication. More...

struct	FormAuthenticator
	Implements browser-oriented form-based authentication. More...

Macros
#define	AuthorizerIntf_constructor(o, authorize) (o)->authorizeFP=authorize
	Install the callback used by AuthorizerIntf. More...

#define	AuthorizerIntf_authorize(o, user, method, path) (o)->authorizeFP(o, user, method, path)
	Returns TRUE if user is authorized. More...

#define	UserIntf_constructor(o, getPwd) (o)->getPwdFp = getPwd
	Install the callback used by UserIntf. More...

#define	UserIntf_getPwd(o, username) (o)->getPwdFp(o, username)
	Invoke UserIntf_GetPwd synchronously. More...

#define	AuthenticatedUser_getName(o)
	Access the authenticated name. More...

#define	AuthenticatedUser_getSession(o) HttpSessionAttribute_getSession((HttpSessionAttribute*)o)
	Get the containing session. More...

#define	AuthenticatedUser_getPassword(o)
	Access the stored credential representation. More...

#define	AuthenticatorIntf_authenticate(o, relPath, cmd) (o)->authenticateCB(o, relPath, cmd)
	Authenticate the user. More...

#define	LoginRespIntf_constructor(o, service) (o)->serviceFp=service
	Install the callback used by LoginRespIntf. More...

#define	AuthInfo_constructor(o, trackerMA, cmdMA, typeMA)
	Initialize an authentication record with zeroed optional fields. More...

#define	LoginTrackerIntf_constructor(o, validateMA, loginMA, loginFailedMA, terminateNodeMA)
	Install required tracker callbacks; no callback may be NULL. More...

#define	LoginTrackerIntf_validate(o, request, node) (o)->validate(o, request, node)
	Invoke the corresponding LoginTrackerIntf callback synchronously. More...

#define	LoginTrackerIntf_login(o, request, user) (o)->login(o, request, user)
	Invoke the corresponding LoginTrackerIntf callback synchronously. More...

#define	LoginTrackerIntf_loginFailed(o, node, loginName) (o)->loginFailed(o, node, loginName)
	Invoke the corresponding LoginTrackerIntf callback synchronously. More...

#define	LoginTrackerIntf_terminateNode(o, node) (o)->terminateNode(o, node)
	Invoke the corresponding LoginTrackerIntf callback synchronously. More...

#define	LoginTrackerNode_getCounter(o) (o)->loginCounter
	Query the address failure/denial counter. More...

#define	LoginTrackerNode_getAuxCounter(o) (o)->auxCounter
	Query the application auxiliary counter. More...

#define	LoginTrackerNode_setAuxCounter(o, count) (o)->auxCounter=count
	Set the application auxiliary counter. More...

#define	LoginTrackerNode_getAddr(o) (&(o)->addr)
	Access the cached peer IP address. More...

#define	LoginTrackerNode_setUserData(o, data) (o)->userData=data
	Associate application data with the node. More...

#define	LoginTrackerNode_getUserData(o) (o)->userData
	Query application data. More...

#define	LoginTrackerNode_getTime(o) (o)->t
	Query the latest recorded failed or denied attempt. More...

#define	Authenticator_setLoginTracker(o, loginTracker)
	C form of Authenticator::setLoginTracker. More...

#define	Authenticator_getBasicAuthenticator(o) (&(o)->basicAuth)
	Access the embedded Basic authenticator. More...

#define	Authenticator_getDigestAuthenticator(o) (&(o)->digestAuth)
	Access the embedded Digest authenticator. More...

#define	Authenticator_getFormAuthenticator(o) (&(o)->formAuth)
	Access the embedded Form authenticator. More...

#define	BasicAuthenticator_setLoginTracker(o, loginTracker) (o)->tracker=loginTracker
	C form of BasicAuthenticator::setLoginTracker. More...

#define	BasicAuthenticator_setFilterMsDomain(o, state) (o)->filterMsDomain=state
	Select user-name domain-prefix filtering (initially FALSE). More...

#define	DavAuth_getBasicAuth(o) (&(o)->basicAuth)
	Access the embedded Basic authenticator. More...

#define	DavAuth_getDigestAuth(o) (&(o)->digestAuth)
	Access the embedded Digest authenticator. More...

#define	DavAuth_setLoginTracker(o, loginTracker)
	C form of DavAuth::setLoginTracker. More...

#define	DigestAuthenticator_setLoginTracker(o, loginTracker) (o)->tracker=loginTracker
	C form of DigestAuthenticator::setLoginTracker. More...

#define	DigestAuthenticator_setFilterMsDomain(o, state) (o)->filterMsDomain=state
	Select user-name domain-prefix filtering (initially FALSE). More...

#define	DigestAuthenticator_setStrictMode(o, enableStrictMode) (o)->strictMode=enableStrictMode
	Control repeated Digest validation for an authenticated session. More...

#define	FormAuthenticator_destructor(o)
	Release authenticator-owned realm storage after detaching all users. More...

#define	FormAuthenticator_setLoginTracker(o, loginTracker) (o)->tracker=loginTracker
	C form of FormAuthenticator::setLoginTracker. More...

#define	FormAuthenticator_setSecure(o) (o)->secure=TRUE
	C form of FormAuthenticator::setSecure. More...

Typedefs
typedef BaBool(*	AuthorizerIntf_Authorize) (struct AuthorizerIntf intf, struct AuthenticatedUser user, HttpMethod httpMethod, const char *path)
	Prototype for the Authorize callback method. More...

typedef struct AuthorizerIntf	AuthorizerIntf
	An abstract class, which you must implement, provides a method of authorizing an authenticated user. More...

typedef void(*	UserIntf_GetPwd) (struct UserIntf intf, struct AuthInfo info)
	User database callback used by authenticators. More...

typedef struct UserIntf	UserIntf
	User database interface used by the authentication classes. More...

typedef struct AuthenticatedUser	AuthenticatedUser
	Abstract base class implemented by BasicAuthUser, FormAuthUser and DigestAuthUser. More...

typedef AuthenticatedUser (	AuthenticatorIntf_Authenticate) (struct AuthenticatorIntf super, const char relPath, HttpCommand *cmd)
	The authenticator callback method for the abstract class AuthenticatorIntf. More...

typedef struct AuthenticatorIntf	AuthenticatorIntf
	Abstract interface class implemented by DigestAuthenticator, FormAuthenticator and BasicAuthenticator. More...

typedef void(*	LoginRespIntf_Service) (struct LoginRespIntf intf, struct AuthInfo info)
	This callback function is called if the user failed to authenticate with one of DigestAuthenticator, BasicAuthenticator, or FormAuthenticator. More...

typedef struct LoginRespIntf	LoginRespIntf
	The LoginRespIntf is an abstract class, which must be implemented when using one of DigestAuthenticator, BasicAuthenticator, and FormAuthenticator. More...

typedef struct AuthInfo	AuthInfo
	An instance of the AuthInfo struct is created on the stack in the Barracuda authenticators and is used as a container object for sending information to the registered user callback methods. More...

typedef BaBool(*	LoginTrackerIntf_Validate) (struct LoginTrackerIntf o, AuthInfo info, struct LoginTrackerNode *node)
	Prototype for the validate callback method. More...

typedef void(*	LoginTrackerIntf_Login) (struct LoginTrackerIntf o, AuthInfo info, struct LoginTrackerNode *node)
	Prototype for the Login tracker method. More...

typedef void(*	LoginTrackerIntf_LoginFailed) (struct LoginTrackerIntf o, AuthInfo info, struct LoginTrackerNode *node)
	Prototype for the LoginFailed callback method. More...

typedef void(*	LoginTrackerIntf_TerminateNode) (struct LoginTrackerIntf o, struct LoginTrackerNode node)
	Prototype for the TerminateNode callback method. More...

typedef struct LoginTrackerIntf	LoginTrackerIntf
	The interface between the LoginTracker and the application code. More...

typedef struct LoginTrackerNode	LoginTrackerNode
	A LoginTrackerNode keeps track of how many times a user using a specific IP address has attempted to login to the server. More...

typedef struct LoginTracker	LoginTracker
	The LoginTracker class is an optional security enhancement that can be installed in an instance of one of the authenticator classes. More...

typedef Authenticator	Authenticator
	Combines HTTP Basic, HTTP Digest, and form-based authentication. More...

typedef BasicAuthenticator	BasicAuthenticator
	Implements HTTP Basic authentication. More...

typedef DavAuth	DavAuth
	This class implements HTTP Basic and HTTP Digest authentication. More...

typedef DigestAuthenticator	DigestAuthenticator
	Implements HTTP Digest authentication. More...

typedef FormAuthenticator	FormAuthenticator
	Implements browser-oriented form-based authentication. More...

Enumerations
enum	AuthenticatedUserType
	The authenticator types. More...

enum	AuthInfoCT { AuthInfoCT_Password =5 , AuthInfoCT_HA1 , AuthInfoCT_Valid , AuthInfoCT_Invalid }
	AuthInfo Credential Type can optionally be used by the UserIntf_GetPwd callback function. More...

Functions
BA_API AuthenticatedUser *	AuthenticatedUser_get1 (HttpRequest *request)
	Find the authenticated user without creating a session. More...

BA_API AuthenticatedUser *	AuthenticatedUser_get2 (HttpSession *session)
	Find the authenticated-user session attribute. More...

BA_API void	AuthenticatedUser_logout (AuthenticatedUser *o, BaBool all)
	Log out and terminate the associated session or sessions. More...

BA_API AuthenticatedUserType	AuthenticatedUser_getType (AuthenticatedUser *o)
	Identify the authenticator that created this user. More...

BA_API AuthenticatedUser *	AuthenticatedUser_getAnonymous (void)
	Access the shared anonymous user. More...

BA_API void	AuthenticatorIntf_constructor (AuthenticatorIntf *o, AuthenticatorIntf_Authenticate authenticate)
	Install the callback used by AuthenticatorIntf. More...

BA_API void	LoginTracker_constructor (LoginTracker o, U32 noOfLoginTrackerNodes, LoginTrackerIntf intf, AllocatorIntf *allocator)
	Allocate a fixed cache of address records. More...

BA_API void	LoginTracker_destructor (LoginTracker *o)
	Release a tracker after detaching all users. More...

BA_API void	LoginTracker_clearCache (LoginTracker *o)
	Remove all active cached addresses. More...

BA_API LoginTrackerNode *	LoginTracker_getFirstNode (LoginTracker *o)
	Start iteration over active cached addresses in insertion order. More...

BA_API LoginTrackerNode *	LoginTracker_getNextNode (LoginTracker o, LoginTrackerNode n)
	Advance through active cached addresses. More...

BA_API LoginTrackerNode *	LoginTracker_find (LoginTracker o, HttpRequest req)
	C form of LoginTracker::find. More...

BA_API void	LoginTracker_loginFailed (LoginTracker o, AuthInfo info)
	Record a failed login, inserting or recycling an address node as needed. More...

BA_API BaBool	LoginTracker_validate (LoginTracker o, AuthInfo info)
	Check whether a cached peer may attempt authentication. More...

BA_API void	LoginTracker_login (LoginTracker o, AuthInfo info)
	Notify successful authentication and remove any cached peer entry. More...

BA_API void	Authenticator_constructor (Authenticator o, UserIntf userDbIntf, const char realm, LoginRespIntf sendLogin)
	C form of Authenticator::Authenticator. More...

BA_API void	Authenticator_destructor (Authenticator *o)
	Release authenticator-owned realm storage after detaching all users. More...

BA_API void	BasicAuthenticator_constructor (BasicAuthenticator o, UserIntf userDbIntf, const char realm, LoginRespIntf sendLogin)
	C form of BasicAuthenticator::BasicAuthenticator. More...

BA_API void	BasicAuthenticator_destructor (BasicAuthenticator *o)
	Release authenticator-owned realm storage after detaching all users. More...

BA_API int	BasicAuthenticator_setAutHeader (const char realm, HttpResponse resp)
	C form of BasicAuthenticator::setAutHeader. More...

BA_API void	DavAuth_constructor (DavAuth o, UserIntf userDbIntf, const char *realm)
	C form of DavAuth::DavAuth. More...

BA_API void	DavAuth_destructor (DavAuth *o)
	Release authenticator-owned realm storage after detaching all users. More...

BA_API void	DigestAuthenticator_constructor (DigestAuthenticator o, UserIntf userDbIntf, const char realm, LoginRespIntf sendLogin)
	C form of DigestAuthenticator::DigestAuthenticator. More...

BA_API void	DigestAuthenticator_destructor (DigestAuthenticator *o)
	Release authenticator-owned realm storage after detaching all users. More...

BA_API int	DigestAuthenticator_setAutHeader (const char , HttpResponse )
	C form of DigestAuthenticator::setAutHeader. More...

BA_API void	FormAuthenticator_constructor (FormAuthenticator o, UserIntf userDbIntf, const char realm, LoginRespIntf login)
	C form of FormAuthenticator::FormAuthenticator. More...

	AuthorizerIntf::AuthorizerIntf (AuthorizerIntf_Authorize authorize)
	The constructor. More...

bool	AuthorizerIntf::authorize (struct AuthenticatedUser user, HttpMethod method, const char path)
	Returns TRUE if user is authorized. More...

	UserIntf::UserIntf (UserIntf_GetPwd getPwd)
	The UserIntf constructor. More...

static AuthenticatedUser *	AuthenticatedUser::get (HttpRequest *request)
	Find the authenticated user without creating a session. More...

static AuthenticatedUser *	AuthenticatedUser::get (HttpSession *session)
	Find the authenticated-user session attribute. More...

const char *	AuthenticatedUser::getName ()
	Access the authenticated name. More...

HttpSession *	AuthenticatedUser::getSession ()
	Get the containing session. More...

const char *	AuthenticatedUser::getPassword ()
	Access the stored credential representation. More...

void	AuthenticatedUser::logout (bool all=false)
	Log out and terminate the associated session or sessions. More...

AuthenticatedUserType	AuthenticatedUser::getType ()
	Identify the authenticator that created this user. More...

static AuthenticatedUser *	AuthenticatedUser::getAnonymous ()
	Access the shared anonymous user. More...

	AuthenticatorIntf::AuthenticatorIntf (AuthenticatorIntf_Authenticate authenticate)
	Install an authentication callback. More...

AuthenticatedUser *	AuthenticatorIntf::authenticate (const char relPath, HttpCommand cmd)
	Authenticate the user. More...

	LoginRespIntf::LoginRespIntf (LoginRespIntf_Service service)
	Install the required login-response callback. More...

	LoginTrackerIntf::LoginTrackerIntf (LoginTrackerIntf_Validate validate, LoginTrackerIntf_Login login, LoginTrackerIntf_LoginFailed loginFailed, LoginTrackerIntf_TerminateNode terminateNode)
	Install four required callbacks; none may be NULL. More...

U32	LoginTrackerNode::getCounter ()
	Query the address failure/denial counter. More...

U32	LoginTrackerNode::getAuxCounter ()
	Query the application auxiliary counter. More...

void	LoginTrackerNode::setAuxCounter (U32 count)
	Set the application auxiliary counter. More...

HttpSockaddr *	LoginTrackerNode::getAddr ()
	Access the cached peer IP address. More...

void	LoginTrackerNode::setUserData (void *data)
	Associate application data with the node. More...

void *	LoginTrackerNode::getUserData ()
	Query application data. More...

BaTime	LoginTrackerNode::getTime ()
	Query the latest recorded failed or denied attempt. More...

	LoginTracker::LoginTracker (U32 noOfLoginTrackerNodes, LoginTrackerIntf intf, AllocatorIntf allocator=AllocatorIntf::getDefault())
	Allocate a fixed cache of address records. More...

void	LoginTracker::clearCache ()
	Remove all active cached addresses. More...

LoginTrackerNode *	LoginTracker::getFirstNode ()
	Start iteration over active cached addresses in insertion order. More...

LoginTrackerNode *	LoginTracker::getNextNode (LoginTrackerNode *n)
	Advance through active cached addresses. More...

LoginTrackerNode *	LoginTracker::find (HttpRequest *request)
	Find a cached address using the current connection's peer IP. More...

	Authenticator::Authenticator (UserIntf userDbIntf, const char realm, LoginRespIntf *sendLogin)
	Construct an authenticator using application-provided user lookup. More...

void	Authenticator::setLoginTracker (LoginTracker *tracker)
	Configure login-attempt tracking. More...

BasicAuthenticator *	Authenticator::getBasicAuthenticator ()
	Access the embedded Basic authenticator. More...

DigestAuthenticator *	Authenticator::getDigestAuthenticator ()
	Access the embedded Digest authenticator. More...

FormAuthenticator *	Authenticator::getFormAuthenticator ()
	Access the embedded Form authenticator. More...

	BasicAuthenticator::BasicAuthenticator (UserIntf userDbIntf, const char realm, LoginRespIntf *sendLogin)
	Construct an authenticator using application-provided user lookup. More...

void	BasicAuthenticator::setLoginTracker (LoginTracker *tracker)
	Configure login-attempt tracking. More...

static int	BasicAuthenticator::setAutHeader (const char realm, HttpResponse response)
	Sets an HTTP Basic authentication challenge and status code. More...

	DavAuth::DavAuth (UserIntf userDbIntf, const char realm)
	Construct an authenticator using application-provided user lookup. More...

BasicAuthenticator *	DavAuth::getBasicAuth ()
	Access the embedded Basic authenticator. More...

DigestAuthenticator *	DavAuth::getDigestAuth ()
	Access the embedded Digest authenticator. More...

void	DavAuth::setLoginTracker (LoginTracker *tracker)
	Configure login-attempt tracking. More...

	DigestAuthenticator::DigestAuthenticator (UserIntf userDbIntf, const char realm, LoginRespIntf *sendLogin)
	Construct an authenticator using application-provided user lookup. More...

void	DigestAuthenticator::setLoginTracker (LoginTracker *tracker)
	Configure login-attempt tracking. More...

static int	DigestAuthenticator::setAutHeader (const char realm, HttpResponse response)
	Sets an HTTP Digest authentication challenge and status code. More...

void	DigestAuthenticator::setStrictMode (bool enableStrictMode=false)
	Control repeated Digest validation for an authenticated session. More...

	FormAuthenticator::FormAuthenticator (UserIntf userDbIntf, const char realm, LoginRespIntf *sendLogin)
	Construct an authenticator using application-provided user lookup. More...

void	FormAuthenticator::setLoginTracker (LoginTracker *tracker)
	Configure login-attempt tracking. More...

void	FormAuthenticator::setSecure ()
	Set the authenticator into secure mode and accept only SSL/TLS connections. More...

Macro Definition Documentation

◆ AuthenticatedUser_getName

#define AuthenticatedUser_getName ( o )

Value:

((o) && (o)->authUserList && (o)->authUserList->username ? \

(o)->authUserList->username : 0)

Access the authenticated name.

Returns: Borrowed NUL-terminated user name, or NULL if unavailable. It remains valid only while the associated authentication record remains alive.

Parameters

o	User pointer, or NULL to return NULL.

◆ AuthenticatedUser_getPassword

#define AuthenticatedUser_getPassword ( o )

Value:

((o) && (o)->authUserList && (o)->authUserList->password ? \

(o)->authUserList->password : 0)

Access the stored credential representation.

Returns: Borrowed NUL-terminated password/hash, or NULL if unavailable. Basic and Form callback-validated credentials can be represented by the placeholder "?" rather than the original password. Copy before logout/session destruction.

Parameters

o	User pointer, or NULL to return NULL.

◆ AuthenticatedUser_getSession

#define AuthenticatedUser_getSession ( o ) HttpSessionAttribute_getSession((HttpSessionAttribute*)o)

Get the containing session.

Returns: Borrowed session pointer, or NULL if not attached. Do not terminate it directly to log out a user; use logout().

Parameters

o	Required user.

◆ Authenticator_getBasicAuthenticator

#define Authenticator_getBasicAuthenticator ( o ) (&(o)->basicAuth)

Access the embedded Basic authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

Parameters

o	Required initialized parent authenticator.

◆ Authenticator_getDigestAuthenticator

#define Authenticator_getDigestAuthenticator ( o ) (&(o)->digestAuth)

Access the embedded Digest authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

Parameters

o	Required initialized parent authenticator.

◆ Authenticator_getFormAuthenticator

#define Authenticator_getFormAuthenticator ( o ) (&(o)->formAuth)

Access the embedded Form authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

Parameters

o	Required initialized parent authenticator.

◆ Authenticator_setLoginTracker

#define Authenticator_setLoginTracker	(	o,
		loginTracker
	)

Value:

   BasicAuthenticator_setLoginTracker(&(o)->basicAuth, loginTracker),\
   DigestAuthenticator_setLoginTracker(&(o)->digestAuth, loginTracker),\
   FormAuthenticator_setLoginTracker(&(o)->formAuth, loginTracker)

C form of Authenticator::setLoginTracker.

Parameters

o	Required initialized authenticator.
loginTracker	Borrowed tracker, or NULL to disable.

◆ AuthenticatorIntf_authenticate

#define AuthenticatorIntf_authenticate	(	o,
		relPath,
		cmd
	)	(o)->authenticateCB(o, relPath, cmd)

Authenticate the user.

Parameters

relPath	Borrowed NUL-terminated relative resource path.
cmd	Required current request/response container.

Returns: The AuthenticatedUser if authenticated, otherwise NULL is returned.

Parameters

o	Required initialized interface.

◆ AuthInfo_constructor

#define AuthInfo_constructor	(	o,
		trackerMA,
		cmdMA,
		typeMA
	)

Value:

   do {\
   memset(o, 0, sizeof(AuthInfo));\
   (o)->tracker=trackerMA;\
   (o)->cmd=cmdMA;\
   (o)->type=typeMA;\
   (o)->maxUsers=3;\
   (o)->ct=AuthInfoCT_Password;\
   (o)->password[0]=0;\
} while(0)

Initialize an authentication record with zeroed optional fields.

Parameters

o	Required writable record.
trackerMA	Borrowed tracker, or NULL.
cmdMA	Borrowed command, or NULL for lookup without a request.
typeMA	AuthenticatedUserType describing the lookup. Sets maxUsers=3 and ct=AuthInfoCT_Password; stores no owned pointers.

◆ AuthorizerIntf_authorize

#define AuthorizerIntf_authorize	(	o,
		user,
		method,
		path
	)	(o)->authorizeFP(o, user, method, path)

Returns TRUE if user is authorized.

Parameters

user	AuthenticatedUser::get
method	The HTTP method type: From HttpRequest::getMethodType
path	The relative path element of the URL requested by the user.
o	Required initialized interface.

◆ AuthorizerIntf_constructor

#define AuthorizerIntf_constructor	(	o,
		authorize
	)	(o)->authorizeFP=authorize

Install the callback used by AuthorizerIntf.

Parameters

authorize	Required callback; remains callable while installed.
o	Required storage to initialize.

◆ BasicAuthenticator_setFilterMsDomain

#define BasicAuthenticator_setFilterMsDomain	(	o,
		state
	)	(o)->filterMsDomain=state

Select user-name domain-prefix filtering (initially FALSE).

Parameters

o	Required initialized authenticator.
state	TRUE removes the prefix through the first backslash before user lookup; FALSE uses the complete supplied user name.

◆ BasicAuthenticator_setLoginTracker

#define BasicAuthenticator_setLoginTracker	(	o,
		loginTracker
	)	(o)->tracker=loginTracker

C form of BasicAuthenticator::setLoginTracker.

Parameters

o	Required initialized authenticator.
loginTracker	Borrowed tracker, or NULL to disable.

◆ DavAuth_getBasicAuth

#define DavAuth_getBasicAuth ( o ) (&(o)->basicAuth)

Access the embedded Basic authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

Parameters

o	Required initialized parent authenticator.

◆ DavAuth_getDigestAuth

#define DavAuth_getDigestAuth ( o ) (&(o)->digestAuth)

Access the embedded Digest authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

Parameters

o	Required initialized parent authenticator.

◆ DavAuth_setLoginTracker

#define DavAuth_setLoginTracker	(	o,
		loginTracker
	)

Value:

   do{\
   BasicAuthenticator_setLoginTracker(&(o)->basicAuth, loginTracker);\
   DigestAuthenticator_setLoginTracker(&(o)->digestAuth, loginTracker);\
   }while(0)

C form of DavAuth::setLoginTracker.

Parameters

o	Required initialized authenticator.
loginTracker	Borrowed tracker, or NULL to disable.

◆ DigestAuthenticator_setFilterMsDomain

#define DigestAuthenticator_setFilterMsDomain	(	o,
		state
	)	(o)->filterMsDomain=state

Select user-name domain-prefix filtering (initially FALSE).

Parameters

o	Required initialized authenticator.
state	TRUE removes the prefix through the first backslash before user lookup; FALSE uses the complete supplied user name.

◆ DigestAuthenticator_setLoginTracker

#define DigestAuthenticator_setLoginTracker	(	o,
		loginTracker
	)	(o)->tracker=loginTracker

C form of DigestAuthenticator::setLoginTracker.

Parameters

o	Required initialized authenticator.
loginTracker	Borrowed tracker, or NULL to disable.

◆ DigestAuthenticator_setStrictMode

#define DigestAuthenticator_setStrictMode	(	o,
		enableStrictMode
	)	(o)->strictMode=enableStrictMode

Control repeated Digest validation for an authenticated session.

Parameters

enableStrictMode True validates subsequent matching Digest headers; false (the initial state and C++ default argument) accepts the authenticated session without repeating that validation. With strict mode enabled, a missing header for a Digest session produces a new challenge. Other authentication types and headers for a different realm bypass this check. This setting is not a general claim of complete RFC conformance.

o Required initialized authenticator.

◆ FormAuthenticator_destructor

#define FormAuthenticator_destructor ( o )

Value:

      do { \
      if((o)->realm)                            \
         baFree((o)->realm);                    \
      (o)->realm=0;                             \
   } while(0)

Release authenticator-owned realm storage after detaching all users.

Parameters

o	Required initialized authenticator. Borrowed dependencies are not freed.

◆ FormAuthenticator_setLoginTracker

#define FormAuthenticator_setLoginTracker	(	o,
		loginTracker
	)	(o)->tracker=loginTracker

C form of FormAuthenticator::setLoginTracker.

Parameters

o	Required initialized authenticator.
loginTracker	Borrowed tracker, or NULL to disable.

◆ FormAuthenticator_setSecure

#define FormAuthenticator_setSecure ( o ) (o)->secure=TRUE

C form of FormAuthenticator::setSecure.

Parameters

o	Required initialized authenticator. The flag is initially FALSE; this setter enables it permanently for the lifetime of this initialization.

◆ LoginRespIntf_constructor

#define LoginRespIntf_constructor	(	o,
		service
	)	(o)->serviceFp=service

Install the callback used by LoginRespIntf.

Parameters

service	Required callback; remains callable while installed.
o	Required storage to initialize.

◆ LoginTrackerIntf_constructor

#define LoginTrackerIntf_constructor	(	o,
		validateMA,
		loginMA,
		loginFailedMA,
		terminateNodeMA
	)

Value:

   do {\
   (o)->validate=validateMA;\
   (o)->login=loginMA;\
   (o)->loginFailed=loginFailedMA;\
   (o)->terminateNode=terminateNodeMA;\
} while(0)

Install required tracker callbacks; no callback may be NULL.

Parameters

o	Required interface storage.
validateMA	LoginTrackerIntf_Validate callback.
loginMA	LoginTrackerIntf_Login callback.
loginFailedMA	LoginTrackerIntf_LoginFailed callback.
terminateNodeMA	LoginTrackerIntf_TerminateNode callback.

◆ LoginTrackerIntf_login

#define LoginTrackerIntf_login	(	o,
		request,
		user
	)	(o)->login(o, request, user)

Invoke the corresponding LoginTrackerIntf callback synchronously.

Parameters

o	Required initialized callback interface.
request	Required AuthInfo pointer.
user	Borrowed LoginTrackerNode pointer, or NULL, despite the argument name.

◆ LoginTrackerIntf_loginFailed

#define LoginTrackerIntf_loginFailed	(	o,
		node,
		loginName
	)	(o)->loginFailed(o, node, loginName)

Invoke the corresponding LoginTrackerIntf callback synchronously.

Parameters

o	Required initialized callback interface.
node	Required AuthInfo pointer, despite the argument name.
loginName	Required LoginTrackerNode pointer, not a string.

◆ LoginTrackerIntf_terminateNode

#define LoginTrackerIntf_terminateNode	(	o,
		node
	)	(o)->terminateNode(o, node)

Invoke the corresponding LoginTrackerIntf callback synchronously.

Parameters

o	Required initialized callback interface.
node	Required node whose application data must be released.

◆ LoginTrackerIntf_validate

#define LoginTrackerIntf_validate	(	o,
		request,
		node
	)	(o)->validate(o, request, node)

Invoke the corresponding LoginTrackerIntf callback synchronously.

Parameters

o	Required initialized callback interface.
request	Required AuthInfo pointer (not HttpRequest).
node	Required cached LoginTrackerNode.

Returns: Callback result: TRUE permits, FALSE denies.

◆ LoginTrackerNode_getAddr

#define LoginTrackerNode_getAddr ( o ) (&(o)->addr)

Access the cached peer IP address.

Returns: Borrowed pointer valid while this node remains cached. Do not modify the address used as the tree key.

Parameters

o	Required live tracker node.

◆ LoginTrackerNode_getAuxCounter

#define LoginTrackerNode_getAuxCounter ( o ) (o)->auxCounter

Query the application auxiliary counter.

Returns: Last stored U32 value, initially zero for a new node.

Parameters

o	Required live tracker node.

◆ LoginTrackerNode_getCounter

#define LoginTrackerNode_getCounter ( o ) (o)->loginCounter

Query the address failure/denial counter.

Returns: U32 count maintained by the tracker, initially zero for a new node.

Parameters

o	Required live tracker node.

◆ LoginTrackerNode_getTime

#define LoginTrackerNode_getTime ( o ) (o)->t

Query the latest recorded failed or denied attempt.

Returns: Unix time in seconds, as provided by baGetUnixTime().

Parameters

o	Required live tracker node.

◆ LoginTrackerNode_getUserData

#define LoginTrackerNode_getUserData ( o ) (o)->userData

Query application data.

Returns: Last stored pointer, initially NULL; ownership remains with the application.

Parameters

o	Required live tracker node.

◆ LoginTrackerNode_setAuxCounter

#define LoginTrackerNode_setAuxCounter	(	o,
		count
	)	(o)->auxCounter=count

Set the application auxiliary counter.

Parameters

count	U32 value, used as the baseline subtracted from loginCounter when populating denied-attempt information.
o	Required live tracker node.

◆ LoginTrackerNode_setUserData

#define LoginTrackerNode_setUserData	(	o,
		data
	)	(o)->userData=data

Associate application data with the node.

Parameters

data	Borrowed application pointer, or NULL. Replacing it does not free the old value. Release owned data through the terminateNode callback.
o	Required live tracker node.

◆ UserIntf_constructor

#define UserIntf_constructor	(	o,
		getPwd
	)	(o)->getPwdFp = getPwd

Install the callback used by UserIntf.

Parameters

getPwd	Required callback; remains callable while installed.
o	Required storage to initialize.

◆ UserIntf_getPwd

#define UserIntf_getPwd	(	o,
		username
	)	(o)->getPwdFp(o, username)

Invoke UserIntf_GetPwd synchronously.

Parameters

o	Required initialized interface.
username	Required AuthInfo pointer, despite this historical macro argument name; it is not a string.

Typedef Documentation

◆ AuthenticatedUser

typedef struct AuthenticatedUser AuthenticatedUser

Abstract base class implemented by BasicAuthUser, FormAuthUser and DigestAuthUser.

Please see the User Authentication documentation for more information.

◆ Authenticator

typedef Authenticator Authenticator

Combines HTTP Basic, HTTP Digest, and form-based authentication.

Authenticator lets the client select between the built-in authentication mechanisms and shares the same user database and login response interface between them.

The Authentication class, which implements all authentication methods in the server, is very useful in a mixed client environment. A limitation with Basic and Digest authentication is that the pop-up window presented by the browser is not user friendly. Consequently, it is common to use a customizable HTML user interface for login. A non-browser client such as a C program, a Java program, or a Python script will usually not be able to display a HTML based login user interface. For this reason, it is recommended to use Basic or Digest authentication for non-browser clients.

The Authentication class makes it possible for the client to decide on the authentication method used. The default authentication is a "form login" and will automatically be used by a HTML browser interface.

A non-HTML client can force the authentication to be one of Basic or Digest by explicitly setting the "Authorization" HTTP header. An instance of the Authentication class analyzes the "Authorization" HTTP header and forwards the request to one of Basic, Digest, or form based login classes. A non-authenticated user requesting a resource without an "Authorization" header is forwarded to the form login class.

It is very simple to use the Authentication class if you use a client HTTP library that automatically handles Digest and/or Basic authentication. You simply set the header to one of Basic or Digest and leave the implementation details to the client HTTP library.

Forcing the login to be Basic or Digest from a client using a client HTTP library:

setHttpHeader("PrefAuth", "Basic"); /* force basic authentication */
setHttpHeader("PrefAuth", "Digest"); /* force digest authentication */

Other uses for the Authentication class include use of Digest authentication for clients that can properly handle Digest authentication and use of Basic authentication for clients that cannot properly handle or do not implement Digest authentication.

◆ AuthenticatorIntf

typedef struct AuthenticatorIntf AuthenticatorIntf

Abstract interface class implemented by DigestAuthenticator, FormAuthenticator and BasicAuthenticator.

◆ AuthenticatorIntf_Authenticate

typedef AuthenticatedUser *(* AuthenticatorIntf_Authenticate) (struct AuthenticatorIntf *super, const char *relPath, HttpCommand *cmd)

The authenticator callback method for the abstract class AuthenticatorIntf.

Parameters

super	a pointer to the super class.
relPath	the URL's relative path
cmd	The HttpRequest HttpResponse container.

Returns: The AuthenticatedUser if authenticated, otherwise NULL is returned.

◆ AuthInfo

typedef struct AuthInfo AuthInfo

An instance of the AuthInfo struct is created on the stack in the Barracuda authenticators and is used as a container object for sending information to the registered user callback methods.

◆ AuthorizerIntf

typedef struct AuthorizerIntf AuthorizerIntf

An abstract class, which you must implement, provides a method of authorizing an authenticated user.

◆ AuthorizerIntf_Authorize

typedef BaBool(* AuthorizerIntf_Authorize) (struct AuthorizerIntf *intf, struct AuthenticatedUser *user, HttpMethod httpMethod, const char *path)

Prototype for the Authorize callback method.

Parameters

intf	The object pointer, which you must upcast to your class implementation; i.e., MySecurityRealm* o = (MySecurityRealm*)intf;
user	A reference to the authenticated user. The method must return false if user is NULL.
httpMethod	The HTTP method type: From HttpRequest::getMethodType
path	Borrowed NUL-terminated relative resource path for this call.

Returns: TRUE to permit access, FALSE to deny. No ownership is transferred.

◆ BasicAuthenticator

typedef BasicAuthenticator BasicAuthenticator

Implements HTTP Basic authentication.

Please see the User Authentication documentation for more information.

◆ DavAuth

typedef DavAuth DavAuth

This class implements HTTP Basic and HTTP Digest authentication.

The client selects the HTTP authentication method it wants to use. The authenticator also handles the domain name prefix added to the user name by many Microsoft HTTP clients.

This class was specifically designed for our WebDAV plugin, but the authenticator is also useful when authenticating non-browser clients in a mixed environment.

◆ DigestAuthenticator

typedef DigestAuthenticator DigestAuthenticator

Implements HTTP Digest authentication.

Please see the User Authentication documentation for more information.

◆ FormAuthenticator

typedef FormAuthenticator FormAuthenticator

Implements browser-oriented form-based authentication.

See the User Authentication documentation for an introduction to authentication and authorization. A form authenticator can be used only by browser clients.

See also: Authenticator

◆ LoginRespIntf

typedef struct LoginRespIntf LoginRespIntf

The LoginRespIntf is an abstract class, which must be implemented when using one of DigestAuthenticator, BasicAuthenticator, and FormAuthenticator.

The Barracuda authenticators call the service method if the user is not authenticated or failed to login. The service method must respond by sending a message to the client.

◆ LoginRespIntf_Service

typedef void(* LoginRespIntf_Service) (struct LoginRespIntf *intf, struct AuthInfo *info)

This callback function is called if the user failed to authenticate with one of DigestAuthenticator, BasicAuthenticator, or FormAuthenticator.

The service function must send an appropriate error message to the client.

The callback is also called when a FormAuthenticator instance needs to send the form login page to the client. This callback can detect the difference between sending the login page and the error page by checking info->username. This variable is NULL when the callback must send the login page.

Parameters

intf	Required application login-response interface.
info	Required borrowed authentication record for this call. Built-in authenticator calls provide cmd for sending the response. The callback has no return value; it communicates by writing the response.

◆ LoginTracker

typedef struct LoginTracker LoginTracker

The LoginTracker class is an optional security enhancement that can be installed in an instance of one of the authenticator classes.

The tracker caches failed attempts by peer IP address and delegates the decision to allow another attempt to application callbacks. It does not provide a built-in retry policy. A full cache reuses its oldest inserted active node. Serialize access with the server mutex and keep callbacks/dependencies alive.

◆ LoginTrackerIntf

typedef struct LoginTrackerIntf LoginTrackerIntf

The interface between the LoginTracker and the application code.

You must inherit and implement the callback methods required for the LoginTrackerIntf.

◆ LoginTrackerIntf_Login

typedef void(* LoginTrackerIntf_Login) (struct LoginTrackerIntf *o, AuthInfo *info, struct LoginTrackerNode *node)

Prototype for the Login tracker method.

The Login method is called when a user is authenticated.

Parameters

o	the object
info	The AuthInfo container object.
node	is borrowed and may be NULL if the address is not cached. This object is automatically terminated as soon as this callback returns; i.e., the terminate callback is called.

◆ LoginTrackerIntf_LoginFailed

typedef void(* LoginTrackerIntf_LoginFailed) (struct LoginTrackerIntf *o, AuthInfo *info, struct LoginTrackerNode *node)

Prototype for the LoginFailed callback method.

The LoginFailed method is called when a user attempts to log in and the user name, password, or both are incorrect.

One can potentially tarpit the failed login attempt if you run the HTTP server in threaded mode, but a short "login window" is probably more than sufficient in most applications. The "login window" length is controlled in the LoginTrackerIntf_Validate callback method.

@param o Required callback interface.
@param info Required borrowed authentication record.
@param node Required cached node after its counter and time are updated.
The callback returns no value and does not own the node.

◆ LoginTrackerIntf_TerminateNode

typedef void(* LoginTrackerIntf_TerminateNode) (struct LoginTrackerIntf *o, struct LoginTrackerNode *node)

Prototype for the TerminateNode callback method.

The TerminateNode method is called when the LoginTracker reuses a node in the internal node cache. The TerminateNode method can be used for clearing/releasing any data set with method LoginTrackerNode::setUserData.

@param o Required callback interface.
@param node Required node about to leave the cache or be reused. Release any
application-owned userData here, but do not free the tracker-owned node.
Also called by clearCache() and the tracker destructor.

◆ LoginTrackerIntf_Validate

typedef BaBool(* LoginTrackerIntf_Validate) (struct LoginTrackerIntf *o, AuthInfo *info, struct LoginTrackerNode *node)

Prototype for the validate callback method.

The validate callback method is called before attempting to authorize a user. The validate callback method can keep track of the login counter in the LoginTrackerNode and either accepts or denies the user. The method should return true if the request is accepted and false if the request is denied. Attribute info.denied is set by the LoginTracker if this method returns false.

@param o Required callback interface.
@param info Required borrowed authentication input/output record.
@param node Required cached address node, borrowed for this call.
@return TRUE to permit the attempt, FALSE to deny it. This callback is called
only for an address already present in the cache.

◆ LoginTrackerNode

typedef struct LoginTrackerNode LoginTrackerNode

A LoginTrackerNode keeps track of how many times a user using a specific IP address has attempted to login to the server.

The LoginTracker stores LoginTrackerNodes internally in a cache.

◆ UserIntf

typedef struct UserIntf UserIntf

User database interface used by the authentication classes.

The getPwd function populates AuthInfo with password data when a matching user is found.

◆ UserIntf_GetPwd

typedef void(* UserIntf_GetPwd) (struct UserIntf *intf, struct AuthInfo *info)

User database callback used by authenticators.

The callback searches for info->username and sets AuthInfo::password, AuthInfo::ct, or both if the user is found.

info->userObj is NULL, but can be set in this callback to signal information to the other callbacks such as LoginRespIntf_Service.

info->user is NULL when this method is called.

The callback is allowed to set header values and work with the response object. The authenticator stops authentication and returns FALSE if the response object is committed; i.e., the login fails.

The authenticator checks if the response is committed on return. The authenticator assumes the user is not authenticated if the response is committed.

Parameters

intf	Required application interface receiving this call.
info	Required input/output authentication record. Read username/type/upwd and fill password/ct and optional policy fields. All pointers are borrowed for this synchronous call; do not retain the stack record.

Note: A direct database lookup can supply NULL cmd and tracker and type Unknown. Test cmd before using request/response APIs. Basic and Form permit ct=Valid after a callback comparison; Digest requires password or HA1 data.

Enumeration Type Documentation

◆ AuthenticatedUserType

enum AuthenticatedUserType

The authenticator types.

◆ AuthInfoCT

enum AuthInfoCT

AuthInfo Credential Type can optionally be used by the UserIntf_GetPwd callback function.

Enumerator
AuthInfoCT_Password	The default. Password is returned in plaintext.
AuthInfoCT_HA1	The password is returned as a HA1 hash, which is: MD5(username ":" realm ":" password)
AuthInfoCT_Valid	Set when getpwd callback successfully compared AuthInfo::upwd with stored password.
AuthInfoCT_Invalid	Set when getpwd callback failed comparing AuthInfo::upwd with stored password.

Function Documentation

◆ authenticate()

AuthenticatedUser * AuthenticatorIntf::authenticate	(	const char *	relPath,
		HttpCommand *	cmd
	)

Authenticate the user.

Parameters

relPath	Borrowed NUL-terminated relative resource path.
cmd	Required current request/response container.

Returns: The AuthenticatedUser if authenticated, otherwise NULL is returned.

◆ AuthenticatedUser_get1()

BA_API AuthenticatedUser * AuthenticatedUser_get1 ( HttpRequest * request )

Find the authenticated user without creating a session.

Parameters

request Required current request.

Returns: Borrowed user owned by the existing session, or NULL if unavailable. Do not free it or retain it beyond logout/session destruction. C equivalent: AuthenticatedUser_get1().

◆ AuthenticatedUser_get2()

BA_API AuthenticatedUser * AuthenticatedUser_get2 ( HttpSession * session )

Find the authenticated-user session attribute.

Parameters

session Existing session, or NULL.

Returns: Borrowed authenticated user, or NULL when no such attribute exists. C equivalent: AuthenticatedUser_get2().

◆ AuthenticatedUser_getAnonymous()

BA_API AuthenticatedUser * AuthenticatedUser_getAnonymous ( void )

Access the shared anonymous user.

Returns: Non-NULL borrowed static object named "anonymous", with type Unknown. It is not a session login. Do not log it out, destroy, free, or modify it.

◆ AuthenticatedUser_getType()

BA_API AuthenticatedUserType AuthenticatedUser_getType ( AuthenticatedUser * o )

Identify the authenticator that created this user.

Returns: Basic, Digest, Form, or Unknown from AuthenticatedUserType. Unknown includes the shared anonymous object and unrecognized derived types.

Parameters

o	Required authenticated user.

◆ AuthenticatedUser_logout()

BA_API void AuthenticatedUser_logout	(	AuthenticatedUser *	o,
		BaBool	all
	)

Log out and terminate the associated session or sessions.

Parameters

all

False (default) terminates this session; true terminates the sessions sharing this user record. Session destruction may be deferred while in use, but the login slot is released immediately. Do not reuse the user pointer. Basic/Digest clients can automatically log in again using cached credentials. This call cannot erase credentials stored by the browser.

AuthenticatedUser* user = AuthenticatedUser::get(request);

if(user) user->logout(); // Avoid calling a C++ member through NULL.

AuthenticatedUser::logout

void logout(bool all=false)

Log out and terminate the associated session or sessions.

Definition: AuthenticatedUser.h:399

AuthenticatedUser::get

static AuthenticatedUser * get(HttpRequest *request)

Find the authenticated user without creating a session.

Definition: AuthenticatedUser.h:389

AuthenticatedUser

Abstract base class implemented by BasicAuthUser, FormAuthUser and DigestAuthUser.

Definition: AuthenticatedUser.h:272

The C function AuthenticatedUser_logout(NULL, FALSE) is a no-op.

o Session-owned authenticated user, or NULL for a no-op. Do not pass the anonymous object.

◆ Authenticator()

Authenticator::Authenticator	(	UserIntf *	userDbIntf,
		const char *	realm,
		LoginRespIntf *	sendLogin
	)

Construct an authenticator using application-provided user lookup.

Parameters

userDbIntf	Required borrowed user database interface; keep it alive while this authenticator is used.
realm	Required NUL-terminated realm string, copied during construction. It identifies the authentication realm sent to clients.
sendLogin	Required borrowed login-response interface, which must outlive authentication calls. Constructors have no error return; realm allocation failure cannot be reported through the constructor signature. Detach the authenticator from directories and stop its users before calling Authenticator_destructor(). The C++ interface has no destructor that performs this cleanup automatically.

◆ Authenticator_constructor()

BA_API void Authenticator_constructor	(	Authenticator *	o,
		UserIntf *	userDbIntf,
		const char *	realm,
		LoginRespIntf *	sendLogin
	)

C form of Authenticator::Authenticator.

Parameters

o	Required storage to initialize.
userDbIntf	Required borrowed user database.
realm	Copied realm string; see the C++ constructor for NULL handling.
sendLogin	Required borrowed login-response interface.

◆ Authenticator_destructor()

BA_API void Authenticator_destructor ( Authenticator * o )

Release authenticator-owned realm storage after detaching all users.

Parameters

o	Required initialized authenticator. Borrowed dependencies are not freed.

Note: The current composite destructor omits its Digest realm cleanup. This limitation is recorded for a separate implementation repair.

◆ AuthenticatorIntf()

AuthenticatorIntf::AuthenticatorIntf ( AuthenticatorIntf_Authenticate authenticate )

Install an authentication callback.

Parameters

authenticate Required callback; remains callable while installed.

◆ AuthenticatorIntf_constructor()

BA_API void AuthenticatorIntf_constructor	(	AuthenticatorIntf *	o,
		AuthenticatorIntf_Authenticate	authenticate
	)

Install the callback used by AuthenticatorIntf.

Parameters

authenticate	Required callback; remains callable while installed.
o	Required storage to initialize.

◆ authorize()

bool AuthorizerIntf::authorize	(	struct AuthenticatedUser *	user,
		HttpMethod	method,
		const char *	path
	)

Returns TRUE if user is authorized.

Parameters

user	AuthenticatedUser::get
method	The HTTP method type: From HttpRequest::getMethodType
path	The relative path element of the URL requested by the user.

◆ AuthorizerIntf()

AuthorizerIntf::AuthorizerIntf ( AuthorizerIntf_Authorize authorize )

The constructor.

Parameters

authorize Required callback; remains callable while this interface is used.

◆ BasicAuthenticator()

BasicAuthenticator::BasicAuthenticator	(	UserIntf *	userDbIntf,
		const char *	realm,
		LoginRespIntf *	sendLogin
	)

Construct an authenticator using application-provided user lookup.

Parameters

userDbIntf	Required borrowed user database interface; keep it alive while this authenticator is used.
realm	Required NUL-terminated realm string, copied during construction. It identifies the authentication realm sent to clients.
sendLogin	Required borrowed login-response interface, which must outlive authentication calls. Constructors have no error return; realm allocation failure cannot be reported through the constructor signature. Detach the authenticator from directories and stop its users before calling BasicAuthenticator_destructor(). The C++ interface has no destructor that performs this cleanup automatically.

◆ BasicAuthenticator_constructor()

BA_API void BasicAuthenticator_constructor	(	BasicAuthenticator *	o,
		UserIntf *	userDbIntf,
		const char *	realm,
		LoginRespIntf *	sendLogin
	)

C form of BasicAuthenticator::BasicAuthenticator.

Parameters

o	Required storage to initialize.
userDbIntf	Required borrowed user database.
realm	Copied realm string; see the C++ constructor for NULL handling.
sendLogin	Required borrowed login-response interface.

◆ BasicAuthenticator_destructor()

BA_API void BasicAuthenticator_destructor ( BasicAuthenticator * o )

Release authenticator-owned realm storage after detaching all users.

Parameters

o	Required initialized authenticator. Borrowed dependencies are not freed.

◆ BasicAuthenticator_setAutHeader()

BA_API int BasicAuthenticator_setAutHeader	(	const char *	realm,
		HttpResponse *	resp
	)

C form of BasicAuthenticator::setAutHeader.

The first argument is the required realm string; the second is the required response.

Returns: Zero, E_MALLOC, or E_IS_COMMITTED as described by setAutHeader().

◆ clearCache()

void LoginTracker::clearCache ( )

Remove all active cached addresses.

Invokes terminateNode for each active node and retains storage for reuse. Previously returned node pointers must no longer be used as cached entries.

◆ DavAuth()

DavAuth::DavAuth	(	UserIntf *	userDbIntf,
		const char *	realm
	)

Construct an authenticator using application-provided user lookup.

Parameters

userDbIntf Required borrowed user database interface; keep it alive while this authenticator is used.

realm Required NUL-terminated realm string, copied during construction. It identifies the authentication realm sent to clients. Constructors have no error return; realm allocation failure cannot be reported through the constructor signature. Detach the authenticator from directories and stop its users before calling DavAuth_destructor(). The C++ interface has no destructor that performs this cleanup automatically. Microsoft domain-prefix filtering is enabled for both embedded authenticators.

◆ DavAuth_constructor()

BA_API void DavAuth_constructor	(	DavAuth *	o,
		UserIntf *	userDbIntf,
		const char *	realm
	)

C form of DavAuth::DavAuth.

Parameters

o	Required storage to initialize.
userDbIntf	Required borrowed user database.
realm	Copied realm string; see the C++ constructor for NULL handling.

◆ DavAuth_destructor()

BA_API void DavAuth_destructor ( DavAuth * o )

Release authenticator-owned realm storage after detaching all users.

Parameters

o	Required initialized authenticator. Borrowed dependencies are not freed.

◆ DigestAuthenticator()

DigestAuthenticator::DigestAuthenticator	(	UserIntf *	userDbIntf,
		const char *	realm,
		LoginRespIntf *	sendLogin
	)

Construct an authenticator using application-provided user lookup.

Parameters

userDbIntf	Required borrowed user database interface; keep it alive while this authenticator is used.
realm	Required NUL-terminated realm string, copied during construction. It identifies the authentication realm sent to clients.
sendLogin	Required borrowed login-response interface, which must outlive authentication calls. Constructors have no error return; realm allocation failure cannot be reported through the constructor signature. Detach the authenticator from directories and stop its users before calling DigestAuthenticator_destructor(). The C++ interface has no destructor that performs this cleanup automatically.

◆ DigestAuthenticator_constructor()

BA_API void DigestAuthenticator_constructor	(	DigestAuthenticator *	o,
		UserIntf *	userDbIntf,
		const char *	realm,
		LoginRespIntf *	sendLogin
	)

C form of DigestAuthenticator::DigestAuthenticator.

Parameters

o	Required storage to initialize.
userDbIntf	Required borrowed user database.
realm	Copied realm string; see the C++ constructor for NULL handling.
sendLogin	Required borrowed login-response interface.

◆ DigestAuthenticator_destructor()

BA_API void DigestAuthenticator_destructor ( DigestAuthenticator * o )

Release authenticator-owned realm storage after detaching all users.

Parameters

o	Required initialized authenticator. Borrowed dependencies are not freed.

◆ DigestAuthenticator_setAutHeader()

BA_API int DigestAuthenticator_setAutHeader	(	const char *	,
		HttpResponse *
	)

C form of DigestAuthenticator::setAutHeader.

The first argument is the required realm string; the second is the required response.

Returns: Zero, E_MALLOC, or E_IS_COMMITTED as described by setAutHeader().

◆ find()

LoginTrackerNode * LoginTracker::find ( HttpRequest * request )

Find a cached address using the current connection's peer IP.

Parameters

request Required request with its current connection.

Returns: Borrowed node, or NULL when not cached or peer lookup fails.

◆ FormAuthenticator()

FormAuthenticator::FormAuthenticator	(	UserIntf *	userDbIntf,
		const char *	realm,
		LoginRespIntf *	sendLogin
	)

Construct an authenticator using application-provided user lookup.

Parameters

userDbIntf	Required borrowed user database interface; keep it alive while this authenticator is used.
realm	Copied NUL-terminated realm. NULL selects an empty realm; supply the matching realm when the database stores HA1 password hashes.
sendLogin	Required borrowed login-response interface, which must outlive authentication calls. Constructors have no error return; realm allocation failure cannot be reported through the constructor signature. Detach the authenticator from directories and stop its users before calling FormAuthenticator_destructor(). The C++ interface has no destructor that performs this cleanup automatically.

◆ FormAuthenticator_constructor()

BA_API void FormAuthenticator_constructor	(	FormAuthenticator *	o,
		UserIntf *	userDbIntf,
		const char *	realm,
		LoginRespIntf *	login
	)

C form of FormAuthenticator::FormAuthenticator.

Parameters

o	Required storage to initialize.
userDbIntf	Required borrowed user database.
realm	Copied realm string; see the C++ constructor for NULL handling.
login	Required borrowed login-response interface.

◆ get() [1/2]

AuthenticatedUser * AuthenticatedUser::get ( HttpRequest * request )

static

Find the authenticated user without creating a session.

Parameters

request Required current request.

Returns: Borrowed user owned by the existing session, or NULL if unavailable. Do not free it or retain it beyond logout/session destruction. C equivalent: AuthenticatedUser_get1().

◆ get() [2/2]

AuthenticatedUser * AuthenticatedUser::get ( HttpSession * session )

static

Find the authenticated-user session attribute.

Parameters

session Existing session, or NULL.

Returns: Borrowed authenticated user, or NULL when no such attribute exists. C equivalent: AuthenticatedUser_get2().

◆ getAddr()

HttpSockaddr * LoginTrackerNode::getAddr ( )

Access the cached peer IP address.

Returns: Borrowed pointer valid while this node remains cached. Do not modify the address used as the tree key.

◆ getAnonymous()

AuthenticatedUser * AuthenticatedUser::getAnonymous ( )

static

Access the shared anonymous user.

Returns: Non-NULL borrowed static object named "anonymous", with type Unknown. It is not a session login. Do not log it out, destroy, free, or modify it.

◆ getAuxCounter()

U32 LoginTrackerNode::getAuxCounter ( )

Query the application auxiliary counter.

Returns: Last stored U32 value, initially zero for a new node.

◆ getBasicAuth()

BasicAuthenticator * DavAuth::getBasicAuth ( )

Access the embedded Basic authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

◆ getBasicAuthenticator()

BasicAuthenticator * Authenticator::getBasicAuthenticator ( )

Access the embedded Basic authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

◆ getCounter()

U32 LoginTrackerNode::getCounter ( )

Query the address failure/denial counter.

Returns: U32 count maintained by the tracker, initially zero for a new node.

◆ getDigestAuth()

DigestAuthenticator * DavAuth::getDigestAuth ( )

Access the embedded Digest authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

◆ getDigestAuthenticator()

DigestAuthenticator * Authenticator::getDigestAuthenticator ( )

Access the embedded Digest authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

◆ getFirstNode()

LoginTrackerNode * LoginTracker::getFirstNode ( )

Start iteration over active cached addresses in insertion order.

Returns: Borrowed first node, or NULL when empty. Keep the cache unchanged during iteration; pointers may be reused after login, clearing, or recycling.

◆ getFormAuthenticator()

FormAuthenticator * Authenticator::getFormAuthenticator ( )

Access the embedded Form authenticator.

Returns: Non-NULL borrowed pointer with the parent's lifetime. Use it to configure that mechanism; do not destroy or free it independently.

◆ getName()

const char * AuthenticatedUser::getName ( )

Access the authenticated name.

Returns: Borrowed NUL-terminated user name, or NULL if unavailable. It remains valid only while the associated authentication record remains alive.

◆ getNextNode()

LoginTrackerNode * LoginTracker::getNextNode ( LoginTrackerNode * n )

Advance through active cached addresses.

Parameters

n	Required node currently in this tracker's active list.

Returns: Borrowed next node, or NULL at the end. Do not pass NULL or a stale node.

◆ getPassword()

const char * AuthenticatedUser::getPassword ( )

Access the stored credential representation.

Returns: Borrowed NUL-terminated password/hash, or NULL if unavailable. Basic and Form callback-validated credentials can be represented by the placeholder "?" rather than the original password. Copy before logout/session destruction.

◆ getSession()

HttpSession * AuthenticatedUser::getSession ( )

Get the containing session.

Returns: Borrowed session pointer, or NULL if not attached. Do not terminate it directly to log out a user; use logout().

◆ getTime()

BaTime LoginTrackerNode::getTime ( )

Query the latest recorded failed or denied attempt.

Returns: Unix time in seconds, as provided by baGetUnixTime().

◆ getType()

AuthenticatedUserType AuthenticatedUser::getType ( )

Identify the authenticator that created this user.

Returns: Basic, Digest, Form, or Unknown from AuthenticatedUserType. Unknown includes the shared anonymous object and unrecognized derived types.

◆ getUserData()

void * LoginTrackerNode::getUserData ( )

Query application data.

Returns: Last stored pointer, initially NULL; ownership remains with the application.

◆ LoginRespIntf()

LoginRespIntf::LoginRespIntf ( LoginRespIntf_Service service )

Install the required login-response callback.

Parameters

service a pointer to the response service callback function.

◆ LoginTracker()

LoginTracker::LoginTracker	(	U32	noOfLoginTrackerNodes,
		LoginTrackerIntf *	intf,
		AllocatorIntf *	allocator = `AllocatorIntf::getDefault()`
	)

Allocate a fixed cache of address records.

Parameters

noOfLoginTrackerNodes	Requested positive cache capacity.
intf	Required borrowed interface containing four non-NULL callbacks.
allocator	Required allocation interface; the C++ default is AllocatorIntf::getDefault(). NULL does not select a default in the C function. Allocation failure calls baFatalE(FE_MALLOC, 0); there is no error return.

Warning: The current implementation allocates one fewer node than the capacity it uses and frees node storage with baFree rather than the supplied allocator. These implementation limitations require a separate source repair. The C++ interface has no automatic cleanup destructor; after detaching users, call LoginTracker_destructor() once.

◆ LoginTracker_clearCache()

BA_API void LoginTracker_clearCache ( LoginTracker * o )

Remove all active cached addresses.

Invokes terminateNode for each active node and retains storage for reuse. Previously returned node pointers must no longer be used as cached entries.

Parameters

o	Required initialized tracker.

◆ LoginTracker_constructor()

BA_API void LoginTracker_constructor	(	LoginTracker *	o,
		U32	noOfLoginTrackerNodes,
		LoginTrackerIntf *	intf,
		AllocatorIntf *	allocator
	)

Allocate a fixed cache of address records.

Parameters

noOfLoginTrackerNodes	Requested positive cache capacity.
intf	Required borrowed interface containing four non-NULL callbacks.
allocator	Required allocation interface; the C++ default is AllocatorIntf::getDefault(). NULL does not select a default in the C function. Allocation failure calls baFatalE(FE_MALLOC, 0); there is no error return.

Warning: The current implementation allocates one fewer node than the capacity it uses and frees node storage with baFree rather than the supplied allocator. These implementation limitations require a separate source repair. The C++ interface has no automatic cleanup destructor; after detaching users, call LoginTracker_destructor() once.

Parameters

o	Required storage to initialize.

◆ LoginTracker_destructor()

BA_API void LoginTracker_destructor ( LoginTracker * o )

Release a tracker after detaching all users.

Parameters

o	Required initialized tracker. Calls clearCache(), then baFree on its node storage. Does not free callback interfaces.

◆ LoginTracker_find()

BA_API LoginTrackerNode * LoginTracker_find	(	LoginTracker *	o,
		HttpRequest *	req
	)

C form of LoginTracker::find.

Parameters

o	Required tracker.
req	Required request.

Returns: Borrowed node, or NULL if absent or peer lookup fails.

◆ LoginTracker_getFirstNode()

BA_API LoginTrackerNode * LoginTracker_getFirstNode ( LoginTracker * o )

Start iteration over active cached addresses in insertion order.

Returns: Borrowed first node, or NULL when empty. Keep the cache unchanged during iteration; pointers may be reused after login, clearing, or recycling.

Parameters

o	Required initialized tracker.

◆ LoginTracker_getNextNode()

BA_API LoginTrackerNode * LoginTracker_getNextNode	(	LoginTracker *	o,
		LoginTrackerNode *	n
	)

Advance through active cached addresses.

Parameters

n	Required node currently in this tracker's active list.

Returns: Borrowed next node, or NULL at the end. Do not pass NULL or a stale node.

Parameters

o	Required initialized tracker.

◆ LoginTracker_login()

BA_API void LoginTracker_login	(	LoginTracker *	o,
		AuthInfo *	info
	)

Notify successful authentication and remove any cached peer entry.

Parameters

o	Required initialized tracker.
info	Required authentication record with non-NULL cmd. Calls login with a node or NULL, then terminateNode for an existing node before recycling it. Callback pointers are borrowed and must not be retained.

◆ LoginTracker_loginFailed()

BA_API void LoginTracker_loginFailed	(	LoginTracker *	o,
		AuthInfo *	info
	)

Record a failed login, inserting or recycling an address node as needed.

Parameters

o	Required initialized tracker.
info	Required authentication record with non-NULL cmd. Updates the counter/time before calling loginFailed. If peer lookup fails, marks the connection terminated. No error value is returned.

◆ LoginTracker_validate()

BA_API BaBool LoginTracker_validate	(	LoginTracker *	o,
		AuthInfo *	info
	)

Check whether a cached peer may attempt authentication.

Parameters

o	Required initialized tracker.
info	Required authentication record with non-NULL cmd.

Returns: TRUE for an uncached address or callback acceptance; FALSE for callback denial or peer lookup failure. Denial updates denied/loginAttempts and the node counter/time. Peer lookup failure sends an HTTP 501 response.

◆ LoginTrackerIntf()

LoginTrackerIntf::LoginTrackerIntf	(	LoginTrackerIntf_Validate	validate,
		LoginTrackerIntf_Login	login,
		LoginTrackerIntf_LoginFailed	loginFailed,
		LoginTrackerIntf_TerminateNode	terminateNode
	)

Install four required callbacks; none may be NULL.

Parameters

validate	validate a user.
login	A user successfully logged in.
loginFailed	The login attempt failed.
terminateNode	The LoginTrackerNode is recycled.

◆ logout()

void AuthenticatedUser::logout ( bool all = false )

Log out and terminate the associated session or sessions.

Parameters

all

False (default) terminates this session; true terminates the sessions sharing this user record. Session destruction may be deferred while in use, but the login slot is released immediately. Do not reuse the user pointer. Basic/Digest clients can automatically log in again using cached credentials. This call cannot erase credentials stored by the browser.

AuthenticatedUser* user = AuthenticatedUser::get(request);

if(user) user->logout(); // Avoid calling a C++ member through NULL.

The C function AuthenticatedUser_logout(NULL, FALSE) is a no-op.

◆ setAutHeader() [1/2]

int BasicAuthenticator::setAutHeader	(	const char *	realm,
		HttpResponse *	response
	)

static

Sets an HTTP Basic authentication challenge and status code.

This method can be used to design logic for invalidating the user and password saved by a browser.

Parameters

realm	Required NUL-terminated realm used in the challenge; supply a value suitable for an HTTP quoted string.
response	Required response receiving the 401 challenge. The response retains its own header value.

Returns: 0 on success, including an ignored call during inclusion; E_MALLOC if header storage fails; E_IS_COMMITTED if already committed outside inclusion. Failure leaves the status code unchanged.

◆ setAutHeader() [2/2]

int DigestAuthenticator::setAutHeader	(	const char *	realm,
		HttpResponse *	response
	)

static

Sets an HTTP Digest authentication challenge and status code.

This method can be used to design logic for invalidating the user and password saved by a browser.

Parameters

realm	Required NUL-terminated realm used in the challenge; supply a value suitable for an HTTP quoted string.
response	Required response receiving the 401 challenge. The response retains its own header value.

Returns: 0 on success, including an ignored call during inclusion; E_MALLOC if header storage fails; E_IS_COMMITTED if already committed outside inclusion. Failure leaves the status code unchanged.

◆ setAuxCounter()

void LoginTrackerNode::setAuxCounter ( U32 count )

Set the application auxiliary counter.

Parameters

count U32 value, used as the baseline subtracted from loginCounter when populating denied-attempt information.