authentication-control.h File Reference

Allows a client session to authenticate the credentials of other sessions, and optionally revoke such authentications. More...

Data Structures
struct	diffusion_authentication_handler_s
	Structure supplied as part of a diffusion_set_authentication_handler request. More...
struct	diffusion_authentication_handler_params_s
	Structure supplied when issuing an diffusion_set_authentication_handler request. More...
struct	diffusion_revoke_authentication_params_s
	Structure supplied when issuing a diffusion_revoke_authentication request. More...

Macros
#define	DEFAULT_AUTH_GROUP_NAME
	If not specified, the group name "default" is used when registering authentication handlers.

Typedefs
typedef int(*	authenticator_on_active) (SESSION_T *session, const DIFFUSION_REGISTRATION_T *registered_handler)
	Callback when an authentication handler is active.
typedef int(*	authenticator_on_authenticate) (SESSION_T *session, const char *principal, const CREDENTIALS_T *credentials, const HASH_T *session_properties, const HASH_T *proposed_session_properties, const DIFFUSION_AUTHENTICATOR_T *authenticator)
	Callback when an authentication handler has received a connection request to be authenticated.
typedef int(*	authenticator_on_error) (const DIFFUSION_ERROR_T *error)
	Callback when an authenticator has encountered an error.
typedef void(*	authenticator_on_close) (void)
	Callback when an authentication handler is closed.
typedef struct diffusion_authentication_handler_s	DIFFUSION_AUTHENTICATION_HANDLER_T
	Structure supplied as part of a diffusion_set_authentication_handler request.
typedef struct diffusion_authentication_handler_params_s	DIFFUSION_AUTHENTICATION_HANDLER_PARAMS_T
	Structure supplied when issuing an diffusion_set_authentication_handler request.
typedef int(*	on_session_revoked_cb) (SESSION_T *session, void *context)
	Callback for diffusion_get_path_permissions.
typedef struct diffusion_revoke_authentication_params_s	DIFFUSION_REVOKE_AUTHENTICATION_PARAMS_T
	Structure supplied when issuing a diffusion_revoke_authentication request.

Functions
void	diffusion_set_authentication_handler (SESSION_T *session, const DIFFUSION_AUTHENTICATION_HANDLER_PARAMS_T params)
	Register an authentication handler for client authentication events.
bool	diffusion_revoke_authentication (SESSION_T *session, const DIFFUSION_REVOKE_AUTHENTICATION_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Revokes a session's authentication.

Detailed Description

Allows a client session to authenticate the credentials of other sessions, and optionally revoke such authentications.

Sessions are authenticated by a chain of authenticators. A client session can participate in the authentication process by creating an authenticator and registering it with the server.

Each authenticator is registered under a particular authenticator name. For registration to succeed, the server's security configuration must include a matching control-authentication-handler entry for the name, otherwise registration will fail and the authenticator will be closed immediately.

Each client session can register a single authenticator for a given authenticator name.

For each authentication event, the server will use its configuration to determine the authenticator priority order. The server may call authenticators in serial or parallel. The server may stop the authentication process as soon as it has an allow or deny response from an authenticator and all higher priority authenticators have abstained.

For a configured control authenticator, the server will select a single authenticator from those registered for the authenticator name. If no authenticators are currently registered, the server will consult the next configured authenticator in priority order.

Access control

In order to register an authenticator a session needs both REGISTER_HANDLER REGISTER_HANDLER and AUTHENTICATE permissions.

In order to revoke a session's authentication a session needs both MODIFY_SESSION and AUTHENTICATE permissions.

Typedef Documentation

authenticator_on_active

typedef int(* authenticator_on_active) (SESSION_T *session, const DIFFUSION_REGISTRATION_T *registered_handler)

Callback when an authentication handler is active.

Parameters

session	The currently active session.
registered_handler	The registered handler

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

authenticator_on_authenticate

typedef int(* authenticator_on_authenticate) (SESSION_T *session, const char *principal, const CREDENTIALS_T *credentials, const HASH_T *session_properties, const HASH_T *proposed_session_properties, const DIFFUSION_AUTHENTICATOR_T *authenticator)

Callback when an authentication handler has received a connection request to be authenticated.

Parameters

session	The currently active session.
principal	The principal of the connection request to be authenticated
credentials	The credentials of the connection request to be authenticated
session_properties	The session properties of the connection request to be authenticated
proposed_session_properties	The proposed properties from the connection request to be authenticated
authenticator	The authenticator. Used to authenticate connection requests (see authenticator.h)

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

authenticator_on_error

typedef int(* authenticator_on_error) (const DIFFUSION_ERROR_T *error)

Callback when an authenticator has encountered an error.

Parameters

error

The received error.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

DIFFUSION_REVOKE_AUTHENTICATION_PARAMS_T

typedef struct diffusion_revoke_authentication_params_s DIFFUSION_REVOKE_AUTHENTICATION_PARAMS_T

Structure supplied when issuing a diffusion_revoke_authentication request.

Since

6.12

on_session_revoked_cb

typedef int(* on_session_revoked_cb) (SESSION_T *session, void *context)

Callback for diffusion_get_path_permissions.

Parameters

session	The current active session.
context	User-supplied context from the originating call.

Returns

HANDLER_SUCCESS or HANDLER_FAILURE.

Since

6.12