Imported Debian patch 0.63.0-6
[hcoop/debian/courier-authlib.git] / auth_getuserinfo.html
CommitLineData
d9898ee8 1<?xml version="1.0"?>
8d138742 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" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"/><link rel="start" 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
4Copyright 1998 - 2007 Double Precision, Inc. See COPYING for distribution
5information.
6
8d138742
CE
7--></head><body><div class="refentry" lang="en" xml:lang="en"><a id="auth-getuserinfo"> </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/>
8#include &lt;courierauth.h&gt;<br/>
9</p></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">int rc=<b class="fsfunc">auth_getuserinfo</b>(</code></td><td>const char * </td><td><var class="pdparam">userid</var>, </td></tr><tr><td> </td><td>int  </td><td><var class="pdparam">(*callback_func)</var><code>(</code>struct authinfo *, void *<code>)</code>, </td></tr><tr><td> </td><td>void * </td><td><var class="pdparam">callback_arg</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="id500248"> </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
8d138742 12<em class="parameter"><code>callback_func</code></em>.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="id514042"> </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.
8d138742 28The first argument will be a pointer to the following structure:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="id478809"> </a><p class="title"><b>Example 1. struct authinfo</b></p><div class="example-contents"><pre class="programlisting">
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 } ;
8d138742 45</pre></div></div><br class="example-break"/></blockquote></div><p>
d9898ee8 46Description of the above fields:</p><div class="variablelist"><dl><dt><span class="term">address</span></dt><dd><p>
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>.
70The encrypted password can take several formats:</p><div class="itemizedlist"><ul type="disc"><li><p>
71A traditional triple-DES crypted password, or a MD5+salt-hashed password,
72as used in Linux.</p></li><li><p>
73“<span class="quote">{MD5}</span>” followed by a base64-encoded MD5 hash
74of the password.</p></li><li><p>
75“<span class="quote">{SHA}</span>” followed by a base64-encoded SHA1 hash
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.
8d138742 81See below for more information.</p></dd></dl></div><div class="refsect2" lang="en" xml:lang="en"><a id="id523609"> </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
85options, the option string will be <code class="literal">NULL</code>.
86Otherwise it will be a comma-separated list of
87“<span class="quote"><em class="replaceable"><code>option</code></em>=<em class="replaceable"><code>value</code></em></span>”
88settings.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
89This is the account option implementation
90that's used by Courier, Courier-IMAP, and
91SqWebMail packages. Some of the following information is obviously
92not applicable for a particular package.
93The inapplicable bits should be obvious.</p></div><p>
94The following options are recognized by the various Courier
95packages:</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
96The application is responsible for enforcing all the “<span class="quote">disabled</span>”
97option.
98An authentication request for service “<span class="quote">imap</span>”, for example,
99will succeed provided that the userid and the password are valid,
100even if “<span class="quote">disableimap=1</span>” is set.
101The application's <code class="function">callback_func</code> should check for this
102condition, and return a negative return code.</p></div><div class="variablelist"><dl><dt><span class="term"><code class="literal">disableimap=</code><em class="replaceable"><code>n</code></em></span></dt><dd><p>
103If "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>
104If "n" is 1, 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>
105If "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>
106If "n" is 1, this account should not have access to shared folders or be able
107to 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>
108This account is a member of access group
109<em class="replaceable"><code>name</code></em>.
110Instead of granting access rights on individual mail folders to individual
111accounts, the access rights can be granted to an access group
112“<span class="quote">name</span>”, and all members of this group get the specified access
113rights.</p><p>
114The access group name “<span class="quote">administrators</span>” is a reserved group.
115All accounts in the <code class="literal">administrators</code> group automatically
116receive 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>
117This option may be specified multiple times to specify that the account
118belongs 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>
119Append "name" to the name of the top level virtual shared folder
120index file. This setting restricts which virtual shared folders this
121account could possibly access (and that's on top of whatever else the
122access control lists say). See the virtual shared folder documentation
123for more information.</p><p>
124For technical reasons, group names may not include comma, tab, "/" or "|"
8d138742
CE
125characters.</p></dd></dl></div></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="id524061"> </a><h2>SEE ALSO</h2><p>
126<a class="ulink" href="authlib.html" target="_top"><span class="citerefentry"><span class="refentrytitle">authlib</span>(3)</span></a>,
d9898ee8 127
8d138742 128<a class="ulink" href="auth_generic.html" target="_top"><span class="citerefentry"><span class="refentrytitle">auth_generic</span>(3)</span></a>,
d9898ee8 129
8d138742 130<a class="ulink" href="auth_login.html" target="_top"><span class="citerefentry"><span class="refentrytitle">auth_login</span>(3)</span></a>,
d9898ee8 131
8d138742 132<a class="ulink" href="auth_enumerate.html" target="_top"><span class="citerefentry"><span class="refentrytitle">auth_enumerate</span>(3)</span></a>,
d9898ee8 133
8d138742 134<a class="ulink" href="auth_passwd.html" target="_top"><span class="citerefentry"><span class="refentrytitle">auth_passwd</span>(3)</span></a>,
d9898ee8 135
8d138742 136<a class="ulink" href="auth_getoption.html" target="_top"><span class="citerefentry"><span class="refentrytitle">auth_getoption</span>(3)</span></a>.</p></div></div></body></html>