xos_credagent.h File Reference

libxoscredagent interface More...

Go to the source code of this file.

Typedefs

typedef void * CREDAGENT_HANDLE
typedef struct creduiagent_handle * CREDUIAGENT_HANDLE

Functions

char * xos_credagent_getcred (char *configuration)
 get credential invoking the credagent module associated to configuration_name to get it.
int xos_setconfigenv (char *config_name, char *section)
 utility function to set configuration parameters from a section in environment variables.
char ** xos_readconfigsections (char *config_name)
 utility function to get configuration sections
CREDAGENT_HANDLE xos_credagentso_instance (char *config_name, char **name)
 function to obtain a handle needed to use libxos-credagent API for credagent modules
void xos_credagentso_destroy (CREDAGENT_HANDLE handle)
 function to freed the handle obtained with xos_credagentso_instance when not needed anymore.
char * xos_credagentso_getparameter (CREDAGENT_HANDLE handle, char *key)
 get a parameter value from "credagent" section in configuration file
CREDUIAGENT_HANDLE xos_creduiagent_instance (char *config_name, char **name)
 function to obtain a handle needed to use libxos-credagent API for interaction with the creduiagent module specified in the credential configuration file.
void xos_creduiagent_destroy (CREDUIAGENT_HANDLE handle)
 function to freed the handle obtained with xos_creduiagentso_instance when not needed anymore.
int xos_creduiagent_ask_login_password (CREDUIAGENT_HANDLE handle, char *message, char **login, char **password, int max_length, char retry)
 Use creduiagent module to ask user a login and password or a password only.
int xos_creduiagent_ask_login_pin (CREDUIAGENT_HANDLE handle, char *message, char **login, char **pin, int length, char retry)
 Use creduiagent module to ask user a PIN number and (optionally) a username.
int xos_creduiagent_ask_code (CREDUIAGENT_HANDLE handle, char *message, char **code, int max_length, char retry)
 Use creduiagent module to ask a text to user. This text is not asked as a password: the user may see what he/she type.
int xos_creduiagent_ask_confirmation (CREDUIAGENT_HANDLE handle, char *message)
 Ask confirmation to user.
int xos_creduiagent_ask_confirmation_pin (CREDUIAGENT_HANDLE handle, char *message, char *pin, char *puk, int max_length_pin, int max_length_puk, int allowed_retries)
int xos_creduiagent_show_error (CREDUIAGENT_HANDLE handle, char *message)
 Show a error message to user using the specified creduiagent.
char * xos_creduiagent_getparameter (CREDUIAGENT_HANDLE handle, char *key)
 get a parameter value from "creduiagent" section in configuration file
void * xos_creduiagent_get_func (CREDUIAGENT_HANDLE handle, char *name)
 get a function pointer to a method implemented in creduiagent module


Detailed Description

libxoscredagent interface

This file should be included by any application that uses libxos-credagent and by credagent/creduiagent modules.


Function Documentation

char* xos_credagent_getcred ( char *  configuration  ) 

get credential invoking the credagent module associated to configuration_name to get it.

Parameters:
[in] configuration_name the configuration name used to obtain the credential. Library searches /etc/xos/creds/<configuration_name>.conf to known the credagent module to use.
Return values:
string with the credential. This string must be freed by caller.
NULL if failure
This function is used to provide a plug-able, modular system to get credentials. Library objective is to allow administrators to change the method used by applications to get the credential to authenticate in a Single Sign-On (SSO) infrastructure, without source code modification.

When a application invokes this function, library searches file /etc/xos/creds/<configuration_name>.conf to know the credagent module needed to get the credential. Module is load with dlopen and module function credagent_getcred is called.

Note that /etc/xos/creds directory is protected: only root user or users member of group "credagent" are allowed to access this directory. This implies that only applications running as root or with SGID "credagent" may call this function. This is not a problem, because final user applications should not use libxos-credagent but libxos-getcred, that invokes a SGID wrapper, runcredagent, that calls this function. In XtreemOS, runcredagent is a link to startxtreemos.

In XtreemOS, credential is expected to be a private key and X.509 certificate in PEM format, but this function does not check it, because other applications may use the library to use other type of credentials (e.g. passphrases).

