| 1 | '\" t |
| 2 | .\" <!-- Copyright 2004 Double Precision, Inc. See COPYING for --> |
| 3 | .\" <!-- distribution information. --> |
| 4 | .\" Title: auth_getuserinfo |
| 5 | .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] |
| 6 | .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> |
| 7 | .\" Date: 09/08/2017 |
| 8 | .\" Manual: Double Precision, Inc. |
| 9 | .\" Source: Double Precision, Inc. |
| 10 | .\" Language: English |
| 11 | .\" |
| 12 | .TH "AUTH_GETUSERINFO" "3" "09/08/2017" "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 | .\" ----------------------------------------------------------------- |
| 25 | .\" disable hyphenation |
| 26 | .nh |
| 27 | .\" disable justification (adjust text to left margin only) |
| 28 | .ad l |
| 29 | .\" ----------------------------------------------------------------- |
| 30 | .\" * MAIN CONTENT STARTS HERE * |
| 31 | .\" ----------------------------------------------------------------- |
| 32 | .SH "NAME" |
| 33 | auth_getuserinfo \- Obtain account information |
| 34 | .SH "SYNOPSIS" |
| 35 | .sp |
| 36 | .nf |
| 37 | #include <courierauth\&.h> |
| 38 | .fi |
| 39 | .HP \w'int\ rc=auth_getuserinfo('u |
| 40 | .BI "int rc=auth_getuserinfo(const\ char\ *" "userid" ", int\ " "(*callback_func)" "(struct\ authinfo\ *,\ void\ *), void\ *" "callback_arg" ");" |
| 41 | .SH "DESCRIPTION" |
| 42 | .PP |
| 43 | If |
| 44 | \fIuserid\fR |
| 45 | is a valid account name, retrieve the account particulars and invoke |
| 46 | \fIcallback_func\fR\&. |
| 47 | .SH "RETURNS" |
| 48 | .PP |
| 49 | \fBcallback_func\fR |
| 50 | will be invoked if |
| 51 | \fIuserid\fR |
| 52 | exists, and |
| 53 | \fBcallback_func\fR\*(Aqs return value becomes the return value from |
| 54 | \fBauth_getuserinfo\fR |
| 55 | (which should be 0, by convention)\&. |
| 56 | \fBcallback_func\fR |
| 57 | will not be invoked if an error occurs, which is reported by a non\-zero return value from |
| 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 |
| 59 | \fIuserid\fR |
| 60 | does not exist\&. |
| 61 | .PP |
| 62 | The second argument to |
| 63 | \fBcallback_func\fR |
| 64 | will be |
| 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: |
| 66 | .PP |
| 67 | \fBExample\ \&1.\ \&struct authinfo\fR |
| 68 | .sp |
| 69 | .if n \{\ |
| 70 | .RS 4 |
| 71 | .\} |
| 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 |
| 90 | .if n \{\ |
| 91 | .RE |
| 92 | .\} |
| 93 | .PP |
| 94 | Description of the above fields: |
| 95 | .PP |
| 96 | address |
| 97 | .RS 4 |
| 98 | The authenticated login ID\&. |
| 99 | .RE |
| 100 | .PP |
| 101 | sysusername |
| 102 | .RS 4 |
| 103 | The authenticated account\*(Aqs userid and groupid can be looked up in the password file using |
| 104 | address\&. If this field is |
| 105 | NULL, obtain the userid and the groupid from |
| 106 | sysuserid |
| 107 | and |
| 108 | sysgroupid\&. |
| 109 | .RE |
| 110 | .PP |
| 111 | sysuserid |
| 112 | .RS 4 |
| 113 | sysuserid |
| 114 | may be |
| 115 | NULL |
| 116 | if |
| 117 | sysusername |
| 118 | is initialized, otherwise it\*(Aqs a pointer to the account\*(Aqs numeric userid\&. |
| 119 | .RE |
| 120 | .PP |
| 121 | sysgroupid |
| 122 | .RS 4 |
| 123 | Account\*(Aqs numeric groupid\&. |
| 124 | sysgroupid |
| 125 | is only used when |
| 126 | sysusername |
| 127 | is |
| 128 | NULL\&. |
| 129 | .RE |
| 130 | .PP |
| 131 | fullname |
| 132 | .RS 4 |
| 133 | This is the account\*(Aqs full name\&. This field is optional, it may be |
| 134 | NULL\&. |
| 135 | .RE |
| 136 | .PP |
| 137 | homedir |
| 138 | .RS 4 |
| 139 | The account\*(Aqs home directory\&. This field cannot be |
| 140 | NULL\&. |
| 141 | .RE |
| 142 | .PP |
| 143 | maildir |
| 144 | .RS 4 |
| 145 | The pathname to the account\*(Aqs mailbox\&. This field is optional, it can be |
| 146 | NULL |
| 147 | in which case the default location is assumed\&. |
| 148 | .RE |
| 149 | .PP |
| 150 | quota |
| 151 | .RS 4 |
| 152 | Optional maildir quota on the account\*(Aqs mailbox (and |
| 153 | NULL |
| 154 | if no quota is set)\&. |
| 155 | .RE |
| 156 | .PP |
| 157 | passwd |
| 158 | .RS 4 |
| 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: |
| 161 | .sp |
| 162 | .RS 4 |
| 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\&. |
| 171 | .RE |
| 172 | .sp |
| 173 | .RS 4 |
| 174 | .ie n \{\ |
| 175 | \h'-04'\(bu\h'+03'\c |
| 176 | .\} |
| 177 | .el \{\ |
| 178 | .sp -1 |
| 179 | .IP \(bu 2.3 |
| 180 | .\} |
| 181 | \(lq{MD5}\(rq |
| 182 | followed by a base64\-encoded MD5 hash of the password\&. |
| 183 | .RE |
| 184 | .sp |
| 185 | .RS 4 |
| 186 | .ie n \{\ |
| 187 | \h'-04'\(bu\h'+03'\c |
| 188 | .\} |
| 189 | .el \{\ |
| 190 | .sp -1 |
| 191 | .IP \(bu 2.3 |
| 192 | .\} |
| 193 | \(lq{SHA}\(rq |
| 194 | followed by a base64\-encoded SHA1 hash of the password\&. |
| 195 | .RE |
| 196 | .RE |
| 197 | .PP |
| 198 | clearpasswd |
| 199 | .RS 4 |
| 200 | The account\*(Aqs cleartext password, if available\&. If the account has an encrypted password defined, this field can be set to |
| 201 | NULL\&. |
| 202 | .RE |
| 203 | .PP |
| 204 | options |
| 205 | .RS 4 |
| 206 | A comma\-separated list of miscellaneous account options\&. See below for more information\&. |
| 207 | .RE |
| 208 | .SS "Account options" |
| 209 | .PP |
| 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 |
| 213 | \(lq\fIoption\fR=\fIvalue\fR\(rq |
| 214 | settings\&. |
| 215 | .if n \{\ |
| 216 | .sp |
| 217 | .\} |
| 218 | .RS 4 |
| 219 | .it 1 an-trap |
| 220 | .nr an-no-space-flag 1 |
| 221 | .nr an-break-flag 1 |
| 222 | .br |
| 223 | .ps +1 |
| 224 | \fBNote\fR |
| 225 | .ps -1 |
| 226 | .br |
| 227 | .PP |
| 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 \{\ |
| 237 | .sp |
| 238 | .\} |
| 239 | .RS 4 |
| 240 | .it 1 an-trap |
| 241 | .nr an-no-space-flag 1 |
| 242 | .nr an-break-flag 1 |
| 243 | .br |
| 244 | .ps +1 |
| 245 | \fBNote\fR |
| 246 | .ps -1 |
| 247 | .br |
| 248 | .PP |
| 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: |
| 254 | .PP |
| 255 | disableimap=\fIn\fR |
| 256 | .RS 4 |
| 257 | If "n" is 1, IMAP access to this account should be disabled\&. |
| 258 | .RE |
| 259 | .PP |
| 260 | disablepop3=\fIn\fR |
| 261 | .RS 4 |
| 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\&. |
| 273 | .RE |
| 274 | .PP |
| 275 | disablewebmail=\fIn\fR |
| 276 | .RS 4 |
| 277 | If "n" is 1, webmail access to this account should be disabled\&. |
| 278 | .RE |
| 279 | .PP |
| 280 | disableshared=\fIn\fR |
| 281 | .RS 4 |
| 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\&. |
| 283 | .RE |
| 284 | .PP |
| 285 | group=\fIname\fR |
| 286 | .RS 4 |
| 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\&. |
| 290 | .sp |
| 291 | The access group name |
| 292 | \(lqadministrators\(rq |
| 293 | is a reserved group\&. All accounts in the |
| 294 | administrators |
| 295 | group automatically receive all rights to all accessible folders\&. |
| 296 | .if n \{\ |
| 297 | .sp |
| 298 | .\} |
| 299 | .RS 4 |
| 300 | .it 1 an-trap |
| 301 | .nr an-no-space-flag 1 |
| 302 | .nr an-break-flag 1 |
| 303 | .br |
| 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 |
| 311 | .RE |
| 312 | .PP |
| 313 | sharedgroup=\fIname\fR |
| 314 | .RS 4 |
| 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\&. |
| 316 | .sp |
| 317 | For technical reasons, group names may not include comma, tab, "/" or "|" characters\&. |
| 318 | .RE |
| 319 | .SH "SEE ALSO" |
| 320 | .PP |
| 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\&. |
| 327 | .SH "NOTES" |
| 328 | .IP " 1." 4 |
| 329 | \fBauthlib\fR(3) |
| 330 | .RS 4 |
| 331 | \%http://www.courier-mta.org/authlib/authlib.html |
| 332 | .RE |
| 333 | .IP " 2." 4 |
| 334 | \fBauth_generic\fR(3) |
| 335 | .RS 4 |
| 336 | \%http://www.courier-mta.org/authlib/auth_generic.html |
| 337 | .RE |
| 338 | .IP " 3." 4 |
| 339 | \fBauth_login\fR(3) |
| 340 | .RS 4 |
| 341 | \%http://www.courier-mta.org/authlib/auth_login.html |
| 342 | .RE |
| 343 | .IP " 4." 4 |
| 344 | \fBauth_enumerate\fR(3) |
| 345 | .RS 4 |
| 346 | \%http://www.courier-mta.org/authlib/auth_enumerate.html |
| 347 | .RE |
| 348 | .IP " 5." 4 |
| 349 | \fBauth_passwd\fR(3) |
| 350 | .RS 4 |
| 351 | \%http://www.courier-mta.org/authlib/auth_passwd.html |
| 352 | .RE |
| 353 | .IP " 6." 4 |
| 354 | \fBauth_getoption\fR(3) |
| 355 | .RS 4 |
| 356 | \%http://www.courier-mta.org/authlib/auth_getoption.html |
| 357 | .RE |