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