Diffusion C API  6.3.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
authentication-control.h File Reference

Authentication control feature. More...

Data Structures

struct  svc_authentication_register_request_s
 Structure containing the information required when sending a request to register as an authentication service. More...
 
struct  connector_details_s
 This structure is populated in the authentication request when the detail type SESSION_DETAIL_CONNECTOR_NAME has been requested. More...
 
struct  svc_authentication_request_s
 The structure passed to an authentication handler. More...
 
struct  svc_authentication_response_s
 Structure holding the response message from the authentication handler. More...
 
struct  authentication_registration_params_s
 Structure supplied when issuing an authentication_register() request. More...
 
struct  authentication_deregistration_handlers_s
 
struct  authentication_deregistration_params_s
 Structure supplied when issuing an authentication_deregister() request. More...
 
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...
 

Macros

#define DEFAULT_AUTH_GROUP_NAME
 If not specified, the group name "default" is used when registering authentication handlers.
 
#define AUTHENTICATION_HANDLERS
 Callbacks that can be supplied by an authentication service.
 
#define AUTHENTICATION_REGISTRATION_HANDLERS
 Handlers for notification of registration of an authentication handler.
 
#define AUTHENTICATION_DEREGISTRATION_HANDLERS
 Callbacks invoked in response to a deregistration request.
 

Typedefs

typedef struct
svc_authentication_register_request_s 
SVC_AUTHENTICATION_REGISTER_REQUEST_T
 Structure containing the information required when sending a request to register as an authentication service.
 
typedef
SVC_AUTHENTICATION_REGISTER_REQUEST_T 
SVC_AUTHENTICATION_DEREGISTER_REQUEST_T
 The request to deregister an authentication handler. More...
 
typedef struct connector_details_s CONNECTOR_DETAILS_T
 This structure is populated in the authentication request when the detail type SESSION_DETAIL_CONNECTOR_NAME has been requested.
 
typedef struct
svc_authentication_request_s 
SVC_AUTHENTICATION_REQUEST_T
 The structure passed to an authentication handler.
 
typedef struct
svc_authentication_response_s 
SVC_AUTHENTICATION_RESPONSE_T
 Structure holding the response message from the authentication handler.
 
typedef int(* on_authentication_cb )(SESSION_T *session, const SVC_AUTHENTICATION_REQUEST_T *request, SVC_AUTHENTICATION_RESPONSE_T *response, void *context)
 Callback for on_authentication(). More...
 
typedef int(* on_authentication_registration_cb )(SESSION_T *session, void *context)
 Callback for on_registration(). More...
 
typedef struct
authentication_registration_params_s 
AUTHENTICATION_REGISTRATION_PARAMS_T
 Structure supplied when issuing an authentication_register() request.
 
typedef int(* on_authentication_deregistration_cb )(SESSION_T *session, void *context)
 Callback for on_deregistration(). More...
 
typedef int(* authenticator_on_active )(SESSION_T *session, const DIFFUSION_REGISTRATION_T *registered_handler)
 Callback when an authentication handler is active. More...
 
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. More...
 
typedef int(* authenticator_on_error )(const DIFFUSION_ERROR_T *error)
 Callback when an authenticator has encountered an error. More...
 
typedef void(* authenticator_on_close )(void)
 Callback when an authentication handler is closed.
 
typedef struct
authentication_deregistration_params_s 
AUTHENTICATION_DEREGISTRATION_PARAMS_T
 Structure supplied when issuing an authentication_deregister() request.
 
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.
 

Enumerations

enum  SESSION_DETAIL_TYPE_T { SESSION_DETAIL_SUMMARY, SESSION_DETAIL_LOCATION, SESSION_DETAIL_CONNECTOR_NAME }
 Degree of session detail required. More...
 
enum  SVC_AUTHENTICATION_RESPONSE_VALUE_T { AUTHENTICATION_DENY, AUTHENTICATION_ABSTAIN, AUTHENTICATION_ALLOW, AUTHENTICATION_ALLOW_WITH_RESULT }
 The action to take for the authentication request. More...
 

Functions

 DEPRECATED (SVC_AUTHENTICATION_REGISTER_REQUEST_T *authentication_register(SESSION_T *session, const AUTHENTICATION_REGISTRATION_PARAMS_T params))
 Register an authentication handler. More...
 
 DEPRECATED (void authentication_deregister(SESSION_T *session, const AUTHENTICATION_DEREGISTRATION_PARAMS_T params))
 Deregister an authentication handler. More...
 
