openafs: Improved calling of get-token script
[hcoop/debian/courier-authlib.git] / auth_login.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_login</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-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"/><!--
d9898ee8 3
b0322a85 4Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution
d9898ee8 5information.
6
b0322a85 7--></head><body><div class="refentry"><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"/>
d9898ee8 8#include &lt;courierauth.h&gt;<br clear="none"/>
b0322a85 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_login</strong>(</code></td><td rowspan="1" colspan="1">const char *<var class="pdparam">service</var>, </td></tr><tr><td rowspan="1" colspan="1"> </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">const char *<var class="pdparam">password</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="idm247882989472" 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
b0322a85 14being authenticated; like <span class="quote">“<span class="quote">imap</span>”</span> or <span class="quote">“<span class="quote">pop3</span>”</span>.
d9898ee8 15<em class="parameter"><code>service</code></em> may or may not be used by the Courier
b0322a85 16authentication library's configured back-end module.</p></div><div class="refsect1"><a id="idm247885295344" 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.
b0322a85 29The first argument will be a pointer to the following structure:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="idm247886847920" shape="rect"> </a><p class="title"><strong>Example 1. struct authinfo</strong></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>
b0322a85 47Description of the above fields:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">address</span></dt><dd><p>
d9898ee8 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>.
b0322a85 71The encrypted password can take several formats:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
d9898ee8 72A traditional triple-DES crypted password, or a MD5+salt-hashed password,
b0322a85
CE
73as used in Linux.</p></li><li class="listitem"><p>
74<span class="quote">“<span class="quote">{MD5}</span>”</span> followed by a base64-encoded MD5 hash
75of the password.</p></li><li class="listitem"><p>
76<span class="quote">“<span class="quote">{SHA}</span>”</span> followed by a base64-encoded SHA1 hash
d9898ee8 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.
b0322a85 82See below for more information.</p></dd></dl></div><div class="refsect2"><a id="idm247881555248" 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
b0322a85 86options, the option string will be a <code class="literal">NULL</code> value.
d9898ee8 87Otherwise it will be a comma-separated list of
b0322a85 88<span class="quote">“<span class="quote"><em class="replaceable"><code>option</code></em>=<em class="replaceable"><code>value</code></em></span>”</span>
d9898ee8 89settings.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
b0322a85
CE
90The application is responsible for actually implementing the
91options.
92For example,
93sn authentication request for service <span class="quote">“<span class="quote">imap</span>”</span>, for example,
94will succeed provided that the userid and the password are valid,
95even if <span class="quote">“<span class="quote">disableimap=1</span>”</span> is set.
96The application's <code class="function">callback_func</code> should check for this
97condition, 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>
98The following list of account options is a combined list of implemented
99options supported by Courier, Courier-IMAP, and
d9898ee8 100SqWebMail packages. Some of the following information is obviously
101not applicable for a particular package.
102The inapplicable bits should be obvious.</p></div><p>
103The following options are recognized by the various Courier
b0322a85 104packages:</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 105If "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
106If "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>
107If "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>
108If "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 109If "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>
110If "n" is 1, this account should not have access to shared folders or be able
111to 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
112This option is used by Courier-IMAP in calculating access control lists.
113This option places the account as a member of access group
d9898ee8 114<em class="replaceable"><code>name</code></em>.
115Instead of granting access rights on individual mail folders to individual
116accounts, the access rights can be granted to an access group
b0322a85 117<span class="quote">“<span class="quote">name</span>”</span>, and all members of this group get the specified access
d9898ee8 118rights.</p><p>
b0322a85 119The access group name <span class="quote">“<span class="quote">administrators</span>”</span> is a reserved group.
d9898ee8 120All accounts in the <code class="literal">administrators</code> group automatically
121receive 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>
122This option may be specified multiple times to specify that the account
123belongs 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 124Another option used by Courier-IMAP.
d9898ee8 125Append "name" to the name of the top level virtual shared folder
126index file. This setting restricts which virtual shared folders this
127account could possibly access (and that's on top of whatever else the
128access control lists say). See the virtual shared folder documentation
129for more information.</p><p>
130For technical reasons, group names may not include comma, tab, "/" or "|"
b0322a85 131characters.</p></dd></dl></div></div></div><div class="refsect1"><a id="idm247881468832" shape="rect"> </a><h2>SEE ALSO</h2><p>
8d138742 132<a class="ulink" href="authlib.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">authlib</span>(3)</span></a>,
d9898ee8 133
8d138742 134<a class="ulink" href="auth_generic.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_generic</span>(3)</span></a>,
d9898ee8 135
8d138742 136<a class="ulink" href="auth_getuserinfo.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_getuserinfo</span>(3)</span></a>,
d9898ee8 137
8d138742 138<a class="ulink" href="auth_enumerate.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_enumerate</span>(3)</span></a>,
d9898ee8 139
8d138742 140<a class="ulink" href="auth_passwd.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_passwd</span>(3)</span></a>,
d9898ee8 141
8d138742 142<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>