## CVM

# CVM Version 1 Client Library

The CVM version 1 client library defines the following functions:

`int cvm_client_authenticate(const char* module, const char* account, const char* domain, const char** credentials, int parse_account)`

  This is the main entry point to the library. Simply set up the credentials as an array with a trailing NULL pointer and call `authenticate`. If the `domain` parameter is a NULL pointer, it will be treated as an empty string; no other parameter may be NULL. The function will return 0 if authentication succeeded and an error code otherwise.

  If `parse_account` is true then `account` is searched for the last instance of any character from `cvm_client_account_split_chars`. 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, no matter what `parse_account` may be set to.

  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.

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