authenticator.h File Reference

An authentication handler that processes authentication requests from the server. More...

Typedefs
typedef struct DIFFUSION_AUTHENTICATOR_T	DIFFUSION_AUTHENTICATOR_T
	Opaque diffusion authenticator struct.

Functions
bool	diffusion_authenticator_allow (SESSION_T *session, const DIFFUSION_AUTHENTICATOR_T *authenticator, DIFFUSION_API_ERROR *error)
	Authentication passed - allow the authentication request with fixed properties as supplied but no user-defined properties.
bool	diffusion_authenticator_allow_with_properties (SESSION_T *session, const DIFFUSION_AUTHENTICATOR_T *authenticator, const HASH_T *properties, DIFFUSION_API_ERROR *error)
	Authentication passed - allow the authentication request with modifications to the session properties.
bool	diffusion_authenticator_abstain (SESSION_T *session, const DIFFUSION_AUTHENTICATOR_T *authenticator, DIFFUSION_API_ERROR *error)
	The authentication has neither passed nor failed.
bool	diffusion_authenticator_deny (SESSION_T *session, const DIFFUSION_AUTHENTICATOR_T *authenticator, DIFFUSION_API_ERROR *error)
	Authentication failed - deny the authentication request.
DIFFUSION_AUTHENTICATOR_T *	diffusion_authenticator_dup (const DIFFUSION_AUTHENTICATOR_T *authenticator)
	Create a duplicate (copy) of an existing DIFFUSION_AUTHENTICATOR_T.
void	diffusion_authenticator_free (DIFFUSION_AUTHENTICATOR_T *authenticator)
	Free a memory allocated DIFFUSION_AUTHENTICATOR_T

Detailed Description

An authentication handler that processes authentication requests from the server.

Instances can be registered with the server using the diffusion_set_authentication_handler feature.

The server calls an authentication handler when a client application creates a session, or changes the principal associated with a session, allowing the handler to veto individual requests.

Authentication handlers are configured in precedence order. Authentication will succeed if a handler responds by calling diffusion_authenticator_allow or diffusion_authenticator_allow_with_properties and handlers with higher precedence respond by calling diffusion_authenticator_abstain

Authentication will fail if a handler responds by calling diffusion_authenticator_deny and all higher precedence handlers respond by calling diffusion_authenticator_abstain

If all authentication handlers respond by calling diffusion_authenticator_abstain, the request will be denied. Once the outcome is known, the server may choose not to call any remaining authentication handlers.

Typedef Documentation

DIFFUSION_AUTHENTICATOR_T

typedef struct DIFFUSION_AUTHENTICATOR_T DIFFUSION_AUTHENTICATOR_T

Opaque diffusion authenticator struct.

Each authentication request receives its own unique, single use authenticator. An authenticator can only be used once to either allow, abstain or deny an authentication request.

Function Documentation

diffusion_authenticator_abstain()

bool diffusion_authenticator_abstain	(	SESSION_T *	session,
		const DIFFUSION_AUTHENTICATOR_T *	authenticator,
		DIFFUSION_API_ERROR *	error
	)

The authentication has neither passed nor failed.

Parameters

session	The session handle. If NULL, this function returns immediately.
authenticator	The session authenticator
error	Populated if an error occurs. Can be NULL.

Returns

true if the authentication response was successfully dispatched. False, otherwise. In this case, if a non-NULL DIFFUSION_API_ERROR pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

diffusion_authenticator_allow()

bool diffusion_authenticator_allow	(	SESSION_T *	session,
		const DIFFUSION_AUTHENTICATOR_T *	authenticator,
		DIFFUSION_API_ERROR *	error
	)

Authentication passed - allow the authentication request with fixed properties as supplied but no user-defined properties.

Parameters

session	The session handle. If NULL, this function returns immediately.
authenticator	The session authenticator
error	Populated if an error occurs. Can be NULL.

Returns

true if the authentication response was successfully dispatched. False, otherwise. In this case, if a non-NULL DIFFUSION_API_ERROR pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

diffusion_authenticator_allow_with_properties()

bool diffusion_authenticator_allow_with_properties	(	SESSION_T *	session,
		const DIFFUSION_AUTHENTICATOR_T *	authenticator,
		const HASH_T *	properties,
		DIFFUSION_API_ERROR *	error
	)

Authentication passed - allow the authentication request with modifications to the session properties.

Parameters

session	The session handle. If NULL, this function returns immediately.
authenticator	The session authenticator
properties	This can include all allowed user-defined session properties, as well as a subset of fixed session properties see
error	Populated if an error occurs. Can be NULL.

Returns

true if the authentication response was successfully dispatched. False, otherwise. In this case, if a non-NULL DIFFUSION_API_ERROR pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

diffusion_authenticator_deny()

bool diffusion_authenticator_deny	(	SESSION_T *	session,
		const DIFFUSION_AUTHENTICATOR_T *	authenticator,
		DIFFUSION_API_ERROR *	error
	)

Authentication failed - deny the authentication request.

Parameters

session	The session handle. If NULL, this function returns immediately.
authenticator	The session authenticator
error	Populated if an error occurs. Can be NULL.

Returns

true if the authentication response was successfully dispatched. False, otherwise. In this case, if a non-NULL DIFFUSION_API_ERROR pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

diffusion_authenticator_dup()

DIFFUSION_AUTHENTICATOR_T * diffusion_authenticator_dup

(

const DIFFUSION_AUTHENTICATOR_T *

authenticator

)

Create a duplicate (copy) of an existing DIFFUSION_AUTHENTICATOR_T.

diffusion_authenticator_free should be called on this pointer when no longer needed.

Parameters

authenticator

The authenticator to be duplicated.

Returns

a copy of the provided authenticator. NULL, if the provided authenticator is NULL.

diffusion_authenticator_free()

void diffusion_authenticator_free

(

DIFFUSION_AUTHENTICATOR_T *

authenticator

)

Free a memory allocated DIFFUSION_AUTHENTICATOR_T

Parameters

authenticator

the authenticator to be freed.