Commit | Line | Data |
---|---|---|
b0322a85 | 1 | '\" t |
d9898ee8 | 2 | .\" <!-- Copyright 2004 Double Precision, Inc. See COPYING for --> |
3 | .\" <!-- distribution information. --> | |
4 | .\" Title: auth_login | |
b0322a85 CE |
5 | .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
6 | .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> | |
d50284c4 | 7 | .\" Date: 06/20/2015 |
d9898ee8 | 8 | .\" Manual: Double Precision, Inc. |
9 | .\" Source: Double Precision, Inc. | |
b0322a85 | 10 | .\" Language: English |
d9898ee8 | 11 | .\" |
d50284c4 | 12 | .TH "AUTH_LOGIN" "3" "06/20/2015" "Double Precision, Inc." "Double Precision, Inc." |
b0322a85 CE |
13 | .\" ----------------------------------------------------------------- |
14 | .\" * Define some portability stuff | |
15 | .\" ----------------------------------------------------------------- | |
16 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17 | .\" http://bugs.debian.org/507673 | |
18 | .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html | |
19 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
20 | .ie \n(.g .ds Aq \(aq | |
21 | .el .ds Aq ' | |
22 | .\" ----------------------------------------------------------------- | |
23 | .\" * set default formatting | |
24 | .\" ----------------------------------------------------------------- | |
d9898ee8 | 25 | .\" disable hyphenation |
26 | .nh | |
27 | .\" disable justification (adjust text to left margin only) | |
28 | .ad l | |
b0322a85 CE |
29 | .\" ----------------------------------------------------------------- |
30 | .\" * MAIN CONTENT STARTS HERE * | |
31 | .\" ----------------------------------------------------------------- | |
d9898ee8 | 32 | .SH "NAME" |
b0322a85 | 33 | auth_login \- Validate a userid and password |
d9898ee8 | 34 | .SH "SYNOPSIS" |
35 | .sp | |
d9898ee8 | 36 | .nf |
b0322a85 | 37 | #include <courierauth\&.h> |
d9898ee8 | 38 | .fi |
b0322a85 | 39 | .HP \w'int\ rc=auth_login('u |
dd184caf | 40 | .BI "int rc=auth_login(const\ char\ *" "service" ", const\ char\ *" "userid" ", const\ char\ *" "password" ", int\ " "(*callback_func)" "(struct\ authinfo\ *,\ void\ *), void\ *" "callback_arg" ");" |
d9898ee8 | 41 | .SH "DESCRIPTION" |
42 | .PP | |
d9898ee8 | 43 | \fBauth_login\fR |
44 | verifies whether | |
45 | \fIuserid\fR | |
b0322a85 | 46 | exists, and whether it\*(Aqs |
d9898ee8 | 47 | \fIpassword\fR |
b0322a85 | 48 | is correct\&. |
d9898ee8 | 49 | \fIservice\fR |
50 | specifies which so\-called "service" is being authenticated; like | |
51 | \(lqimap\(rq | |
52 | or | |
b0322a85 | 53 | \(lqpop3\(rq\&. |
d9898ee8 | 54 | \fIservice\fR |
b0322a85 | 55 | may or may not be used by the Courier authentication library\*(Aqs configured back\-end module\&. |
d9898ee8 | 56 | .SH "RETURNS" |
57 | .PP | |
d9898ee8 | 58 | \fBcallback_func\fR |
59 | will be invoked if | |
60 | \fBauth_login\fR | |
61 | succeeds, and | |
b0322a85 | 62 | \fBcallback_func\fR\*(Aqs return value becomes the return value from |
d9898ee8 | 63 | \fBauth_login\fR |
b0322a85 | 64 | (which should be 0, by convention)\&. |
d9898ee8 | 65 | \fBcallback_func\fR |
66 | will not be invoked if an error occurs, which is reported by a non\-zero return value from | |
b0322a85 | 67 | \fBauth_login\fR\&. By convention, a positive return value indicates an internal, temporary failure, such as the authentication daemon process not running; a negative return value indicates that this request was processed, but it failed\&. |
d9898ee8 | 68 | .PP |
69 | The second argument to | |
70 | \fBcallback_func\fR | |
71 | will be | |
b0322a85 | 72 | \fBcallback_arg\fR, which is not interpreted by this function in any way\&. The first argument will be a pointer to the following structure: |
8d138742 | 73 | .PP |
b0322a85 | 74 | \fBExample\ \&1.\ \&struct authinfo\fR |
d9898ee8 | 75 | .sp |
b0322a85 | 76 | .if n \{\ |
d9898ee8 | 77 | .RS 4 |
b0322a85 | 78 | .\} |
d9898ee8 | 79 | .nf |
80 | struct authinfo { | |
81 | const char *sysusername; | |
82 | const uid_t *sysuserid; | |
83 | gid_t sysgroupid; | |
84 | const char *homedir; | |
85 | ||
86 | const char *address; | |
87 | const char *fullname; | |
88 | const char *maildir; | |
89 | const char *quota; | |
90 | const char *passwd; | |
91 | const char *clearpasswd; | |
92 | ||
93 | const char *options; | |
94 | ||
95 | } ; | |
96 | .fi | |
b0322a85 | 97 | .if n \{\ |
d9898ee8 | 98 | .RE |
b0322a85 | 99 | .\} |
d9898ee8 | 100 | .PP |
101 | Description of the above fields: | |
102 | .PP | |
103 | address | |
104 | .RS 4 | |
b0322a85 | 105 | The authenticated login ID\&. |
d9898ee8 | 106 | .RE |
107 | .PP | |
108 | sysusername | |
109 | .RS 4 | |
b0322a85 CE |
110 | The authenticated account\*(Aqs userid and groupid can be looked up in the password file using |
111 | address\&. If this field is | |
d9898ee8 | 112 | NULL, obtain the userid and the groupid from |
113 | sysuserid | |
114 | and | |
b0322a85 | 115 | sysgroupid\&. |
d9898ee8 | 116 | .RE |
117 | .PP | |
118 | sysuserid | |
119 | .RS 4 | |
d9898ee8 | 120 | sysuserid |
121 | may be | |
122 | NULL | |
123 | if | |
124 | sysusername | |
b0322a85 | 125 | is initialized, otherwise it\*(Aqs a pointer to the account\*(Aqs numeric userid\&. |
d9898ee8 | 126 | .RE |
127 | .PP | |
128 | sysgroupid | |
129 | .RS 4 | |
b0322a85 | 130 | Account\*(Aqs numeric groupid\&. |
d9898ee8 | 131 | sysgroupid |
132 | is only used when | |
133 | sysusername | |
134 | is | |
b0322a85 | 135 | NULL\&. |
d9898ee8 | 136 | .RE |
137 | .PP | |
138 | fullname | |
139 | .RS 4 | |
b0322a85 CE |
140 | This is the account\*(Aqs full name\&. This field is optional, it may be |
141 | NULL\&. | |
d9898ee8 | 142 | .RE |
143 | .PP | |
144 | homedir | |
145 | .RS 4 | |
b0322a85 CE |
146 | The account\*(Aqs home directory\&. This field cannot be |
147 | NULL\&. | |
d9898ee8 | 148 | .RE |
149 | .PP | |
150 | maildir | |
151 | .RS 4 | |
b0322a85 | 152 | The pathname to the account\*(Aqs mailbox\&. This field is optional, it can be |
d9898ee8 | 153 | NULL |
b0322a85 | 154 | in which case the default location is assumed\&. |
d9898ee8 | 155 | .RE |
156 | .PP | |
157 | quota | |
158 | .RS 4 | |
b0322a85 | 159 | Optional maildir quota on the account\*(Aqs mailbox (and |
d9898ee8 | 160 | NULL |
b0322a85 | 161 | if no quota is set)\&. |
d9898ee8 | 162 | .RE |
163 | .PP | |
164 | passwd | |
165 | .RS 4 | |
b0322a85 CE |
166 | The account\*(Aqs encrypted password, if available\&. If the account has a cleartext password defined, this field can be set to |
167 | NULL\&. The encrypted password can take several formats: | |
8d138742 | 168 | .sp |
d9898ee8 | 169 | .RS 4 |
b0322a85 CE |
170 | .ie n \{\ |
171 | \h'-04'\(bu\h'+03'\c | |
172 | .\} | |
173 | .el \{\ | |
174 | .sp -1 | |
175 | .IP \(bu 2.3 | |
176 | .\} | |
177 | A traditional triple\-DES crypted password, or a MD5+salt\-hashed password, as used in Linux\&. | |
d9898ee8 | 178 | .RE |
8d138742 | 179 | .sp |
d9898ee8 | 180 | .RS 4 |
b0322a85 CE |
181 | .ie n \{\ |
182 | \h'-04'\(bu\h'+03'\c | |
183 | .\} | |
184 | .el \{\ | |
185 | .sp -1 | |
186 | .IP \(bu 2.3 | |
187 | .\} | |
d9898ee8 | 188 | \(lq{MD5}\(rq |
b0322a85 | 189 | followed by a base64\-encoded MD5 hash of the password\&. |
d9898ee8 | 190 | .RE |
8d138742 | 191 | .sp |
d9898ee8 | 192 | .RS 4 |
b0322a85 CE |
193 | .ie n \{\ |
194 | \h'-04'\(bu\h'+03'\c | |
195 | .\} | |
196 | .el \{\ | |
197 | .sp -1 | |
198 | .IP \(bu 2.3 | |
199 | .\} | |
d9898ee8 | 200 | \(lq{SHA}\(rq |
b0322a85 | 201 | followed by a base64\-encoded SHA1 hash of the password\&. |
d9898ee8 | 202 | .RE |
203 | .RE | |
204 | .PP | |
205 | clearpasswd | |
206 | .RS 4 | |
b0322a85 CE |
207 | The account\*(Aqs cleartext password, if available\&. If the account has an encrypted password defined, this field can be set to |
208 | NULL\&. | |
d9898ee8 | 209 | .RE |
210 | .PP | |
211 | options | |
212 | .RS 4 | |
b0322a85 | 213 | A comma\-separated list of miscellaneous account options\&. See below for more information\&. |
d9898ee8 | 214 | .RE |
215 | .SS "Account options" | |
216 | .PP | |
b0322a85 CE |
217 | Depending on the configuration of the Courier authentication library, accounts may have individual options associated with them\&. If the authentication library configuration does not implement account options, the option string will be a |
218 | NULL | |
219 | value\&. Otherwise it will be a comma\-separated list of | |
d9898ee8 | 220 | \(lq\fIoption\fR=\fIvalue\fR\(rq |
b0322a85 CE |
221 | settings\&. |
222 | .if n \{\ | |
d9898ee8 | 223 | .sp |
b0322a85 CE |
224 | .\} |
225 | .RS 4 | |
d9898ee8 | 226 | .it 1 an-trap |
227 | .nr an-no-space-flag 1 | |
228 | .nr an-break-flag 1 | |
229 | .br | |
b0322a85 CE |
230 | .ps +1 |
231 | \fBNote\fR | |
232 | .ps -1 | |
233 | .br | |
d9898ee8 | 234 | .PP |
b0322a85 CE |
235 | The application is responsible for actually implementing the options\&. For example, sn authentication request for service |
236 | \(lqimap\(rq, for example, will succeed provided that the userid and the password are valid, even if | |
237 | \(lqdisableimap=1\(rq | |
238 | is set\&. The application\*(Aqs | |
239 | \fBcallback_func\fR | |
240 | should check for this condition, and return a negative return code\&. | |
241 | .sp .5v | |
242 | .RE | |
243 | .if n \{\ | |
d9898ee8 | 244 | .sp |
b0322a85 CE |
245 | .\} |
246 | .RS 4 | |
d9898ee8 | 247 | .it 1 an-trap |
248 | .nr an-no-space-flag 1 | |
249 | .nr an-break-flag 1 | |
250 | .br | |
b0322a85 CE |
251 | .ps +1 |
252 | \fBNote\fR | |
253 | .ps -1 | |
254 | .br | |
d9898ee8 | 255 | .PP |
b0322a85 CE |
256 | The following list of account options is a combined list of implemented options supported by Courier, Courier\-IMAP, and SqWebMail packages\&. Some of the following information is obviously not applicable for a particular package\&. The inapplicable bits should be obvious\&. |
257 | .sp .5v | |
258 | .RE | |
259 | .PP | |
260 | The following options are recognized by the various Courier packages: | |
d9898ee8 | 261 | .PP |
262 | disableimap=\fIn\fR | |
263 | .RS 4 | |
b0322a85 | 264 | If "n" is 1, IMAP access to this account should be disabled\&. |
d9898ee8 | 265 | .RE |
266 | .PP | |
267 | disablepop3=\fIn\fR | |
268 | .RS 4 | |
b0322a85 CE |
269 | If "n" is 1, POP3 access to this account should be disabled\&. |
270 | .RE | |
271 | .PP | |
272 | disableinsecureimap=\fIn\fR | |
273 | .RS 4 | |
274 | If "n" is 1, unencrypted IMAP access to this account should be disabled\&. | |
275 | .RE | |
276 | .PP | |
277 | disableinsecurepop3=\fIn\fR | |
278 | .RS 4 | |
279 | If "n" is 1, unencrypted POP3 access to this account should be disabled\&. | |
d9898ee8 | 280 | .RE |
281 | .PP | |
282 | disablewebmail=\fIn\fR | |
283 | .RS 4 | |
b0322a85 | 284 | If "n" is 1, webmail access to this account should be disabled\&. |
d9898ee8 | 285 | .RE |
286 | .PP | |
287 | disableshared=\fIn\fR | |
288 | .RS 4 | |
b0322a85 | 289 | If "n" is 1, this account should not have access to shared folders or be able to share its own folders with other people\&. |
d9898ee8 | 290 | .RE |
291 | .PP | |
292 | group=\fIname\fR | |
293 | .RS 4 | |
b0322a85 CE |
294 | This option is used by Courier\-IMAP in calculating access control lists\&. This option places the account as a member of access group |
295 | \fIname\fR\&. Instead of granting access rights on individual mail folders to individual accounts, the access rights can be granted to an access group | |
296 | \(lqname\(rq, and all members of this group get the specified access rights\&. | |
d9898ee8 | 297 | .sp |
298 | The access group name | |
299 | \(lqadministrators\(rq | |
b0322a85 | 300 | is a reserved group\&. All accounts in the |
d9898ee8 | 301 | administrators |
b0322a85 CE |
302 | group automatically receive all rights to all accessible folders\&. |
303 | .if n \{\ | |
d9898ee8 | 304 | .sp |
b0322a85 CE |
305 | .\} |
306 | .RS 4 | |
d9898ee8 | 307 | .it 1 an-trap |
308 | .nr an-no-space-flag 1 | |
309 | .nr an-break-flag 1 | |
310 | .br | |
b0322a85 CE |
311 | .ps +1 |
312 | \fBNote\fR | |
313 | .ps -1 | |
314 | .br | |
315 | This option may be specified multiple times to specify that the account belongs to multiple account groups\&. | |
316 | .sp .5v | |
317 | .RE | |
d9898ee8 | 318 | .RE |
319 | .PP | |
320 | sharedgroup=\fIname\fR | |
321 | .RS 4 | |
b0322a85 | 322 | Another option used by Courier\-IMAP\&. Append "name" to the name of the top level virtual shared folder index file\&. This setting restricts which virtual shared folders this account could possibly access (and that\*(Aqs on top of whatever else the access control lists say)\&. See the virtual shared folder documentation for more information\&. |
d9898ee8 | 323 | .sp |
b0322a85 | 324 | For technical reasons, group names may not include comma, tab, "/" or "|" characters\&. |
d9898ee8 | 325 | .RE |
326 | .SH "SEE ALSO" | |
327 | .PP | |
b0322a85 CE |
328 | \m[blue]\fB\fBauthlib\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2, |
329 | \m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[2]\d\s+2, | |
330 | \m[blue]\fB\fBauth_getuserinfo\fR(3)\fR\m[]\&\s-2\u[3]\d\s+2, | |
331 | \m[blue]\fB\fBauth_enumerate\fR(3)\fR\m[]\&\s-2\u[4]\d\s+2, | |
332 | \m[blue]\fB\fBauth_passwd\fR(3)\fR\m[]\&\s-2\u[5]\d\s+2, | |
333 | \m[blue]\fB\fBauth_getoption\fR(3)\fR\m[]\&\s-2\u[6]\d\s+2\&. | |
8d138742 | 334 | .SH "NOTES" |
d9898ee8 | 335 | .IP " 1." 4 |
336 | \fBauthlib\fR(3) | |
337 | .RS 4 | |
d50284c4 | 338 | \%http://www.courier-mta.org/authlib/authlib.html |
d9898ee8 | 339 | .RE |
340 | .IP " 2." 4 | |
341 | \fBauth_generic\fR(3) | |
342 | .RS 4 | |
d50284c4 | 343 | \%http://www.courier-mta.org/authlib/auth_generic.html |
d9898ee8 | 344 | .RE |
345 | .IP " 3." 4 | |
346 | \fBauth_getuserinfo\fR(3) | |
347 | .RS 4 | |
d50284c4 | 348 | \%http://www.courier-mta.org/authlib/auth_getuserinfo.html |
d9898ee8 | 349 | .RE |
350 | .IP " 4." 4 | |
351 | \fBauth_enumerate\fR(3) | |
352 | .RS 4 | |
d50284c4 | 353 | \%http://www.courier-mta.org/authlib/auth_enumerate.html |
d9898ee8 | 354 | .RE |
355 | .IP " 5." 4 | |
356 | \fBauth_passwd\fR(3) | |
357 | .RS 4 | |
d50284c4 | 358 | \%http://www.courier-mta.org/authlib/auth_passwd.html |
d9898ee8 | 359 | .RE |
360 | .IP " 6." 4 | |
361 | \fBauth_getoption\fR(3) | |
362 | .RS 4 | |
d50284c4 | 363 | \%http://www.courier-mta.org/authlib/auth_getoption.html |
d9898ee8 | 364 | .RE |