#include <creds_store.h>
Data Fields | |
int(* | store_cred )(char *data_in_pem_format) |
store specified credential | |
char *(* | retrieve_cred )(char *config_name) |
retrieve current credential from credstore, if config_name match | |
int(* | set_cred_timeout )(int timeout) |
set a timeout after thich the credential is purged | |
int(* | delete_cred )() |
delete credential from credstore if it's not empty | |
char *(* | get_current_cred_configname )() |
return configuration name of the credential | |
int(* | set_current_cred_configname )(char *config_name) |
sets the current configuration name of the credstore | |
int(* | check_cred_is_available )(char *config_name) |
inform if specified credential is stored in credstore | |
char *(* | join_new_session )() |
uses a private session credstore instead of user credstore | |
int(* | exit_session )() |
end session credstore | |
int(* | join_default_user_session )() |
change user credstore after change UID |
This struct with function pointers allows applications to use different possible credstore implementations without change the code
int(* creds_store_funcs::store_cred)(char *data_in_pem_format) |
store specified credential
This functions stores the credential that user passes. If other credential is already stored, the new credential will overwrite it.
0 | success | |
-1 | failure |
char*(* creds_store_funcs::retrieve_cred)(char *config_name) |
retrieve current credential from credstore, if config_name match
This function returns credential from credstore if not empty and config_name match or config_name is NULL.
config_name | If parameter is NULL, this function returns the credential stored in the credstore (e.g. in Key Retention Service). If config_name is not NULL, first checks if config_name is the current configuration name in the credstore; returns NULL if they are different. |
credential | ||
NULL | if failure |
int(* creds_store_funcs::set_cred_timeout)(int timeout) |
set a timeout after thich the credential is purged
Sets a timeout (in seconds) after which the credential is purged from credstore. Zero value cancels the timeout.
timeout | The timeout in seconds. Zero value cancels the timeout. |
0 | success | |
-1 | failure |
int(* creds_store_funcs::delete_cred)() |
delete credential from credstore if it's not empty
Delete credential from credstore. Operation returns success (0) also if credstore is empty.
0 | success | |
-1 | failure |
return configuration name of the credential
This function returns the current configuration name of the key stored in credstore. If credstore is emtpy or operation faults, returns NULL.
If a credential is stored without specify a configuration name, configuration name is filled with the value "default".
configuration name | ||
NULL | failure or credstore is empty |
int(* creds_store_funcs::set_current_cred_configname)(char *config_name) |
sets the current configuration name of the credstore
This function set the new configuration name of the key stored in credstore. This function must be invoked after store a new credential.
In future releases, this function will be removed and config_name parameter will be pass to store_cred function.
config_name | the new configuration name |
0 | success | |
-1 | failure |
int(* creds_store_funcs::check_cred_is_available)(char *config_name) |
inform if specified credential is stored in credstore
This function is similar to retrieve_cred, but returns 1 if the credential to this config_name is available, 0 otherwise, instead of the credential/NULL.
config_name | If parameter is NULL, this function returns 1 if credstore is not empty. If config_name is not NULL, also checks if config_name is the current configuration name in the credstore; returns 0 if they are different. |
1 | available | |
0 | not available or failure |
char*(* creds_store_funcs::join_new_session)() |
uses a private session credstore instead of user credstore
By default, all functions operate over current user credstore. This function creates a new private credstore session and all successive new calls of the process and its childs will use this new credstore session. It's important to call exit_session at the end of the session (although current three implementations don't need it because session will be killed when the program ends).
In the krs/zkrs implementations, this function invokes the syscall to start a new session. In the uskeystore implementation, this functions starts a new daemon using a fork and defines an environment variable with the address of the socket. The function returns a environment value that the user must use with putenv, if launching other processes within the same session. KRS implementation returns nothing, but uskeystore needs to modify the environment because new session processes use XOS_CREDSTORE_SOCKET to localize the socket of the session credstore daemon and to read the cookie and file handler required to authenticate.
0 | success | |
-1 | failure |
int(* creds_store_funcs::exit_session)() |
end session credstore
If a user program calls join_new_session, it must call this function to end the session. In the KRS implementation this function do nothing (keystore session ends when the program that started the session ends). In the uskeystore implementation this function kills the session credstore daemon, but this call is not needed in Linux because join_new_session calls prctl to establish that the credstore daemon receives a SIGTERM when the parent process dies.
0 | success | |
-1 | failure |
change user credstore after change UID
If a program changes the UID, is must call this function to change to the new user credstore. In the krs and zkrs implementations, this function invokes the syscall to change the keystore. In the uskeystore implementation, it launches a new xos_credstored.
IMPORTANT: this function checks UID, not EUID!!!! But with krs/zkrs is required that programmer also change FSUID (file system UID) that initially has the same value that FSUID, because FSUID is used to assign the owner of the key and for qouta accounting. If program does not need to recover root privileges, best solution is to change UID and EUID. If program needs recover root privileges, best option is continue with EUID=0, and change UID with setreuid and FSUID with setfsuid.
0 | success | |
-1 | failure |