CVM

CVM Protocol

Input

Input to the authenticator is as follows. All items are NUL-terminated strings. The total length of the input must not exceed 512 bytes.

  1. Account identifier (ie user name).
  2. List of credentials.

The credentials consist of one of the following:

Each module will implement a single type of credential validation. The invoker will choose which modules to invoke depending on what type of credentials it needs validated.

Environment Variables

The following environment variables may be set by the invoker:

SERVICE
The service name, to be used (for example) by PAM modules to determine which configuration file to load.

Output

If authentication succeeds, the output from the module is a single byte success code followed by a list of facts about the authenticator. The total size of the output must not exceed 512 bytes.

If authentication succeeded, the code byte will be 0. If the credentials are accepted by this module, but are not valid, the code will be 100 (permanent failure). Any other code indicates a temporary error.

Each fact consists of a single byte identifying what type of fact is being reported, followed by a sequence of zero or more non-zero bytes, terminated by a single NUL byte. A second NUL byte follows the last fact and indicates the end of the list.

All predefined facts use values less than 128. All other fact values are reserved for local or experimental use. Facts marked as "required" must be present at least once in the result. Facts marked as "multiple" may be present more than once; all other facts must be present at most once. Facts may be reported in any order, and that order carries no significance.

Code Considerations

The module must report a temporary error if it detects malformed input (too few credentials, etc.). Extra input is a fault in the invoking code, and may produce undefined results.

An executable module must exit 0 if authentication succeeds. Non-zero exit codes from an executable module should be treated as a temporary error.

The invoker of an executable module must assume a temporary error if the module either fails to completely read its input or produces incomplete output, even if the module exits without error.

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