xos_getcred.h File Reference

libxosgetcred interface More...

Go to the source code of this file.

Functions

char * xos_getcred (char *configuration_name)
 get credential from credstore if available; otherwise invoke runcredagent to get it.
void xos_delcred (char *credential, char clear_credstore)
 clear and delete credential; optionally, purge delete from credstore


Detailed Description

libxosgetcred interface

This file should be included by any application that use libxosgetcred


Function Documentation

void xos_delcred ( char *  credential,
char  clear_credstore 
)

clear and delete credential; optionally, purge delete from credstore

Parameters:
[in] credential the credential as returned by xos_getcred. This parameter may be NULL, if the only purpose of the call is clear the credstore.
[in] clear_credstore if this parameter is not zero, then clear current content of credstore.
Return values:
This function does not return any value.
This auxiliar function fill with zeroes the credential and then delete it. This function also allows to delete the current credential stored in credstore (this functionality does not need the parameter credential, because credstore only store one credential)

char* xos_getcred ( char *  configuration_name  ) 

get credential from credstore if available; otherwise invoke runcredagent to get it.

Parameters:
[in] configuration_name the configuration name used to obtain the credential. If NULL retrieve the configuration present in credstore (if any) without check the configuration name. If NULL and credstore is empty, use "default" configuration.
Return values:
string with the credential
NULL if failure
This function is used to provide a single sign-on to applications. When a application invokes this function, library first searchs the credential in credstore. If credstore is not empty, checks if configuration_name is the same configuration_name that was specified when current stored credential was obtained. If names matchs, returns the credential. Also return the stored credential if configuration_name is NULL. If credstore is empty or configuration names don't match, runcredagent is called with the configuration name as parameter. Runcredagent use configuration_name to known how to get the credential (if NULL, use "default" configuration). Runcredagent store the obtained credential in credstore and this function returns it to application.

Runcredagent executable is not part of libxos_getcred. Package startxtreemos provides a implementation of runcredagent but other implementations are possible. These are the requirements that runcredagent must obey: -Application receives two parameters: "-l" and "-c <configuration_name>" -Application must store the retrieved credential using libcredstore

A credential may be present in credstore after a previous call to runcredagent invoked from this function, but other cause is that user manually invoked startxtreemos or startxtreemos-ams. A third possibility is that user invokes libcredstore or some of its utilities to store a arbitrary content in credstore. This implies that is not guaranteed that credential stored in credstore is good in all cases (e.g. a malicious Trojan may replace the credential if running with the same UID than user applications).

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).


Generated on Fri Dec 18 14:33:42 2009 for libxos-getcred by  doxygen 1.5.1