Commit | Line | Data |
---|---|---|
b0322a85 | 1 | '\" t |
d9898ee8 | 2 | .\" <!-- Copyright 2004 Double Precision, Inc. See COPYING for --> |
3 | .\" <!-- distribution information. --> | |
4 | .\" Title: auth_generic | |
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/> | |
7 | .\" Date: 08/25/2013 | |
d9898ee8 | 8 | .\" Manual: Double Precision, Inc. |
9 | .\" Source: Double Precision, Inc. | |
b0322a85 | 10 | .\" Language: English |
d9898ee8 | 11 | .\" |
b0322a85 CE |
12 | .TH "AUTH_GENERIC" "3" "08/25/2013" "Double Precision, Inc." "Double Precision, Inc." |
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_generic \- Generic authentication request |
d9898ee8 | 34 | .SH "SYNOPSIS" |
35 | .sp | |
d9898ee8 | 36 | .nf |
b0322a85 | 37 | #include <courierauth\&.h> |
d9898ee8 | 38 | .fi |
b0322a85 | 39 | .HP \w'int\ rc=auth_generic('u |
dd184caf | 40 | .BI "int rc=auth_generic(const\ char\ *" "service" ", const\ char\ *" "authtype" ", const\ char\ *" "authdata" ", int\ " "(*callback_func)" "\ (struct\ authinfo\ *,\ void\ *), void\ *" "callback_arg" ");" |
d9898ee8 | 41 | .SH "DESCRIPTION" |
42 | .PP | |
d9898ee8 | 43 | \fBauth_generic\fR |
b0322a85 CE |
44 | processes a generic authentication request\&. You do not want to use this function\&. You really want to use |
45 | \m[blue]\fB\fBauth_login\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2\&. | |
d9898ee8 | 46 | \fIservice\fR |
47 | specifies which so\-called "service" is being authenticated; like | |
48 | \(lqimap\(rq | |
49 | or | |
b0322a85 | 50 | \(lqpop3\(rq\&. |
d9898ee8 | 51 | \fIservice\fR |
b0322a85 | 52 | may or may not be used by the Courier authentication library\*(Aqs configured back\-end module\&. |
d9898ee8 | 53 | .PP |
d9898ee8 | 54 | \fBauthtype\fR |
b0322a85 CE |
55 | specifies the format of the authentication request\&. Three authentication formats are defined in |
56 | courierauth\&.h: | |
d9898ee8 | 57 | .PP |
58 | AUTHTYPE_LOGIN | |
59 | .RS 4 | |
d9898ee8 | 60 | \fIauthdata\fR |
61 | contains the following string: | |
b0322a85 | 62 | \(lq\fIuserid\fR\en\fIpassword\fR\en\(rq\&. That is, the userid being authenticated, an |
d9898ee8 | 63 | ASCII |
b0322a85 | 64 | newline character, the password, and a second newline character\&. |
d9898ee8 | 65 | .RE |
66 | .PP | |
67 | AUTHTYPE_CRAMMD5 or AUTHTYPE_CRAMSHA1 | |
68 | .RS 4 | |
69 | This format is used with | |
70 | CRAM\-MD5 | |
71 | or | |
b0322a85 | 72 | CRAM\-SHA1\&. |
d9898ee8 | 73 | \fIauthdata\fR |
74 | contains the following string: | |
b0322a85 | 75 | \(lq\fIchallenge\fR\en\fIresponse\fR\en\(rq\&. |
d9898ee8 | 76 | \fIchallenge\fR |
77 | is the base64\-encoded challenge, which is followed by an | |
78 | ASCII | |
b0322a85 | 79 | newline character\&. |
d9898ee8 | 80 | \fIresponse\fR |
b0322a85 | 81 | is a base64\-encoded string that\*(Aqs followed by a second newline character\&. The base64\-encoded string consists of the responding userid, a space character, then the response to the challenge expressed as hexadecimal digits\&. |
d9898ee8 | 82 | .RE |
83 | .SH "RETURNS" | |
84 | .PP | |
d9898ee8 | 85 | \fBcallback_func\fR |
86 | will be invoked if | |
87 | \fBauth_generic\fR | |
88 | succeeds, and | |
b0322a85 | 89 | \fBcallback_func\fR\*(Aqs return value becomes the return value from |
d9898ee8 | 90 | \fBauth_generic\fR |
b0322a85 | 91 | (which should be 0, by convention)\&. |
d9898ee8 | 92 | \fBcallback_func\fR |
93 | will not be invoked if an error occurs, which is reported by a non\-zero return value from | |
b0322a85 | 94 | \fBauth_generic\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 | 95 | .PP |
96 | The second argument to | |
97 | \fBcallback_func\fR | |
98 | will be | |
b0322a85 | 99 | \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 | 100 | .PP |
b0322a85 | 101 | \fBExample\ \&1.\ \&struct authinfo\fR |
d9898ee8 | 102 | .sp |
b0322a85 | 103 | .if n \{\ |
d9898ee8 | 104 | .RS 4 |
b0322a85 | 105 | .\} |
d9898ee8 | 106 | .nf |
107 | struct authinfo { | |
108 | const char *sysusername; | |
109 | const uid_t *sysuserid; | |
110 | gid_t sysgroupid; | |
111 | const char *homedir; | |
112 | ||
113 | const char *address; | |
114 | const char *fullname; | |
115 | const char *maildir; | |
116 | const char *quota; | |
117 | const char *passwd; | |
118 | const char *clearpasswd; | |
119 | ||
120 | const char *options; | |
121 | ||
122 | } ; | |
123 | .fi | |
b0322a85 | 124 | .if n \{\ |
d9898ee8 | 125 | .RE |
b0322a85 | 126 | .\} |
d9898ee8 | 127 | .PP |
128 | Description of the above fields: | |
129 | .PP | |
130 | address | |
131 | .RS 4 | |
b0322a85 | 132 | The authenticated login ID\&. |
d9898ee8 | 133 | .RE |
134 | .PP | |
135 | sysusername | |
136 | .RS 4 | |
b0322a85 CE |
137 | The authenticated account\*(Aqs userid and groupid can be looked up in the password file using |
138 | address\&. If this field is | |
d9898ee8 | 139 | NULL, obtain the userid and the groupid from |
140 | sysuserid | |
141 | and | |
b0322a85 | 142 | sysgroupid\&. |
d9898ee8 | 143 | .RE |
144 | .PP | |
145 | sysuserid | |
146 | .RS 4 | |
d9898ee8 | 147 | sysuserid |
148 | may be | |
149 | NULL | |
150 | if | |
151 | sysusername | |
b0322a85 | 152 | is initialized, otherwise it\*(Aqs a pointer to the account\*(Aqs numeric userid\&. |
d9898ee8 | 153 | .RE |
154 | .PP | |
155 | sysgroupid | |
156 | .RS 4 | |
b0322a85 | 157 | Account\*(Aqs numeric groupid\&. |
d9898ee8 | 158 | sysgroupid |
159 | is only used when | |
160 | sysusername | |
161 | is | |
b0322a85 | 162 | NULL\&. |
d9898ee8 | 163 | .RE |
164 | .PP | |
165 | fullname | |
166 | .RS 4 | |
b0322a85 CE |
167 | This is the account\*(Aqs full name\&. This field is optional, it may be |
168 | NULL\&. | |
d9898ee8 | 169 | .RE |
170 | .PP | |
171 | homedir | |
172 | .RS 4 | |
b0322a85 CE |
173 | The account\*(Aqs home directory\&. This field cannot be |
174 | NULL\&. | |
d9898ee8 | 175 | .RE |
176 | .PP | |
177 | maildir | |
178 | .RS 4 | |
b0322a85 | 179 | The pathname to the account\*(Aqs mailbox\&. This field is optional, it can be |
d9898ee8 | 180 | NULL |
b0322a85 | 181 | in which case the default location is assumed\&. |
d9898ee8 | 182 | .RE |
183 | .PP | |
184 | quota | |
185 | .RS 4 | |
b0322a85 | 186 | Optional maildir quota on the account\*(Aqs mailbox (and |
d9898ee8 | 187 | NULL |
b0322a85 | 188 | if no quota is set)\&. |
d9898ee8 | 189 | .RE |
190 | .PP | |
191 | passwd | |
192 | .RS 4 | |
b0322a85 CE |
193 | The account\*(Aqs encrypted password, if available\&. If the account has a cleartext password defined, this field can be set to |
194 | NULL\&. The encrypted password can take several formats: | |
8d138742 | 195 | .sp |
d9898ee8 | 196 | .RS 4 |
b0322a85 CE |
197 | .ie n \{\ |
198 | \h'-04'\(bu\h'+03'\c | |
199 | .\} | |
200 | .el \{\ | |
201 | .sp -1 | |
202 | .IP \(bu 2.3 | |
203 | .\} | |
204 | A traditional triple\-DES crypted password, or a MD5+salt\-hashed password, as used in Linux\&. | |
d9898ee8 | 205 | .RE |
8d138742 | 206 | .sp |
d9898ee8 | 207 | .RS 4 |
b0322a85 CE |
208 | .ie n \{\ |
209 | \h'-04'\(bu\h'+03'\c | |
210 | .\} | |
211 | .el \{\ | |
212 | .sp -1 | |
213 | .IP \(bu 2.3 | |
214 | .\} | |
d9898ee8 | 215 | \(lq{MD5}\(rq |
b0322a85 | 216 | followed by a base64\-encoded MD5 hash of the password\&. |
d9898ee8 | 217 | .RE |
8d138742 | 218 | .sp |
d9898ee8 | 219 | .RS 4 |
b0322a85 CE |
220 | .ie n \{\ |
221 | \h'-04'\(bu\h'+03'\c | |
222 | .\} | |
223 | .el \{\ | |
224 | .sp -1 | |
225 | .IP \(bu 2.3 | |
226 | .\} | |
d9898ee8 | 227 | \(lq{SHA}\(rq |
b0322a85 | 228 | followed by a base64\-encoded SHA1 hash of the password\&. |
d9898ee8 | 229 | .RE |
230 | .RE | |
231 | .PP | |
232 | clearpasswd | |
233 | .RS 4 | |
b0322a85 CE |
234 | The account\*(Aqs cleartext password, if available\&. If the account has an encrypted password defined, this field can be set to |
235 | NULL\&. | |
d9898ee8 | 236 | .RE |
237 | .PP | |
238 | options | |
239 | .RS 4 | |
b0322a85 | 240 | A comma\-separated list of miscellaneous account options\&. See below for more information\&. |
d9898ee8 | 241 | .RE |
242 | .SS "Account options" | |
243 | .PP | |
b0322a85 CE |
244 | 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 |
245 | NULL | |
246 | value\&. Otherwise it will be a comma\-separated list of | |
d9898ee8 | 247 | \(lq\fIoption\fR=\fIvalue\fR\(rq |
b0322a85 CE |
248 | settings\&. |
249 | .if n \{\ | |
d9898ee8 | 250 | .sp |
b0322a85 CE |
251 | .\} |
252 | .RS 4 | |
d9898ee8 | 253 | .it 1 an-trap |
254 | .nr an-no-space-flag 1 | |
255 | .nr an-break-flag 1 | |
256 | .br | |
b0322a85 CE |
257 | .ps +1 |
258 | \fBNote\fR | |
259 | .ps -1 | |
260 | .br | |
d9898ee8 | 261 | .PP |
b0322a85 CE |
262 | The application is responsible for actually implementing the options\&. For example, sn authentication request for service |
263 | \(lqimap\(rq, for example, will succeed provided that the userid and the password are valid, even if | |
264 | \(lqdisableimap=1\(rq | |
265 | is set\&. The application\*(Aqs | |
266 | \fBcallback_func\fR | |
267 | should check for this condition, and return a negative return code\&. | |
268 | .sp .5v | |
269 | .RE | |
270 | .if n \{\ | |
d9898ee8 | 271 | .sp |
b0322a85 CE |
272 | .\} |
273 | .RS 4 | |
d9898ee8 | 274 | .it 1 an-trap |
275 | .nr an-no-space-flag 1 | |
276 | .nr an-break-flag 1 | |
277 | .br | |
b0322a85 CE |
278 | .ps +1 |
279 | \fBNote\fR | |
280 | .ps -1 | |
281 | .br | |
d9898ee8 | 282 | .PP |
b0322a85 CE |
283 | 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\&. |
284 | .sp .5v | |
285 | .RE | |
286 | .PP | |
287 | The following options are recognized by the various Courier packages: | |
d9898ee8 | 288 | .PP |
289 | disableimap=\fIn\fR | |
290 | .RS 4 | |
b0322a85 | 291 | If "n" is 1, IMAP access to this account should be disabled\&. |
d9898ee8 | 292 | .RE |
293 | .PP | |
294 | disablepop3=\fIn\fR | |
295 | .RS 4 | |
b0322a85 CE |
296 | If "n" is 1, POP3 access to this account should be disabled\&. |
297 | .RE | |
298 | .PP | |
299 | disableinsecureimap=\fIn\fR | |
300 | .RS 4 | |
301 | If "n" is 1, unencrypted IMAP access to this account should be disabled\&. | |
302 | .RE | |
303 | .PP | |
304 | disableinsecurepop3=\fIn\fR | |
305 | .RS 4 | |
306 | If "n" is 1, unencrypted POP3 access to this account should be disabled\&. | |
d9898ee8 | 307 | .RE |
308 | .PP | |
309 | disablewebmail=\fIn\fR | |
310 | .RS 4 | |
b0322a85 | 311 | If "n" is 1, webmail access to this account should be disabled\&. |
d9898ee8 | 312 | .RE |
313 | .PP | |
314 | disableshared=\fIn\fR | |
315 | .RS 4 | |
b0322a85 | 316 | 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 | 317 | .RE |
318 | .PP | |
319 | group=\fIname\fR | |
320 | .RS 4 | |
b0322a85 CE |
321 | This option is used by Courier\-IMAP in calculating access control lists\&. This option places the account as a member of access group |
322 | \fIname\fR\&. Instead of granting access rights on individual mail folders to individual accounts, the access rights can be granted to an access group | |
323 | \(lqname\(rq, and all members of this group get the specified access rights\&. | |
d9898ee8 | 324 | .sp |
325 | The access group name | |
326 | \(lqadministrators\(rq | |
b0322a85 | 327 | is a reserved group\&. All accounts in the |
d9898ee8 | 328 | administrators |
b0322a85 CE |
329 | group automatically receive all rights to all accessible folders\&. |
330 | .if n \{\ | |
d9898ee8 | 331 | .sp |
b0322a85 CE |
332 | .\} |
333 | .RS 4 | |
d9898ee8 | 334 | .it 1 an-trap |
335 | .nr an-no-space-flag 1 | |
336 | .nr an-break-flag 1 | |
337 | .br | |
b0322a85 CE |
338 | .ps +1 |
339 | \fBNote\fR | |
340 | .ps -1 | |
341 | .br | |
342 | This option may be specified multiple times to specify that the account belongs to multiple account groups\&. | |
343 | .sp .5v | |
344 | .RE | |
d9898ee8 | 345 | .RE |
346 | .PP | |
347 | sharedgroup=\fIname\fR | |
348 | .RS 4 | |
b0322a85 | 349 | 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 | 350 | .sp |
b0322a85 | 351 | For technical reasons, group names may not include comma, tab, "/" or "|" characters\&. |
d9898ee8 | 352 | .RE |
353 | .SH "SEE ALSO" | |
354 | .PP | |
b0322a85 CE |
355 | \m[blue]\fB\fBauthlib\fR(3)\fR\m[]\&\s-2\u[2]\d\s+2, |
356 | \m[blue]\fB\fBauth_login\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2, | |
357 | \m[blue]\fB\fBauth_getuserinfo\fR(3)\fR\m[]\&\s-2\u[3]\d\s+2, | |
358 | \m[blue]\fB\fBauth_enumerate\fR(3)\fR\m[]\&\s-2\u[4]\d\s+2, | |
359 | \m[blue]\fB\fBauth_passwd\fR(3)\fR\m[]\&\s-2\u[5]\d\s+2, | |
360 | \m[blue]\fB\fBauth_getoption\fR(3)\fR\m[]\&\s-2\u[6]\d\s+2\&. | |
8d138742 | 361 | .SH "NOTES" |
d9898ee8 | 362 | .IP " 1." 4 |
363 | \fBauth_login\fR(3) | |
364 | .RS 4 | |
b0322a85 | 365 | \%[set $man.base.url.for.relative.links]/auth_login.html |
d9898ee8 | 366 | .RE |
367 | .IP " 2." 4 | |
368 | \fBauthlib\fR(3) | |
369 | .RS 4 | |
b0322a85 | 370 | \%[set $man.base.url.for.relative.links]/authlib.html |
d9898ee8 | 371 | .RE |
372 | .IP " 3." 4 | |
373 | \fBauth_getuserinfo\fR(3) | |
374 | .RS 4 | |
b0322a85 | 375 | \%[set $man.base.url.for.relative.links]/auth_getuserinfo.html |
d9898ee8 | 376 | .RE |
377 | .IP " 4." 4 | |
378 | \fBauth_enumerate\fR(3) | |
379 | .RS 4 | |
b0322a85 | 380 | \%[set $man.base.url.for.relative.links]/auth_enumerate.html |
d9898ee8 | 381 | .RE |
382 | .IP " 5." 4 | |
383 | \fBauth_passwd\fR(3) | |
384 | .RS 4 | |
b0322a85 | 385 | \%[set $man.base.url.for.relative.links]/auth_passwd.html |
d9898ee8 | 386 | .RE |
387 | .IP " 6." 4 | |
388 | \fBauth_getoption\fR(3) | |
389 | .RS 4 | |
b0322a85 | 390 | \%[set $man.base.url.for.relative.links]/auth_getoption.html |
d9898ee8 | 391 | .RE |