void xos_credagentso_destroy ( CREDAGENT_HANDLE  handle  ) 

function to freed the handle obtained with xos_credagentso_instance when not needed anymore.

Parameters:
[in] handle obtained from a previous call to xos_credagentso_instance
Return values:
this function does not return anything.
Any credagent module that use libxos-credagent API, must first obtain a handle with xos_credagentso_instance and use this handle with the other functions. When handler is not needed anymore, module must call this function to free resources.

char* xos_credagentso_getparameter ( CREDAGENT_HANDLE  handle,
char *  key 
)

get a parameter value from "credagent" section in configuration file

Parameters:
[in] handle of credagent module. This handle may be obtained invoking xos_credagentso_instance and must be destroyed when not needed anymore with xos_credagentso_destroy.
[in] key the name of the parameter to retrieve from credagent section.
Return values:
string value of the requested parameter on success. The value must be freed by caller when not needed anymore.
NULL on error
This function is used by credagent modules to obtain a credagent parameter from credential configuration name.

CREDAGENT_HANDLE xos_credagentso_instance ( char *  config_name,
char **  name 
)

function to obtain a handle needed to use libxos-credagent API for credagent modules

Parameters:
[in] config_name the configuration name specified by application when invoked xos_credagent_getcred and received by module as parameter in credagent_getcred function.
[in] name is a pointer to string, that will be filled by the library with the name of the credagent module. This string must be freed by the caller when not needed anymore. This parameter may be NULL if module does not need this information.
Return values:
handle that must be used with most libxos_credagent API calls. Handler should be freed with xos_credagentso_destroy when not needed anymore.
This function is needed by all credagent modules, because the obtained handler is mandatory is most libxos-credagent calls. Handler must be freed using xos_credagentso_instance when not needed anymore.

int xos_creduiagent_ask_code ( CREDUIAGENT_HANDLE  handle,
char *  message,
char **  code,
int  max_length,
char  retry 
)

Use creduiagent module to ask a text to user. This text is not asked as a password: the user may see what he/she type.

Parameters:
[in] handle of creduiagent module. This handle may be obtained invoking xos_creduiagent_instance and must be destroyed when not needed anymore with xos_creduiagent_destroy. Handle may be also received as parameter in a creduiagent modulue function. In last case, don't destroy the handle, because handle owner is the caller, not the creduiagent module.
[in] message the informative message to show user when asking him the code. Pass NULL if you want that the creduiagent shows its default message (perhaps a message specified in the configuration file)
[in] code a pointer to a string that will be filled with the text provided by user. This string must be freed by the caller.
[in] length the maximum number of characters of the code. Warning: Some creduiagent modules may ignore this parameter. Consider this value as a hint, not as a validation.
[in] retry pass 1 in this parameter if this is invocation is a retry after user provided a invalid value, pass 0 otherwise. This is only a hint, some creduiagent modules may use this value, others may ignore it.
Return values:
0 on success
-1 on error
This function

int xos_creduiagent_ask_confirmation ( CREDUIAGENT_HANDLE  handle,
char *  message 
)

Ask confirmation to user.

Parameters:
[in] handle of creduiagent module. This handle may be obtained invoking xos_creduiagent_instance and must be destroyed when not needed anymore with xos_creduiagent_destroy. Handle may be also received as parameter in a creduiagent modulue function. In last case, don't destroy the handle, because handle owner is the caller, not the creduiagent module.
[in] message the informative text to display user when asking user confirmation. Pass NULL if you want that the creduiagent shows its default message (perhaps a message specified in the configuration file)
Return values:
0 on user accept
-1 on error or on user rejection.
This function is used to get authorization from user to do anything. For example, some credagent modules using this call to request confirmation from user that he really want to use a credential, to avoid that a malicious application stole a credential without user's knowledge.

int xos_creduiagent_ask_login_password ( CREDUIAGENT_HANDLE  handle,
char *  message,
char **  login,
char **  password,
int  max_length,
char  retry 
)

Use creduiagent module to ask user a login and password or a password only.

