Authentication Support

Authentication Support — API for loadable authentication modules

Synopsis


#include <monitor/monitor.h>


enum        mon_auth_type;
#define     MON_AUTH_API
            mon_auth_module_client;
#define     MON_AUTH_MODULE_CLIENT          (desc)
#define     MON_SYMBOL_AUTH_CLIENT
            mon_auth_module_server;
#define     MON_AUTH_MODULE_SERVER          (desc)
#define     MON_SYMBOL_AUTH_SERVER
#define     MON_AUTH_METH_TRANSPORT
#define     MON_AUTH_PARAM_SERVER
#define     MON_AUTH_PARAM_SERVICE
int         mon_auth_client_register        (mon_module *module);
void        mon_auth_client_unregister      (mon_module *module);
int         mon_auth_server_register        (mon_module *module);
void        mon_auth_server_unregister      (mon_module *module);
const char** mon_auth_client_methlist       (void);
const char** mon_auth_server_methlist       (void);
void        mon_auth_methlist_free          (const char **methlist);
int         mon_auth_client_new             (const char *meth,
                                             const mon_cfg_node *config,
                                             const char *default_hostname,
                                             mon_cred_flags flags,
                                             mon_auth_creds **creds);
int         mon_auth_server_new             (const char *meth,
                                             const mon_cfg_node *config,
                                             const char *default_hostname,
                                             mon_cred_flags flags,
                                             mon_auth_creds **creds);

            mon_auth_creds;
enum        mon_cred_flags;
            mon_auth_state;
enum        mon_auth_state_state;
mon_auth_creds* mon_auth_creds_new          (mon_module *module,
                                             mon_auth_type type,
                                             const mon_cfg_node *config,
                                             const char *default_hostname,
                                             mon_cred_flags flags);
void        mon_auth_creds_done             (mon_auth_creds *creds);
void        mon_auth_creds_ref              (mon_auth_creds *creds);
int         mon_auth_state_new              (mon_auth_creds *creds,
                                             mon_auth_state **state);
void        mon_auth_state_free             (mon_auth_state *state);
int         mon_auth_state_step             (mon_auth_state *state,
                                             void *data,
                                             size_t len);
char*       mon_auth_user_id                (mon_auth_state *state);
char*       mon_auth_auth_id                (mon_auth_state *state);
const char* mon_auth_method                 (mon_auth_state *state);

Description

Details

enum mon_auth_type

typedef enum {
	MON_AUTH_SERVER,
	MON_AUTH_CLIENT
} mon_auth_type;

Authenticator types.

MON_AUTH_SERVERserver-side authenticator
MON_AUTH_CLIENTclient-side authenticator

MON_AUTH_API

#define MON_AUTH_API		1

Defines the version of the authentication API that is implemented by the library.


mon_auth_module_client

typedef struct {
	mon_module		header;

	unsigned int		strength;

	/* Initialize authentication credentials */
	int			(*init_creds)(mon_auth_creds *creds,
					const mon_cfg_node *config,
					const char *default_hostname);
	/* Allocate a new authentication state */
	int			(*init_authstate)(mon_auth_state *state);
	/* Perform next authentication step */
	int			(*state_step)(mon_auth_state *auth,
					void *in_data, size_t in_len);

	/**** Methods & fields above this line should be exactly the same in
	 * the client and the server module for optimization purposes *****/
} mon_auth_module_client;

Authentication module descriptor for the client side.

mon_module header;the generic mon_module_header.
unsigned int strength;strength of the authentication method.
init_creds ()credential initialization method.
init_authstate ()authentication state initialization method.
state_step ()performs an authentication step.

MON_AUTH_MODULE_CLIENT()

#define     MON_AUTH_MODULE_CLIENT(desc)

Macro to export a client-side authentication module descriptor.

desc :the name of a mon_auth_module_client descriptor.

MON_SYMBOL_AUTH_CLIENT

#define MON_SYMBOL_AUTH_CLIENT	MON_MODSYM(mon_module_auth_client)

Symbol name of the client-side authentication module descriptor.


mon_auth_module_server

