File: cvm.html

package info (click to toggle)
cvm 0.97-0.1
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 1,036 kB
  • sloc: ansic: 4,065; sh: 2,758; makefile: 235; sql: 15
file content (103 lines) | stat: -rw-r--r-- 4,019 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
<html>
<body>
<h1>CVM: Credential Validation Module</h1>

<p><a href="protocol-1.html">CVM Protocol Version 1 Description</a>
<br><a href="protocol-2.html">CVM Protocol Version 2 Description</a>
<br><a href="credentials.html">CVM Credential Definitions</a>
<br><a href="facts.html">CVM Fact Definitions</a>
<br><a href="v1client.html">CVM Version 1 Client Library</a>
<br><a href="v2client.html">CVM Version 2 Client Library</a>
<br><a href="module.html">CVM Module Library</a>
<br><a href="sasl.html">CVM SASL Library</a>
<br><a href="errors.html">CVM Error Values</a>
<br><a href="rationale.html">CVM Design Rationale</a>
</p>

<p><a href="cvm-checkpassword.html">The cvm-checkpassword Program</a>
<br><a href="cvm-testclient.html">The cvm-testclient Program</a>
<br><a href="cvm-benchclient.html">The cvm-benchclient Program</a>
</p>

<p><a href="cvm-unix.html">The cvm-unix Module</a>
<br><a href="cvm-pwfile.html">The cvm-pwfile Module</a>
<br><a href="cvm-vmailmgr.html">The cvm-vmailmgr Module</a>
<br><a href="cvm-qmail.html">The cvm-qmail Module</a>
<br><a href="cvm-mysql.html">The cvm-mysql Module</a>
<br><a href="cvm-pgsql.html">The cvm-pgsql Module</a>
<br><a href="cvm-chain.html">The cvm-chain Module</a>
</p>

<hr>

<p>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.</p>

<p>Some of the ideas for CVM came from experience with PAM (pluggable
authentication modules), the <a
http="http://cr.yp.to/checkpwd.html">checkpassword</a> interface used
by <tt>qmail-pop3d</tt>, 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.</p>

<h2>Contact Modes</h2>

<p>CVM modules may be contacted by one of three modes:</p>

<ol>

<li>Command execution: Use a module name of
<tt>cvm-command:/path/to/command</tt>.  The <tt>cvm-command:</tt>
prefix is optional.</li>

<li>UNIX (or local) domain socket:  Use a module name of
<tt>cvm-local:/path/to/socket</tt>.</li>

<li>UDP:  Use a module name of <tt>cvm-udp:hostname:port</tt>.</li>

</ol>

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

<pre>cvm-local:/path/to/socket,cvm-command:/path/to/module</pre>

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

<h2>Module Invocation</h2>

<p>CVM modules are invoked using a similar syntax to the above:</p>

<ol>

<li>UNIX (or local) domain server: Use a command-line argument of
<tt>cvm-local:/path/to/socket</tt>.  If <tt>$CVM_SOCKET_MODE</tt> is
set, the created socket will have this mode (in octal, defaults to
<tt>777</tt>).  If <tt>$CVM_SOCKET_OWNER</tt> or
<tt>$CVM_SOCKET_GROUP</tt> 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 <tt>$CVM_IO_TIMEOUT</tt>.</li>

<li>UDP socket server: Use a command-line argument of
<tt>cvm-udp:hostname:port</tt>.  The <tt>hostname</tt> argument
specifies the IP to bind the socket to.  Normally this will be
<tt>0</tt> to bind to all IPs.</li>

</ol>

<p>If <tt>$CVM_LOOKUP_SECRET</tt> 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, <em>before</em> 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.</p>

</body>
</html>