Parameters:
[in] handle of creduiagent module. This handle may be obtained invoking xos_creduiagent_instance and must be destroyed when not needed anymore with xos_creduiagent_destroy. Handle may be also received as parameter in a creduiagent modulue function. In last case, don't destroy the handle, because handle owner is the caller, not the creduiagent module.
[in] message the informative text to display user when asking login/password. Pass NULL if you want that the creduiagent shows its default message (perhaps a message specified in the configuration file)
[in] login pointer to a string that (if not NULL) will be filled with the username typed by the user. This string must be freed by the caller when not needed anymore. If parameter is NULL, only PIN number is requested. If (*login) is not NULL, the value is toked as the initial value of login, but user may change the value.
[in] pin pointer to a string that will be filled with the password typed by the user. This string must be freed by the caller when no needed anymore.
[in] length the suggested maximum length of the password. Warning: Some creduiagent modules may ignore this parameter. Consider this value as a hint, not as a validation.
[in] retry pass 1 in this parameter if this is invocation is a retry after user provided a bad password, pass 0 otherwise. This is only a hint, some creduiagent modules may use this value, others may ignore it.
Return values:
0 on success -1 on error
This function is used to ask a username and password (or only the password if parameter login is NULL). A creduiagent module may not interact with a user actually, and for example read this values from configuration file.

int xos_creduiagent_ask_login_pin ( CREDUIAGENT_HANDLE  handle,
char *  message,
char **  login,
char **  pin,
int  length,
char  retry 
)

Use creduiagent module to ask user a PIN number and (optionally) a username.

Parameters:
[in] handle of creduiagent module. This handle may be obtained invoking xos_creduiagent_instance and must be destroyed when not needed anymore with xos_creduiagent_destroy. Handle may be also received as parameter in a creduiagent modulue function. In last case, don't destroy the handle, because handle owner is the caller, not the creduiagent module.
[in] message the informative text to display user when asking the PIN. Pass NULL if you want that the creduiagent shows its default message (perhaps a message specified in the configuration file)
[in] login pointer to a string that (if not NULL) will be filled with the username typed by the user. This string must be freed by the caller when not needed anymore. If parameter is NULL, only PIN number is requested. If (*login) is not NULL, the value is toked as the initial value of login, but user may change the value.
[in] pin pointer to a string that will be filled with the PIN number typed by the user. This string must be freed by the caller when no needed anymore.
[in] length the number of PIN digits. Warning: Some creduiagent modules may ignore this parameter. Consider this value as a hint, not as a validation.
[in] retry pass 1 in this parameter if this is invocation is a retry after user provided a bad password, pass 0 otherwise. This is only a hint, some creduiagent modules may use this value, others may ignore it. Values 2 and 3 are special: value 2 is received after bad PIN if no more PIN tries are allowed and a full password is required as PUK. Value 3 is the same than value 2, except that authentication was rejected without checking PIN because retry limit was reached before.
Return values:
0 on success -1 on error
This function is equivalent to xos_creduiagent_ask_password, but here password is a PIN number and length is the number of digits. Some creduiagent modules may use the same implementation for the two functions, that is, ignore in this call that the PIN is a numeric password with a fixed length. Consider this as a hint, not as a validation.

void xos_creduiagent_destroy ( CREDUIAGENT_HANDLE  handle  ) 

function to freed the handle obtained with xos_creduiagentso_instance when not needed anymore.

Parameters:
[in] handle obtained from a previous call to xos_creduiagentso_instance
Return values:
this function does not return anything.
Any credagent module that use libxos-credagent API to interact with the creduiagent specified in the credential configuration name, must first obtain a handle with xos_creduiagent_instance and use this handle with the other functions. When handler is not needed anymore, module must call this function to free resources.

Warning: creduiagent modules receives a CREDUIAGENT_HANDLE in each call, but they must not freed the handler using this function, because that handler is owned by credagent module, not by creduiagent module.

void* xos_creduiagent_get_func ( CREDUIAGENT_HANDLE  handle,
char *  name 
)

get a function pointer to a method implemented in creduiagent module

