CVM: Credential Validation Module

CVM Protocol Version 1 Description
CVM Protocol Version 2 Description
CVM Credential Definitions
CVM Fact Definitions
CVM Version 1 Client Library
CVM Version 2 Client Library
CVM Module Library
CVM SASL Library
CVM Error Values
CVM Design Rationale

The cvm-checkpassword Program
The cvm-testclient Program
The cvm-benchclient Program

The cvm-unix Module
The cvm-pwfile Module
The cvm-vmailmgr Module
The cvm-qmail Module
The cvm-mysql Module
The cvm-pgsql Module
The cvm-chain Module

CVM is a framework for validating a set of credentials against a database using a filter program. The modules act as a filter, taking a set of credentials as input and writing a set of facts as output if those credentials are valid. Optional input is given to the module through environment variables.

Some of the ideas for CVM came from experience with PAM (pluggable authentication modules), the checkpassword interface used by qmail-pop3d, and the "authmod" interface used by Courier IMAP and POP3. This framework places fewer restrictions on the invoking client than checkpassword does, and is much simpler to implement on both sides than PAM and the authmod framework.

Contact Modes

CVM modules may be contacted by one of three modes:

  1. Command execution: Use a module name of cvm-command:/path/to/command. The cvm-command: prefix is optional.
  2. UNIX (or local) domain socket: Use a module name of cvm-local:/path/to/socket.
  3. UDP: Use a module name of cvm-udp:hostname:port.

Modules may be chained in the client. To do so, specify the list of modules separated by a comma. For example:

cvm-local:/path/to/socket,cvm-command:/path/to/module

The first module to either report success, a temporary failure, or permanent failure with an in-scope result terminates the chain.

Module Invocation

CVM modules are invoked using a similar syntax to the above:

  1. UNIX (or local) domain server: Use a command-line argument of cvm-local:/path/to/socket. If $CVM_SOCKET_MODE is set, the created socket will have this mode (in octal, defaults to 777). If $CVM_SOCKET_OWNER or $CVM_SOCKET_GROUP are set, the created socket will have its UID/GID set appropriately. The module will wait a maximum of 1000ms for complete input to be received from the client or to completely send the response. This value may be overridden by $CVM_IO_TIMEOUT.
  2. UDP socket server: Use a command-line argument of cvm-udp:hostname:port. The hostname argument specifies the IP to bind the socket to. Normally this will be 0 to bind to all IPs.

If $CVM_LOOKUP_SECRET is set, the module operates in "lookup mode". In this mode, the authentication function provided by the module will not be called. Instead, the module library will handle authentication internally, before the lookup happens. If the secret is empty, the module will expect no credentials to be passed to the module, otherwise one must be passed and it must match the secret.