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