Parameters:
[in] handle of creduiagent module. This handle may be obtained invoking xos_creduiagent_instance and must be destroyed when not needed anymore with xos_creduiagent_destroy. Handle may be also received as parameter in a creduiagent modulue function. In last case, don't destroy the handle, because handle owner is the caller, not the creduiagent module.
[in] the name of the function to retrieve
Return values:
fuction pointer to the requested call on success
NULL on error
This helper function allows credagent module programmers to use functions provided by a creduiagent module that are not standard and therefore the library does not define specific API to use them.

char* xos_creduiagent_getparameter ( CREDUIAGENT_HANDLE  handle,
char *  key 
)

get a parameter value from "creduiagent" section in configuration file

Parameters:
[in] handle of creduiagent module. This handle may be obtained invoking xos_creduiagent_instance and must be destroyed when not needed anymore with xos_creduiagent_destroy. Handle may be also received as parameter in a creduiagent modulue function. In last case, don't destroy the handle, because handle owner is the caller, not the creduiagent module.
[in] key the name of the parameter to retrieve from creduiagent section.
Return values:
string value of the requested parameter on success. The value must be freed by caller when not needed anymore.
NULL on error
This function is used to obtain a creduiagent parameter from credential configuration name. Normally, this function is used by creduiagent modules using the handle received as parameter in the call they provides, not by credagent modules. Indeed, this is the only libxos-credagent function that is intended to creduiagent modules.

CREDUIAGENT_HANDLE xos_creduiagent_instance ( char *  config_name,
char **  name 
)

function to obtain a handle needed to use libxos-credagent API for interaction with the creduiagent module specified in the credential configuration file.

Parameters:
[in] config_name the credential configuration file used to know the creduiagent module is /etc/xos/creds/<config_name>.conf
[in] name is a pointer to string, that will be filled by the library with the name of the creduiagent module. This string must be freed by the caller when not needed anymore. This parameter may be NULL if module does not need this information.
Return values:
handle that must be used with most libxos_creduiagent API calls. Handler should be freed with xos_creduiagent_destroy when not needed anymore.
This function is needed by every credagent module that needs to interact with the creduiagent module specified in the credential configuration name, because the obtained handler is mandatory is most related calls. Handler must be freed using xos_credauigentso_instance when not needed anymore.

int xos_creduiagent_show_error ( CREDUIAGENT_HANDLE  handle,
char *  message 
)

Show a error message to user using the specified creduiagent.

Parameters:
[in] handle of creduiagent module. This handle may be obtained invoking xos_creduiagent_instance and must be destroyed when not needed anymore with xos_creduiagent_destroy. Handle may be also received as parameter in a creduiagent modulue function. In last case, don't destroy the handle, because handle owner is the caller, not the creduiagent module.
[in] message the string with the error message to be showed.
Return values:
0 on success
-1 on error
This function is used to notify user a error. Actually, creduiagent module may not display any message: a creduiagent module may choose for example log the error in a file or ignore the message.

char** xos_readconfigsections ( char *  config_name  ) 

utility function to get configuration sections

Parameters:
[in] config_name the configuration name used to obtain the credential and read configuration parameters. Library parses file /etc/xos/creds/<configuration_name>.conf
Return values:
a array of char * with the section names. This data must be freed by the caller.
-NULL on error.
This helper function allows applications to get sections names from a credential configuration file. Sections general, credagent and creduiagent are used by the library, but application may use its own sections to get configuration data. For example, startxtreemos applications use "xtreemfs" section to obtain configuration about mounting a XtreemFS volume when running. Application may use xos_setconfigenv to read the parameters for a particular section.

int xos_setconfigenv ( char *  config_name,
char *  section 
)

utility function to set configuration parameters from a section in environment variables.

Parameters:
[in] config_name the configuration name used to obtain the credential and read configuration parameters. Library parses file /etc/xos/creds/<configuration_name>.conf
[in] section the name of the section in configuration file to parse
Return values:
zero on success.
-1 on error.
This helper function allows applications to read parameters from a credential configuration file. Sections general, credagent and creduiagent are used by the library, but application may use its own sections to get configuration data. For example, startxtreemos applications use "xtreemfs" section to obtain configuration about mounting a XtreemFS volume when running. Afer this call, application may read values ussing getenv("key");


Generated on Wed Jun 30 06:08:27 2010 for libxos-credagent by  doxygen 1.5.9