Import Upstream version 0.69.0
[hcoop/debian/courier-authlib.git] / auth_getuserinfo.html
CommitLineData
d9898ee8 1<?xml version="1.0"?>
b0322a85 2<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>auth_getuserinfo</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"/><link rel="home" href="#auth-getuserinfo" title="auth_getuserinfo"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--
d9898ee8 3
b0322a85 4Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution
d9898ee8 5information.
6
b0322a85
CE
7--></head><body><div class="refentry"><a id="auth-getuserinfo" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>auth_getuserinfo — Obtain account information</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="literallayout"><p><br clear="none"/>
8#include &lt;courierauth.h&gt;<br clear="none"/>
d50284c4 9</p></div><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td rowspan="1" colspan="1"><code class="funcdef">int rc=<strong>auth_getuserinfo</strong>(</code></td><td rowspan="1" colspan="1">const char *<var class="pdparam">userid</var>, </td></tr><tr><td rowspan="1" colspan="1"> </td><td rowspan="1" colspan="1">int <var class="pdparam">(*callback_func)</var><code>(</code>struct authinfo *, void *<code>)</code>, </td></tr><tr><td rowspan="1" colspan="1"> </td><td rowspan="1" colspan="1">void *<var class="pdparam">callback_arg</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a id="idm255228309696" shape="rect"> </a><h2>DESCRIPTION</h2><p>
d9898ee8 10If <em class="parameter"><code>userid</code></em> is a valid account name,
11retrieve the account particulars and invoke
d50284c4 12<em class="parameter"><code>callback_func</code></em>.</p></div><div class="refsect1"><a id="idm255225665504" shape="rect"> </a><h2>RETURNS</h2><p>
d9898ee8 13<code class="function">callback_func</code> will be invoked if
14<em class="replaceable"><code>userid</code></em> exists,
15and <code class="function">callback_func</code>'s return value becomes
16the return value from <code class="function">auth_getuserinfo</code>
17(which should be 0, by convention).
18<code class="function">callback_func</code> will not be invoked if an error occurs,
19which is reported by a non-zero return value from
20<code class="function">auth_getuserinfo</code>.
21By convention, a positive return value indicates an internal, temporary
22failure, such as the authentication daemon process not running; a negative
23return value indicates that this request was processed, but it failed
24(probably because <em class="replaceable"><code>userid</code></em> does not exist.</p><p>
25The second argument to <code class="function">callback_func</code> will be
26<code class="function">callback_arg</code>, which is not interpreted by this
27function in any way.
d50284c4 28The first argument will be a pointer to the following structure:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="idm255229873440" shape="rect"> </a><p class="title"><strong>Example 1. struct authinfo</strong></p><div class="example-contents"><pre class="programlisting" xml:space="preserve">
d9898ee8 29struct authinfo {
30 const char *sysusername;
31 const uid_t *sysuserid;
32 gid_t sysgroupid;
33 const char *homedir;
34
35 const char *address;
36 const char *fullname;
37 const char *maildir;
38 const char *quota;
39 const char *passwd;
40 const char *clearpasswd;
41
42 const char *options;
43
44 } ;
b0322a85
CE
45</pre></div></div><br class="example-break" clear="none"/></blockquote></div><p>
46Description of the above fields:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">address</span></dt><dd><p>
d9898ee8 47The authenticated login ID.</p></dd><dt><span class="term">sysusername</span></dt><dd><p>
48The authenticated account's userid and groupid can be looked up in the
49password file using <code class="literal">address</code>.
50If this field is <code class="literal">NULL</code>, obtain the userid and the groupid from
51<code class="literal">sysuserid</code> and <code class="literal">sysgroupid</code>.</p></dd><dt><span class="term">sysuserid</span></dt><dd><p>
52<code class="literal">sysuserid</code> may be <code class="literal">NULL</code> if
53<code class="literal">sysusername</code> is initialized, otherwise it's a pointer to
54the account's numeric userid.</p></dd><dt><span class="term">sysgroupid</span></dt><dd><p>
55Account's numeric groupid.
56<code class="literal">sysgroupid</code> is only used when <code class="literal">sysusername</code>
57is <code class="literal">NULL</code>.</p></dd><dt><span class="term">fullname</span></dt><dd><p>
58This is the account's full name.
59This field is optional, it may be <code class="literal">NULL</code>.</p></dd><dt><span class="term">homedir</span></dt><dd><p>
60The account's home directory.
61This field cannot be <code class="literal">NULL</code>.</p></dd><dt><span class="term">maildir</span></dt><dd><p>
62The pathname to the account's mailbox.
63This field is optional, it can be <code class="literal">NULL</code> in which case the
64default location is assumed.</p></dd><dt><span class="term">quota</span></dt><dd><p>
65Optional maildir quota on the account's mailbox (and <code class="literal">NULL</code>
66if no quota is set).</p></dd><dt><span class="term">passwd</span></dt><dd><p>
67The account's encrypted password, if available.
68If the account has a cleartext password defined, this field
69can be set to <code class="literal">NULL</code>.
b0322a85 70The encrypted password can take several formats:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
d9898ee8 71A traditional triple-DES crypted password, or a MD5+salt-hashed password,
b0322a85
CE
72as used in Linux.</p></li><li class="listitem"><p>
73<span class="quote">“<span class="quote">{MD5}</span>”</span> followed by a base64-encoded MD5 hash
74of the password.</p></li><li class="listitem"><p>
75<span class="quote">“<span class="quote">{SHA}</span>”</span> followed by a base64-encoded SHA1 hash
d9898ee8 76of the password.</p></li></ul></div></dd><dt><span class="term">clearpasswd</span></dt><dd><p>
77The account's cleartext password, if available.
78If the account has an encrypted password defined, this field
79can be set to <code class="literal">NULL</code>.</p></dd><dt><span class="term">options</span></dt><dd><p>
80A comma-separated list of miscellaneous account options.
d50284c4 81See below for more information.</p></dd></dl></div><div class="refsect2"><a id="idm255224460816" shape="rect"> </a><h3>Account options</h3><p>
d9898ee8 82Depending on the configuration of the Courier authentication library,
83accounts may have individual options associated with them.
84If the authentication library configuration does not implement account
b0322a85 85options, the option string will be a <code class="literal">NULL</code> value.
d9898ee8 86Otherwise it will be a comma-separated list of
b0322a85 87<span class="quote">“<span class="quote"><em class="replaceable"><code>option</code></em>=<em class="replaceable"><code>value</code></em></span>”</span>
d9898ee8 88settings.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
b0322a85
CE
89The application is responsible for actually implementing the
90options.
91For example,
92sn authentication request for service <span class="quote">“<span class="quote">imap</span>”</span>, for example,
93will succeed provided that the userid and the password are valid,
94even if <span class="quote">“<span class="quote">disableimap=1</span>”</span> is set.
95The application's <code class="function">callback_func</code> should check for this
96condition, and return a negative return code.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
97The following list of account options is a combined list of implemented
98options supported by Courier, Courier-IMAP, and
d9898ee8 99SqWebMail packages. Some of the following information is obviously
100not applicable for a particular package.
101The inapplicable bits should be obvious.</p></div><p>
102The following options are recognized by the various Courier
b0322a85 103packages:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disableimap=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
d9898ee8 104If "n" is 1, IMAP access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disablepop3=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
b0322a85
CE
105If "n" is 1, POP3 access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disableinsecureimap=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
106If "n" is 1, unencrypted IMAP access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disableinsecurepop3=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
107If "n" is 1, unencrypted POP3 access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disablewebmail=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
d9898ee8 108If "n" is 1, webmail access to this account should be disabled.</p></dd><dt><span class="term"><code class="literal">disableshared=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
109If "n" is 1, this account should not have access to shared folders or be able
110to share its own folders with other people.</p></dd><dt><span class="term"><code class="literal">group=</code><em class="replaceable"><code>name</code></em></span></dt><dd><p>
b0322a85
CE
111This option is used by Courier-IMAP in calculating access control lists.
112This option places the account as a member of access group
d9898ee8 113<em class="replaceable"><code>name</code></em>.
114Instead of granting access rights on individual mail folders to individual
115accounts, the access rights can be granted to an access group
b0322a85 116<span class="quote">“<span class="quote">name</span>”</span>, and all members of this group get the specified access
d9898ee8 117rights.</p><p>
b0322a85 118The access group name <span class="quote">“<span class="quote">administrators</span>”</span> is a reserved group.
d9898ee8 119All accounts in the <code class="literal">administrators</code> group automatically
120receive all rights to all accessible folders.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
121This option may be specified multiple times to specify that the account
122belongs to multiple account groups.</p></div></dd><dt><span class="term"><code class="literal">sharedgroup=</code><em class="replaceable"><code>name</code></em></span></dt><dd><p>
b0322a85 123Another option used by Courier-IMAP.
d9898ee8 124Append "name" to the name of the top level virtual shared folder
125index file. This setting restricts which virtual shared folders this
126account could possibly access (and that's on top of whatever else the
127access control lists say). See the virtual shared folder documentation
128for more information.</p><p>
129For technical reasons, group names may not include comma, tab, "/" or "|"
d50284c4 130characters.</p></dd></dl></div></div></div><div class="refsect1"><a id="idm255224373824" shape="rect"> </a><h2>SEE ALSO</h2><p>
b0322a85 131<a class="ulink" href="authlib.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">authlib</span>(3)</span></a>,
d9898ee8 132
b0322a85 133<a class="ulink" href="auth_generic.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_generic</span>(3)</span></a>,
d9898ee8 134
b0322a85 135<a class="ulink" href="auth_login.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_login</span>(3)</span></a>,
d9898ee8 136
b0322a85 137<a class="ulink" href="auth_enumerate.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_enumerate</span>(3)</span></a>,
d9898ee8 138
b0322a85 139<a class="ulink" href="auth_passwd.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_passwd</span>(3)</span></a>,
d9898ee8 140
b0322a85 141<a class="ulink" href="auth_getoption.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_getoption</span>(3)</span></a>.</p></div></div></body></html>