| 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_getuserinfo</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-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"/><!-- |
| 3 | |
| 4 | Copyright 1998 - 2007 Double Precision, Inc. See COPYING for distribution |
| 5 | information. |
| 6 | |
| 7 | --></head><body><div class="refentry" lang="en" xml:lang="en"><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 <courierauth.h><br clear="none"/> |
| 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_getuserinfo</b>(</code></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">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="id282319" shape="rect"> </a><h2>DESCRIPTION</h2><p> |
| 10 | If <em class="parameter"><code>userid</code></em> is a valid account name, |
| 11 | retrieve the account particulars and invoke |
| 12 | <em class="parameter"><code>callback_func</code></em>.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="id282341" shape="rect"> </a><h2>RETURNS</h2><p> |
| 13 | <code class="function">callback_func</code> will be invoked if |
| 14 | <em class="replaceable"><code>userid</code></em> exists, |
| 15 | and <code class="function">callback_func</code>'s return value becomes |
| 16 | the 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, |
| 19 | which is reported by a non-zero return value from |
| 20 | <code class="function">auth_getuserinfo</code>. |
| 21 | By convention, a positive return value indicates an internal, temporary |
| 22 | failure, such as the authentication daemon process not running; a negative |
| 23 | return 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> |
| 25 | The second argument to <code class="function">callback_func</code> will be |
| 26 | <code class="function">callback_arg</code>, which is not interpreted by this |
| 27 | function in any way. |
| 28 | The first argument will be a pointer to the following structure:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="id282589" shape="rect"> </a><p class="title"><b>Example 1. struct authinfo</b></p><div class="example-contents"><pre class="programlisting" xml:space="preserve"> |
| 29 | struct 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 | } ; |
| 45 | </pre></div></div><br class="example-break" clear="none"/></blockquote></div><p> |
| 46 | Description of the above fields:</p><div class="variablelist"><dl><dt><span class="term">address</span></dt><dd><p> |
| 47 | The authenticated login ID.</p></dd><dt><span class="term">sysusername</span></dt><dd><p> |
| 48 | The authenticated account's userid and groupid can be looked up in the |
| 49 | password file using <code class="literal">address</code>. |
| 50 | If 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 |
| 54 | the account's numeric userid.</p></dd><dt><span class="term">sysgroupid</span></dt><dd><p> |
| 55 | Account's numeric groupid. |
| 56 | <code class="literal">sysgroupid</code> is only used when <code class="literal">sysusername</code> |
| 57 | is <code class="literal">NULL</code>.</p></dd><dt><span class="term">fullname</span></dt><dd><p> |
| 58 | This is the account's full name. |
| 59 | This field is optional, it may be <code class="literal">NULL</code>.</p></dd><dt><span class="term">homedir</span></dt><dd><p> |
| 60 | The account's home directory. |
| 61 | This field cannot be <code class="literal">NULL</code>.</p></dd><dt><span class="term">maildir</span></dt><dd><p> |
| 62 | The pathname to the account's mailbox. |
| 63 | This field is optional, it can be <code class="literal">NULL</code> in which case the |
| 64 | default location is assumed.</p></dd><dt><span class="term">quota</span></dt><dd><p> |
| 65 | Optional maildir quota on the account's mailbox (and <code class="literal">NULL</code> |
| 66 | if no quota is set).</p></dd><dt><span class="term">passwd</span></dt><dd><p> |
| 67 | The account's encrypted password, if available. |
| 68 | If the account has a cleartext password defined, this field |
| 69 | can be set to <code class="literal">NULL</code>. |
| 70 | The encrypted password can take several formats:</p><div class="itemizedlist"><ul type="disc"><li><p> |
| 71 | A traditional triple-DES crypted password, or a MD5+salt-hashed password, |
| 72 | as used in Linux.</p></li><li><p> |
| 73 | “<span class="quote">{MD5}</span>” followed by a base64-encoded MD5 hash |
| 74 | of the password.</p></li><li><p> |
| 75 | “<span class="quote">{SHA}</span>” followed by a base64-encoded SHA1 hash |
| 76 | of the password.</p></li></ul></div></dd><dt><span class="term">clearpasswd</span></dt><dd><p> |
| 77 | The account's cleartext password, if available. |
| 78 | If the account has an encrypted password defined, this field |
| 79 | can be set to <code class="literal">NULL</code>.</p></dd><dt><span class="term">options</span></dt><dd><p> |
| 80 | A comma-separated list of miscellaneous account options. |
| 81 | See below for more information.</p></dd></dl></div><div class="refsect2" lang="en" xml:lang="en"><a id="id325640" shape="rect"> </a><h3>Account options</h3><p> |
| 82 | Depending on the configuration of the Courier authentication library, |
| 83 | accounts may have individual options associated with them. |
| 84 | If the authentication library configuration does not implement account |
| 85 | options, the option string will be <code class="literal">NULL</code>. |
| 86 | Otherwise 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>” |
| 88 | settings.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| 89 | This is the account option implementation |
| 90 | that's used by Courier, Courier-IMAP, and |
| 91 | SqWebMail packages. Some of the following information is obviously |
| 92 | not applicable for a particular package. |
| 93 | The inapplicable bits should be obvious.</p></div><p> |
| 94 | The following options are recognized by the various Courier |
| 95 | packages:</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| 96 | The application is responsible for enforcing all the “<span class="quote">disabled</span>” |
| 97 | option. |
| 98 | An authentication request for service “<span class="quote">imap</span>”, for example, |
| 99 | will succeed provided that the userid and the password are valid, |
| 100 | even if “<span class="quote">disableimap=1</span>” is set. |
| 101 | The application's <code class="function">callback_func</code> should check for this |
| 102 | condition, 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> |
| 103 | If "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> |
| 104 | If "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> |
| 105 | If "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> |
| 106 | If "n" is 1, this account should not have access to shared folders or be able |
| 107 | to 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> |
| 108 | This account is a member of access group |
| 109 | <em class="replaceable"><code>name</code></em>. |
| 110 | Instead of granting access rights on individual mail folders to individual |
| 111 | accounts, 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 |
| 113 | rights.</p><p> |
| 114 | The access group name “<span class="quote">administrators</span>” is a reserved group. |
| 115 | All accounts in the <code class="literal">administrators</code> group automatically |
| 116 | receive 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> |
| 117 | This option may be specified multiple times to specify that the account |
| 118 | belongs 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> |
| 119 | Append "name" to the name of the top level virtual shared folder |
| 120 | index file. This setting restricts which virtual shared folders this |
| 121 | account could possibly access (and that's on top of whatever else the |
| 122 | access control lists say). See the virtual shared folder documentation |
| 123 | for more information.</p><p> |
| 124 | For technical reasons, group names may not include comma, tab, "/" or "|" |
| 125 | characters.</p></dd></dl></div></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="id326137" shape="rect"> </a><h2>SEE ALSO</h2><p> |
| 126 | <a href="authlib.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">authlib</span>(3)</span></a>, |
| 127 | |
| 128 | <a href="auth_generic.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_generic</span>(3)</span></a>, |
| 129 | |
| 130 | <a href="auth_login.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_login</span>(3)</span></a>, |
| 131 | |
| 132 | <a href="auth_enumerate.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_enumerate</span>(3)</span></a>, |
| 133 | |
| 134 | <a href="auth_passwd.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_passwd</span>(3)</span></a>, |
| 135 | |
| 136 | <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> |