typedef struct {
	mon_module		header;

	unsigned int		strength;

	/* Initialize authentication credentials */
	int			(*init_creds)(mon_auth_creds *creds,
					const mon_cfg_node *config,
					const char *default_hostname);
	/* Initialize an authentication state */
	int			(*init_authstate)(mon_auth_state *state);
	/* Perform next authentication step */
	int			(*state_step)(mon_auth_state *auth,
					void *in_data, size_t in_len);

	/**** Methods & fields above this line should be exactly the same in
	 * the client and the server module for optimization purposes *****/

	/* Get authenticated user ID */
	char			*(*auth_id)(mon_auth_state *state);
	/* Get requested user ID */
	char			*(*user_id)(mon_auth_state *state);
	/* Delegate credentials presented by the peer */
	mon_auth_creds		*(*delegate)(mon_auth_creds *creds,
					const char *server_name,
					const char *service_name);
} mon_auth_module_server;

Authentication module descriptor for the server side.

mon_module header;the generic mon_module_header.
unsigned int strength;strength of the authentication method.
init_creds ()credential initialization method.
init_authstate ()authentication state initialization method.
state_step ()performs an authentication step.
auth_id ()retrieves the requested authorization ID from a completed authentication state.
user_id ()retrieves the authenticated user ID from a completed authentication state.
delegate ()delegetes credentials.

MON_AUTH_MODULE_SERVER()

#define     MON_AUTH_MODULE_SERVER(desc)

Macro to export a server-side authentication module descriptor.

desc :the name of a mon_auth_module_server descriptor.

MON_SYMBOL_AUTH_SERVER

#define MON_SYMBOL_AUTH_SERVER	MON_MODSYM(mon_module_auth_server)

Symbol name of the server-side authentication module descriptor.


MON_AUTH_METH_TRANSPORT

#define MON_AUTH_METH_TRANSPORT	"Transport"

Defines the method name to indicate transport-level authentication.


MON_AUTH_PARAM_SERVER

#define MON_AUTH_PARAM_SERVER	"server_name"

Defines the configuration key name for the hostname to be used during authentication.


MON_AUTH_PARAM_SERVICE

#define MON_AUTH_PARAM_SERVICE	"service"

Defines the configuration key name for the service name.


mon_auth_client_register ()

int         mon_auth_client_register        (mon_module *module);

Registers a client-side authentication module.

module :a mon_auth_module_client to register.
Returns :0 if successful or an error code.

mon_auth_client_unregister ()

void        mon_auth_client_unregister      (mon_module *module);

Unregisters a client-side authentication module.

module :a mon_auth_module_client to unregister.

mon_auth_server_register ()

int         mon_auth_server_register        (mon_module *module);

Registers a server-side authentication module.

module :a mon_auth_module_server to register.
Returns :0 if successful or an error code.

mon_auth_server_unregister ()

void        mon_auth_server_unregister      (mon_module *module);

Unregisters a server-side authentication module.

module :a mon_auth_module_server to unregister.

mon_auth_client_methlist ()

const char** mon_auth_client_methlist       (void);

Retrieves the list of available client-side authentication methods. The returned list must be deallocated by passing it to mon_auth_methlist_free() when no longer needed.

Returns :the NULL-terminated list of authentication methods.

mon_auth_server_methlist ()

const char** mon_auth_server_methlist       (void);

Retrieves the list of available server-side authentication methods. The returned list must be deallocated by passing it to mon_auth_methlist_free() when no longer needed.

Returns :the NULL-terminated list of authentication methods.

mon_auth_methlist_free ()

void        mon_auth_methlist_free          (const char **methlist);

Deallocates an authentication method list that was obtained by either mon_auth_client_methlist() or mon_auth_server_methlist().

methlist :the method list to deallocate.

mon_auth_client_new ()

int         mon_auth_client_new             (const char *meth,
                                             const mon_cfg_node *config,
                                             const char *default_hostname,
                                             mon_cred_flags flags,
                                             mon_auth_creds **creds);

Creates a new client-side credential structure.

meth :name of the authentication method to use.
config :a mon_cfg_node containing configuration information for this method.
default_hostname :the host name the client wants to connect to.
flags :flags for the requested credentials.
creds :address to store the credentials if successful.
Returns :0 if successful or an error code.

mon_auth_server_new ()

int         mon_auth_server_new             (const char *meth,
                                             const mon_cfg_node *config,
                                             const char *default_hostname,
                                             mon_cred_flags flags,
                                             mon_auth_creds **creds);

Creates a new server-side credential structure.

meth :name of the authentication method to use.
config :a mon_cfg_node containing configuration information for this method.
default_hostname :the host name to use during authentication. Can be overridden in config.
flags :flags for the requested credentials.
creds :address to store the credentials if successful.
Returns :0 if successful or an error code.

mon_auth_creds

