CVM

CVM Version 2 Client Library

The CVM version 2 client library defines the following functions:

int cvm_client_authenticate(const char* module, unsigned count, struct cvm_credential* credentials)

This is the main entry point to the library. Set up the credentials as an array and call cvm_client_authenticate. The credentials must contain a CVM_CRED_ACCOUNT entry. The function will return 0 if authentication succeeded and an error code otherwise. The credentials have the following structure:

struct
cvm_credential { unsigned type; str value; }

If $CVM_LOOKUP_SECRET is set, and no CVM_CRED_SECRET credential is present in the credentials, its value is added to the set of outgoing credentials automatically to assist with the workings of lookup modules.

If authentication succeeds, this routine automatically retrieves cvm_fact_username, cvm_fact_userid, cvm_fact_groupid, cvm_fact_directory, and cvm_fact_shell. cvm_fact_realname, cvm_fact_groupname, cvm_fact_sys_username, cvm_fact_sys_directory, and cvm_fact_domain are also set if they were present in the results.

The client should change directory to the named home directory and drop root priviledges as soon as possible after successful authentication. Where reasonable, the client should also chroot to the directory for added protection.

A random tag is added to the transmitted data to prevent spoofing when a remote module is being contacted (UDP mode). Its size is set by $CVM_RANDOM_BYTES, and defaults to 8 bytes.

int cvm_client_split_account(str* account, str* domain)

This function splits a domain name, if present, from of the account name. It searches for the last instance of any character from cvm_client_account_split_chars in account. If found, domain is replaced with the portion of account following that character, and account is truncated before that character. cvm_client_account_split_chars defaults to "@", which may be overridden by either setting it to a different string from the client program or by setting the $CVM_ACCOUNT_SPLIT_CHARS environment variable. Setting it to an empty string will effectively prevent parsing of the account name.

int cvm_client_authenticate_password(const char* module, const char* account, const char* domain, const char* password, int split_account)

This is a convenience wrapper function for the cvm_authenticate and cvm_split_account functions. The domain and password credentials are only sent if they are not NULL and not empty.

int cvm_client_fact_str(unsigned number, const char** data)

Retrieves a fact from the data returned by the module as a NUL-terminated string. Returns zero if the fact was present, and CVME_NOFACT otherwise. Successive calls to this function with the same number return subsequent facts if more than one instance of the fact was present.

int cvm_client_fact_uint(unsigned number, unsigned long* data)

Retrieves a fact from the data returned by the module as an unsigned integer. Returns zero if the fact was present and was an unsigned integer. Returns CVME_BAD_MODDATA if the fact was present but was not an unsigned integer. Successive calls to this function with the same number return subsequent facts if more than one instance of the fact was present.

const char* cvm_client_ucspi_domain(void)

Retrieves the UCSPI local domain from the environment variable named ${PROTO}LOCALHOST. Use this as the domain paramenter to cvm_authenticate in all UCSPI servers that have no other means of determining the domain name.

int cvm_client_setenv(void)

Exports the following environment variables based on their associated CVM fact. If the fact was optional and was not present in the results from the module, the environment variable will not be set or unset.

Variable	CVM Fact
USER	CVM_FACT_USERNAME
UID	CVM_FACT_USERID
GID	CVM_FACT_GROUPID
NAME	CVM_FACT_REALNAME
HOME	CVM_FACT_DIRECTORY
SHELL	CVM_FACT_SHELL
GROUP	CVM_FACT_GROUPNAME
DOMAIN	CVM_FACT_DOMAIN
MAIL	CVM_FACT_MAILBOX
MAILBOX	CVM_FACT_MAILBOX
MAILDIR	CVM_FACT_MAILBOX

int cvm_client_setugid(void)

Calls chdir, setgid and setuid with appropriate values based on the data returned from the authentication. Returns zero if any of the calls failed.