## CVM

# CVM Module Library

To write a module using the CVM module library, you must provide the following items:

`int cvm_module_init(void)`
  This function is called once when the CVM starts up.
`int cvm_module_lookup(void)`
  This function is used to retrieve the stored credentials for the named user. If the named user does not exist, this function must return `CVME_PERMFAIL` (value 100). Before this function is called, the input request is read and the account name is parsed into `cvm_account_name`, the domain name into `cvm_account_domain`, and the credentials are parsed into `cvm_credentials`.
`int cvm_module_authenticate(void)`
  The main authentication verification function. This function is not called when the module is operating in lookup mode. If authentication fails, this function must return `CVME_PERMFAIL` (value 100).
`int cvm_module_results(void)`
  This function is used to provide the lookup results to the client. All required facts must be set by this function: `cvm_fact_username`, `cvm_fact_userid`, `cvm_fact_groupid`, `cvm_fact_directory`, and `cvm_fact_shell`. The following facts may optional be set as well: `cvm_fact_realname`, `cvm_fact_groupname`, `cvm_fact_sys_username`, `cvm_fact_sys_directory`, and `cvm_fact_domain`. All of these will be sent to the client automatically by the invoking module framework, with the optional facts being sent only if they have been set. If any other facts are to be returned to the client, send them in this function with `cvm_module_fact_str(unsigned number, const char* data)` or `cvm_module_fact_uint(unsigned number, unsigned data)`.
`void cvm_module_stop(void)`
  This routine is called once when the CVM is shut down.

If any function fails due to a temporary error (read error, out of memory, connection failed, etc), it must return a non-zero error code (other than `CVME_PERMFAIL`). Otherwise, return zero.

The credentials sent from the client are accessable through the global `cvm_credentials` array (type `str`), which is indexed by the credential type number.

NOTE: The functions supplied by the module must never exit except on fatal errors. If any memory is allocated in the course of processing a request, it must either be freed or reallocated on the next invocation.

Each module will implement at least one type of credential validation (ie plain text, CRAM, etc). Modules are not obligated to implement multiple types of validation, but may do so by examinimg which types of credentials are present in the input. The invoker will choose which modules to invoke depending on what type of credentials it needs validated.