Diffusion C API  6.4.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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. More...
 

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. More...
 
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. More...
 
bool diffusion_authenticator_abstain (SESSION_T *session, const DIFFUSION_AUTHENTICATOR_T *authenticator, DIFFUSION_API_ERROR *error)
 The authentication has neither passed nor failed. More...
 
bool diffusion_authenticator_deny (SESSION_T *session, const DIFFUSION_AUTHENTICATOR_T *authenticator, DIFFUSION_API_ERROR *error)
 Authentication failed - deny the authentication request. More...
 
DIFFUSION_AUTHENTICATOR_Tdiffusion_authenticator_dup (const DIFFUSION_AUTHENTICATOR_T *authenticator)
 Create a duplicate (copy) of an existing DIFFUSION_AUTHENTICATOR_T. More...
 
void diffusion_authenticator_free (DIFFUSION_AUTHENTICATOR_T *authenticator)
 Free a memory allocated DIFFUSION_AUTHENTICATOR_T More...
 

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

Opaque diffusion authenticator struct.

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

Function Documentation

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

The authentication has neither passed nor failed.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
authenticatorThe session authenticator
errorPopulated 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.
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
sessionThe session handle. If NULL, this function returns immediately.
authenticatorThe session authenticator
errorPopulated 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.
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
sessionThe session handle. If NULL, this function returns immediately.
authenticatorThe session authenticator
propertiesThis can include all allowed user-defined session properties, as well as a subset of fixed session properties see
errorPopulated 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.
bool diffusion_authenticator_deny ( SESSION_T session,
const DIFFUSION_AUTHENTICATOR_T authenticator,
DIFFUSION_API_ERROR error 
)

Authentication failed - deny the authentication request.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
authenticatorThe session authenticator
errorPopulated 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_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
authenticatorThe authenticator to be duplicated.
Returns
a copy of the provided authenticator. NULL, if the provided authenticator is NULL.
void diffusion_authenticator_free ( DIFFUSION_AUTHENTICATOR_T authenticator)

Free a memory allocated DIFFUSION_AUTHENTICATOR_T

Parameters
authenticatorthe authenticator to be freed.