/usr/share/doc/libcvm1-dev/v2client.html is in libcvm1-dev 0.96-1ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | <html>
<body>
<h2><a href="cvm.html">CVM</a></h2>
<h1>CVM Version 2 Client Library</h1>
<p>The CVM version 2 client library defines the following functions:</p>
<dl>
<dt><tt>int cvm_client_authenticate(const char* module, unsigned count,
struct cvm_credential* credentials)</tt> <dd><p>This is the main entry
point to the library. Set up the credentials as an array and call
<tt>cvm_client_authenticate</tt>. The credentials must contain a
<tt>CVM_CRED_ACCOUNT</tt> entry. The function will return 0 if
authentication succeeded and an <a href="errors.html">error code</a>
otherwise. The credentials have the following structure: <pre>struct
cvm_credential { unsigned type; str value; }</pre></p>
<p>If <tt>$CVM_LOOKUP_SECRET</tt> is set, and no
<tt>CVM_CRED_SECRET</tt> credential is present in the
<tt>credentials</tt>, its value is added to the set of outgoing
credentials automatically to assist with the workings of lookup
modules.</p>
<p>If authentication succeeds, this routine automatically retrieves
<tt>cvm_fact_username</tt>, <tt>cvm_fact_userid</tt>,
<tt>cvm_fact_groupid</tt>, <tt>cvm_fact_directory</tt>, and
<tt>cvm_fact_shell</tt>. <tt>cvm_fact_realname</tt>,
<tt>cvm_fact_groupname</tt>, <tt>cvm_fact_sys_username</tt>,
<tt>cvm_fact_sys_directory</tt>, and <tt>cvm_fact_domain</tt> are also
set if they were present in the results.</p>
<p>The client should change directory to the named home directory and
drop root priviledges as soon as possible after successful
authentication. Where reasonable, the client should also chroot to
the directory for added protection.</p>
<p>A random tag is added to the transmitted data to prevent spoofing
when a remote module is being contacted (UDP mode). Its size is set
by <tt>$CVM_RANDOM_BYTES</tt>, and defaults to 8 bytes.</p>
<dt><tt>int cvm_client_split_account(str* account, str* domain)</tt>
<dd><p>This function splits a domain name, if present, from of the
account name. It searches for the last instance of any character from
<tt>cvm_client_account_split_chars</tt> in <tt>account</tt>. If found,
<tt>domain</tt> is replaced with the portion of <tt>account</tt>
following that character, and <tt>account</tt> is truncated before that
character. <tt>cvm_client_account_split_chars</tt> defaults to
"<tt>@</tt>", which may be overridden by either setting it to a
different string from the client program or by setting the
<tt>$CVM_ACCOUNT_SPLIT_CHARS</tt> environment variable. Setting it to
an empty string will effectively prevent parsing of the account
name.</p>
<dt><tt>int cvm_client_authenticate_password(const char* module, const
char* account, const char* domain, const char* password, int
split_account)</tt> <dd><p>This is a convenience wrapper function for
the <tt>cvm_authenticate</tt> and <tt>cvm_split_account</tt> functions.
The <tt>domain</tt> and <tt>password</tt> credentials are only sent if
they are not <tt>NULL</tt> and not empty.</p>
<dt><tt>int cvm_client_fact_str(unsigned number, const char** data)</tt>
<dd><p>Retrieves a <a href="facts.html">fact</a> from the data returned
by the module as a NUL-terminated string. Returns zero if the fact was
present, and <tt>CVME_NOFACT</tt> otherwise. Successive calls to this
function with the same <tt>number</tt> return subsequent facts if more
than one instance of the fact was present.</p>
<dt><tt>int cvm_client_fact_uint(unsigned number, unsigned long*
data)</tt> <dd><p>Retrieves a <a href="facts.html">fact</a> from the
data returned by the module as an unsigned integer. Returns zero if the
fact was present and was an unsigned integer. Returns
<tt>CVME_BAD_MODDATA</tt> if the fact was present but was not an
unsigned integer. Successive calls to this function with the same
<tt>number</tt> return subsequent facts if more than one instance of the
fact was present.</p>
<dt><tt>const char* cvm_client_ucspi_domain(void)</tt> <dd><p>Retrieves
the UCSPI local domain from the environment variable named
<tt>${PROTO}LOCALHOST</tt>. Use this as the <tt>domain</tt> paramenter
to <tt>cvm_authenticate</tt> in all UCSPI servers that have no other
means of determining the domain name.</p>
<dt><tt>int cvm_client_setenv(void)</tt> <dd><p>Exports the following
environment variables based on their associated CVM fact. If the fact
was optional and was not present in the results from the module, the
environment variable will not be set or unset.</p>
<table border=1>
<tr> <th>Variable</th> <th>CVM Fact</th> </tr>
<tr> <td><tt>USER</tt></td> <td><tt>CVM_FACT_USERNAME</tt></td> </tr>
<tr> <td><tt>UID</tt></td> <td><tt>CVM_FACT_USERID</tt></td> </tr>
<tr> <td><tt>GID</tt></td> <td><tt>CVM_FACT_GROUPID</tt></td> </tr>
<tr> <td><tt>NAME</tt></td> <td><tt>CVM_FACT_REALNAME</tt></td> </tr>
<tr> <td><tt>HOME</tt></td> <td><tt>CVM_FACT_DIRECTORY</tt></td> </tr>
<tr> <td><tt>SHELL</tt></td> <td><tt>CVM_FACT_SHELL</tt></td> </tr>
<tr> <td><tt>GROUP</tt></td> <td><tt>CVM_FACT_GROUPNAME</tt></td> </tr>
<tr> <td><tt>DOMAIN</tt></td> <td><tt>CVM_FACT_DOMAIN</tt></td> </tr>
<tr> <td><tt>MAIL</tt></td> <td><tt>CVM_FACT_MAILBOX</tt></td> </tr>
<tr> <td><tt>MAILBOX</tt></td> <td><tt>CVM_FACT_MAILBOX</tt></td> </tr>
<tr> <td><tt>MAILDIR</tt></td> <td><tt>CVM_FACT_MAILBOX</tt></td> </tr>
</table>
<dt><tt>int cvm_client_setugid(void)</tt> <dd><p>Calls <tt>chdir</tt>,
<tt>setgid</tt> and <tt>setuid</tt> with appropriate values based on the
data returned from the authentication. Returns zero if any of the calls
failed.</p>
</dl>
</body>
</html>
|