typedef struct {
	mon_auth_type		type;
	mon_module		*module;
	mon_cred_flags		flags;

	const mon_cfg_node	*config;
	char			*default_hostname;

	/* Method-private data */
	void			*method_data;
	GDestroyNotify		method_data_done;

	int			refcnt;
} mon_auth_creds;

Holds the credentials of an user.

mon_auth_type type;either MON_AUTH_CLIENT or MON_AUTH_SERVER.
mon_module *module;the authentication module this credential belongs to.
mon_cred_flags flags;credential flags.
const mon_cfg_node *config;configuration information for this method.
char *default_hostname;the host name to use during authentication. In case of server-side credentials, config may override default_hostname.
void *method_data;private data for the authentication method.
GDestroyNotify method_data_done;destructor for method_data.
int refcnt;reference count.

enum mon_cred_flags

typedef enum {
	MON_CRED_REQ_DELEGATION	= (1 << 0),
	MON_CRED_TRANSPORT	= (1 << 1)
} mon_cred_flags;

Credential flags.

MON_CRED_REQ_DELEGATIONif set, delegation is requested.
MON_CRED_TRANSPORTif set, this is a fake credential for transport-level authentication.

mon_auth_state

typedef struct {
	mon_auth_state_state	state;
	mon_auth_creds		*creds;
	mon_buffer		outbuf;

	/* Method-private data */
	void			*method_data;
	GDestroyNotify		method_data_done;
} mon_auth_state;

Contains information about the current state of the authentication process.

mon_auth_state_state state;one of the values of mon_auth_state_state.
mon_auth_creds *creds;the credentials used for authentication.
mon_buffer outbuf;the output buffer.
void *method_data;private data for the authentication method.
GDestroyNotify method_data_done;destructor for method_data.

enum mon_auth_state_state

typedef enum {
	MON_AUTH_CONTINUE,
	MON_AUTH_FINISHED
} mon_auth_state_state;

Authentication states.

MON_AUTH_CONTINUEcontinuation needed.
MON_AUTH_FINISHEDthe authentication process has finished.

mon_auth_creds_new ()

mon_auth_creds* mon_auth_creds_new          (mon_module *module,
                                             mon_auth_type type,
                                             const mon_cfg_node *config,
                                             const char *default_hostname,
                                             mon_cred_flags flags);

Allocates a new mon_auth_creds structure.

module :the module providing the authentication method. May be NULL for transport-level authentication.
type :either MON_AUTH_SERVER or MON_AUTH_CLIENT.
config :configuration information for the authentication method.
default_hostname :hostname to use during authentication.
flags :one or more of mon_cred_flags.
Returns :a new mon_auth_creds structure or NULL if there was not enough memory.

mon_auth_creds_done ()

void        mon_auth_creds_done             (mon_auth_creds *creds);

Decrements the reference count of a mon_auth_creds structure. If the reference count reaches zero, the credentials are deallocated.

creds :a mon_auth_creds.

mon_auth_creds_ref ()

void        mon_auth_creds_ref              (mon_auth_creds *creds);

Increments the reference count of a mon_auth_creds structure.

creds :a mon_auth_creds.

mon_auth_state_new ()

int         mon_auth_state_new              (mon_auth_creds *creds,
                                             mon_auth_state **state);

Allocates a new authentication state structure.

creds :credentials to use.
state :address to store the authentication state if successful.
Returns :0 if successful or an error code.

mon_auth_state_free ()

void        mon_auth_state_free             (mon_auth_state *state);

Deallocates a mon_auth_state structure.

state :a mon_auth_state.

mon_auth_state_step ()

int         mon_auth_state_step             (mon_auth_state *state,
                                             void *data,
                                             size_t len);

Performs an authentication step on a mon_auth_state structure.

state :a mon_auth_state.
data :data received from the peer.
len :length of data.
Returns :0 if successful or an error code. If successful, the response that has to be sent to the peer (if any) can be found in the outbuf field of state.

mon_auth_user_id ()

char*       mon_auth_user_id                (mon_auth_state *state);

Retrieves the authenticated user ID from a completed mon_auth_state.

state :a mon_auth_state.
Returns :the authenticated user ID. It must be freed by the caller using g_free().

mon_auth_auth_id ()

char*       mon_auth_auth_id                (mon_auth_state *state);

Retrieves the requested authorization ID from a completed mon_auth_state.

state :a mon_auth_state.
Returns :the authorization ID. It must be freed by the caller using g_free().

mon_auth_method ()

const char* mon_auth_method                 (mon_auth_state *state);

Retrieves the name of the authentication method used by a mon_auth_state.

state :a mon_auth_state.
Returns :the name of the authentication method.