Commit | Line | Data |
---|---|---|
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_generic</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-generic" title="auth_generic"/><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 | 4 | Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution |
d9898ee8 | 5 | information. |
6 | ||
b0322a85 | 7 | --></head><body><div class="refentry"><a id="auth-generic" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>auth_generic — Generic authentication request</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="literallayout"><p><br clear="none"/> |
d9898ee8 | 8 | #include <courierauth.h><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_generic</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">authtype</var>, </td></tr><tr><td rowspan="1" colspan="1"> </td><td rowspan="1" colspan="1">const char *<var class="pdparam">authdata</var>, </td></tr><tr><td rowspan="1" colspan="1"> </td><td rowspan="1" colspan="1">int <var class="pdparam">(*callback_func)</var> |
d50284c4 | 10 | <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="idm255238642128" shape="rect"> </a><h2>DESCRIPTION</h2><p> |
d9898ee8 | 11 | <code class="function">auth_generic</code> processes a generic authentication request. |
12 | You do not want to use this function. | |
13 | You really want to use | |
8d138742 | 14 | <a class="ulink" href="auth_login.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_login</span>(3)</span></a>. |
d9898ee8 | 15 | <em class="parameter"><code>service</code></em> specifies which so-called "service" is |
b0322a85 | 16 | being authenticated; like <span class="quote">“<span class="quote">imap</span>”</span> or <span class="quote">“<span class="quote">pop3</span>”</span>. |
d9898ee8 | 17 | <em class="parameter"><code>service</code></em> may or may not be used by the Courier |
18 | authentication library's configured back-end module.</p><p> | |
19 | <code class="function">authtype</code> specifies the format of the authentication | |
20 | request. | |
21 | Three authentication formats are defined in | |
b0322a85 | 22 | <code class="filename">courierauth.h</code>:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">AUTHTYPE_LOGIN</code></span></dt><dd><p> |
d9898ee8 | 23 | <em class="parameter"><code>authdata</code></em> contains the following string: |
b0322a85 | 24 | <span class="quote">“<span class="quote"><em class="replaceable"><code>userid</code></em>\n<em class="replaceable"><code>password</code></em>\n</span>”</span>. |
d9898ee8 | 25 | That is, the userid being authenticated, an <acronym class="acronym">ASCII</acronym> |
26 | newline character, the password, and a second newline character.</p></dd><dt><span class="term"><code class="literal">AUTHTYPE_CRAMMD5</code> or <code class="literal">AUTHTYPE_CRAMSHA1</code></span></dt><dd><p> | |
27 | This format is used | |
28 | with <acronym class="acronym">CRAM-MD5</acronym> or <acronym class="acronym">CRAM-SHA1</acronym>. | |
29 | <em class="parameter"><code>authdata</code></em> contains the following string: | |
b0322a85 | 30 | <span class="quote">“<span class="quote"><em class="replaceable"><code>challenge</code></em>\n<em class="replaceable"><code>response</code></em>\n</span>”</span>. |
d9898ee8 | 31 | <em class="replaceable"><code>challenge</code></em> is the base64-encoded challenge, which |
32 | is followed by an <acronym class="acronym">ASCII</acronym> | |
33 | newline character. | |
34 | <em class="replaceable"><code>response</code></em> is a base64-encoded string that's | |
35 | followed by a second newline character. | |
36 | The base64-encoded string consists of the responding userid, a space | |
37 | character, then the response to the challenge expressed as hexadecimal | |
d50284c4 | 38 | digits.</p></dd></dl></div></div><div class="refsect1"><a id="idm255237499360" shape="rect"> </a><h2>RETURNS</h2><p> |
d9898ee8 | 39 | <code class="function">callback_func</code> will be invoked if |
40 | <code class="function">auth_generic</code> | |
41 | succeeds, and <code class="function">callback_func</code>'s return value becomes | |
42 | the return value from <code class="function">auth_generic</code> (which should be 0, by convention). | |
43 | <code class="function">callback_func</code> will not be invoked if an error occurs, | |
44 | which is reported by a non-zero return value from <code class="function">auth_generic</code>. | |
45 | By convention, a positive return value indicates an internal, temporary | |
46 | failure, such as the authentication daemon process not running; a negative | |
47 | return value indicates that this request was processed, but it failed.</p><p> | |
48 | The second argument to <code class="function">callback_func</code> will be | |
49 | <code class="function">callback_arg</code>, which is not interpreted by this | |
50 | function in any way. | |
d50284c4 | 51 | The first argument will be a pointer to the following structure:</p><div class="blockquote"><blockquote class="blockquote"><div class="example"><a id="idm255237491696" shape="rect"> </a><p class="title"><strong>Example 1. struct authinfo</strong></p><div class="example-contents"><pre class="programlisting" xml:space="preserve"> |
d9898ee8 | 52 | struct authinfo { |
53 | const char *sysusername; | |
54 | const uid_t *sysuserid; | |
55 | gid_t sysgroupid; | |
56 | const char *homedir; | |
57 | ||
58 | const char *address; | |
59 | const char *fullname; | |
60 | const char *maildir; | |
61 | const char *quota; | |
62 | const char *passwd; | |
63 | const char *clearpasswd; | |
64 | ||
65 | const char *options; | |
66 | ||
67 | } ; | |
68 | </pre></div></div><br class="example-break" clear="none"/></blockquote></div><p> | |
b0322a85 | 69 | Description of the above fields:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">address</span></dt><dd><p> |
d9898ee8 | 70 | The authenticated login ID.</p></dd><dt><span class="term">sysusername</span></dt><dd><p> |
71 | The authenticated account's userid and groupid can be looked up in the | |
72 | password file using <code class="literal">address</code>. | |
73 | If this field is <code class="literal">NULL</code>, obtain the userid and the groupid from | |
74 | <code class="literal">sysuserid</code> and <code class="literal">sysgroupid</code>.</p></dd><dt><span class="term">sysuserid</span></dt><dd><p> | |
75 | <code class="literal">sysuserid</code> may be <code class="literal">NULL</code> if | |
76 | <code class="literal">sysusername</code> is initialized, otherwise it's a pointer to | |
77 | the account's numeric userid.</p></dd><dt><span class="term">sysgroupid</span></dt><dd><p> | |
78 | Account's numeric groupid. | |
79 | <code class="literal">sysgroupid</code> is only used when <code class="literal">sysusername</code> | |
80 | is <code class="literal">NULL</code>.</p></dd><dt><span class="term">fullname</span></dt><dd><p> | |
81 | This is the account's full name. | |
82 | This field is optional, it may be <code class="literal">NULL</code>.</p></dd><dt><span class="term">homedir</span></dt><dd><p> | |
83 | The account's home directory. | |
84 | This field cannot be <code class="literal">NULL</code>.</p></dd><dt><span class="term">maildir</span></dt><dd><p> | |
85 | The pathname to the account's mailbox. | |
86 | This field is optional, it can be <code class="literal">NULL</code> in which case the | |
87 | default location is assumed.</p></dd><dt><span class="term">quota</span></dt><dd><p> | |
88 | Optional maildir quota on the account's mailbox (and <code class="literal">NULL</code> | |
89 | if no quota is set).</p></dd><dt><span class="term">passwd</span></dt><dd><p> | |
90 | The account's encrypted password, if available. | |
91 | If the account has a cleartext password defined, this field | |
92 | can be set to <code class="literal">NULL</code>. | |
b0322a85 | 93 | The encrypted password can take several formats:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> |
d9898ee8 | 94 | A traditional triple-DES crypted password, or a MD5+salt-hashed password, |
b0322a85 CE |
95 | as used in Linux.</p></li><li class="listitem"><p> |
96 | <span class="quote">“<span class="quote">{MD5}</span>”</span> followed by a base64-encoded MD5 hash | |
97 | of the password.</p></li><li class="listitem"><p> | |
98 | <span class="quote">“<span class="quote">{SHA}</span>”</span> followed by a base64-encoded SHA1 hash | |
d9898ee8 | 99 | of the password.</p></li></ul></div></dd><dt><span class="term">clearpasswd</span></dt><dd><p> |
100 | The account's cleartext password, if available. | |
101 | If the account has an encrypted password defined, this field | |
102 | can be set to <code class="literal">NULL</code>.</p></dd><dt><span class="term">options</span></dt><dd><p> | |
103 | A comma-separated list of miscellaneous account options. | |
d50284c4 | 104 | See below for more information.</p></dd></dl></div><div class="refsect2"><a id="idm255237415744" shape="rect"> </a><h3>Account options</h3><p> |
d9898ee8 | 105 | Depending on the configuration of the Courier authentication library, |
106 | accounts may have individual options associated with them. | |
107 | If the authentication library configuration does not implement account | |
b0322a85 | 108 | options, the option string will be a <code class="literal">NULL</code> value. |
d9898ee8 | 109 | Otherwise it will be a comma-separated list of |
b0322a85 | 110 | <span class="quote">“<span class="quote"><em class="replaceable"><code>option</code></em>=<em class="replaceable"><code>value</code></em></span>”</span> |
d9898ee8 | 111 | settings.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
b0322a85 CE |
112 | The application is responsible for actually implementing the |
113 | options. | |
114 | For example, | |
115 | sn authentication request for service <span class="quote">“<span class="quote">imap</span>”</span>, for example, | |
116 | will succeed provided that the userid and the password are valid, | |
117 | even if <span class="quote">“<span class="quote">disableimap=1</span>”</span> is set. | |
118 | The application's <code class="function">callback_func</code> should check for this | |
119 | condition, 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> | |
120 | The following list of account options is a combined list of implemented | |
121 | options supported by Courier, Courier-IMAP, and | |
d9898ee8 | 122 | SqWebMail packages. Some of the following information is obviously |
123 | not applicable for a particular package. | |
124 | The inapplicable bits should be obvious.</p></div><p> | |
125 | The following options are recognized by the various Courier | |
b0322a85 | 126 | packages:</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 | 127 | 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> |
b0322a85 CE |
128 | If "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> |
129 | If "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> | |
130 | If "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 | 131 | 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> |
132 | If "n" is 1, this account should not have access to shared folders or be able | |
133 | 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> | |
b0322a85 CE |
134 | This option is used by Courier-IMAP in calculating access control lists. |
135 | This option places the account as a member of access group | |
d9898ee8 | 136 | <em class="replaceable"><code>name</code></em>. |
137 | Instead of granting access rights on individual mail folders to individual | |
138 | accounts, the access rights can be granted to an access group | |
b0322a85 | 139 | <span class="quote">“<span class="quote">name</span>”</span>, and all members of this group get the specified access |
d9898ee8 | 140 | rights.</p><p> |
b0322a85 | 141 | The access group name <span class="quote">“<span class="quote">administrators</span>”</span> is a reserved group. |
d9898ee8 | 142 | All accounts in the <code class="literal">administrators</code> group automatically |
143 | 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> | |
144 | This option may be specified multiple times to specify that the account | |
145 | 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> | |
b0322a85 | 146 | Another option used by Courier-IMAP. |
d9898ee8 | 147 | Append "name" to the name of the top level virtual shared folder |
148 | index file. This setting restricts which virtual shared folders this | |
149 | account could possibly access (and that's on top of whatever else the | |
150 | access control lists say). See the virtual shared folder documentation | |
151 | for more information.</p><p> | |
152 | For technical reasons, group names may not include comma, tab, "/" or "|" | |
d50284c4 | 153 | characters.</p></dd></dl></div></div></div><div class="refsect1"><a id="idm255237328656" shape="rect"> </a><h2>SEE ALSO</h2><p> |
8d138742 | 154 | <a class="ulink" href="authlib.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">authlib</span>(3)</span></a>, |
d9898ee8 | 155 | |
8d138742 | 156 | <a class="ulink" href="auth_login.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_login</span>(3)</span></a>, |
d9898ee8 | 157 | |
8d138742 | 158 | <a class="ulink" href="auth_getuserinfo.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_getuserinfo</span>(3)</span></a>, |
d9898ee8 | 159 | |
8d138742 | 160 | <a class="ulink" href="auth_enumerate.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_enumerate</span>(3)</span></a>, |
d9898ee8 | 161 | |
8d138742 | 162 | <a class="ulink" href="auth_passwd.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">auth_passwd</span>(3)</span></a>, |
d9898ee8 | 163 | |
8d138742 | 164 | <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> |