## CVM

## CVM Version 2 Proposed Protocol

# CVM Version 1 Protocol

## Input

Input to the authenticator is as follows. All items except the first, which is a single byte, are NUL-terminated strings. The total length of the input must not exceed 512 bytes.

1. Protocol number, 1.
2. Account name base (ie user name).
3. Account domain name.
4. List of credentials.
5. An empty string (ie a single NUL byte).

The credentials consist of one of the following:

- For plain login, the password.
- For APOP, the timestamp and MD5 digest.
- For CRAM-MD5 keyed hashing, as specified in RFC 2095, the challenge and MD5 digest.

## 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-NUL bytes, terminated by a single NUL byte. A second NUL byte follows the last fact and indicates the end of the list.

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

Note: for non-command modules, the invoker is NOT the CVM client. The CVM client has no control over the environment variables of non-command modules.

## Implementation Considerations

The module must report a temporary error if it detects malformed input (incorrect credentials, etc.). Extra data following the final NUL byte in the credentials is a fault in the invoking code, and must be rejected by the module. Similarly, extra data following the final NUL byte in the facts is a fault in the module code.

All data following an unsuccessful result status code must be ignored by the invoking code. Modules should not produce any facts when validation fails.

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.