void diffusion_set_authentication_handler (SESSION_T *session, const DIFFUSION_AUTHENTICATION_HANDLER_PARAMS_T params)
 Register an authentication handler for client authentication events. More...
 
 DEPRECATED (void svc_authentication_register_request_free(SESSION_T *session, SVC_AUTHENTICATION_REGISTER_REQUEST_T *request))
 Free a SVC_AUTHENTICATION_REGISTER_REQUEST_T. More...
 

Detailed Description

Authentication control feature.

Functions required for registering and deregistering an authentication service in a control client.

Typedef Documentation

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

Callback when an authentication handler is active.

Parameters
sessionThe currently active session.
registered_handlerThe registered handler
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
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
sessionThe currently active session.
principalThe principal of the connection request to be authenticated
credentialsThe credentials of the connection request to be authenticated
session_propertiesThe session properties of the connection request to be authenticated
proposed_session_propertiesThe proposed properties from the connection request to be authenticated
authenticatorThe authenticator. Used to authenticate connection requests (see authenticator.h)
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* authenticator_on_error)(const DIFFUSION_ERROR_T *error)

Callback when an authenticator has encountered an error.

Parameters
errorThe received error.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_authentication_cb)(SESSION_T *session, const SVC_AUTHENTICATION_REQUEST_T *request, SVC_AUTHENTICATION_RESPONSE_T *response, void *context)

Callback for on_authentication().

Parameters
sessionThe current active session.
requestThe incoming authentication request.
responseThe response to be returned from the handler.
contextUser-supplied context from initial authentication handler registration.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_authentication_deregistration_cb)(SESSION_T *session, void *context)

Callback for on_deregistration().

Parameters
sessionThe currently active session.
contextUser-supplied context from the initial authentication_deregister() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_authentication_registration_cb)(SESSION_T *session, void *context)

Callback for on_registration().

Parameters
sessionThe currently active session.
contextUser-supplied context from the initial authentication_register() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.

The request to deregister an authentication handler.

The same as the registration request.

Enumeration Type Documentation

Degree of session detail required.

When registering an authentication handler, you can request various levels of information about connecting clients to enable you to make a decision about the validity of the client. This enumeration lists the available details that can be requested.

Enumerator
SESSION_DETAIL_SUMMARY 

Request summary information only.

SESSION_DETAIL_LOCATION 

Also request GeoIP information.

SESSION_DETAIL_CONNECTOR_NAME 

Request information about the connector which the client has used while connecting to Diffusion.

The action to take for the authentication request.

On receipt of an authentication request, the service may either deny the connecting client, allow it or abstain from answering which passes the request to the next handler in the chain.

Enumerator
AUTHENTICATION_DENY 

Authentication failed.

AUTHENTICATION_ABSTAIN 

Authentication has neither passed nor failed.

AUTHENTICATION_ALLOW 

Authentication passed, no result supplied.

AUTHENTICATION_ALLOW_WITH_RESULT 

Authentication passed, result supplied.

Function Documentation

DEPRECATED ( SVC_AUTHENTICATION_REGISTER_REQUEST_T authentication_registerSESSION_T *session, const AUTHENTICATION_REGISTRATION_PARAMS_T params)

Register an authentication handler.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release. Applications should now use the preferred function diffusion_set_authentication_handler.
Parameters
sessionThe session handle. If NULL, this function returns immediately with the value NULL.
paramsParameters defining the request to register an authentication handler.
Returns
The request structure which is required for later deregistering the authorisation handler, or NULL if the session handle was NULL.
DEPRECATED ( void   authentication_deregisterSESSION_T *session, const AUTHENTICATION_DEREGISTRATION_PARAMS_T params)

Deregister an authentication handler.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.
Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameters defining the request to deregister an existing authentication handler.
DEPRECATED ( void   svc_authentication_register_request_freeSESSION_T *session, SVC_AUTHENTICATION_REGISTER_REQUEST_T *request)

Free a SVC_AUTHENTICATION_REGISTER_REQUEST_T.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.
Parameters
sessionThe currently active session.
requestThe request to be freed.