|
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
|
This file should be included by any application that uses libxos-credagent and by credagent/creduiagent modules.
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).
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:
-
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.
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.
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");