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_SERVER`	server-side authenticator
`MON_AUTH_CLIENT`	client-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_DELEGATION`	if set, delegation is requested.
`MON_CRED_TRANSPORT`	if 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_CONTINUE`	continuation needed.
`MON_AUTH_FINISHED`	the 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.