| 1 | '\" t |
| 2 | .\" <!-- Copyright 2004 Double Precision, Inc. See COPYING for --> |
| 3 | .\" <!-- distribution information. --> |
| 4 | .\" Title: auth_generic |
| 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: 06/20/2015 |
| 8 | .\" Manual: Double Precision, Inc. |
| 9 | .\" Source: Double Precision, Inc. |
| 10 | .\" Language: English |
| 11 | .\" |
| 12 | .TH "AUTH_GENERIC" "3" "06/20/2015" "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_generic \- Generic authentication request |
| 34 | .SH "SYNOPSIS" |
| 35 | .sp |
| 36 | .nf |
| 37 | #include <courierauth\&.h> |
| 38 | .fi |
| 39 | .HP \w'int\ rc=auth_generic('u |
| 40 | .BI "int rc=auth_generic(const\ char\ *" "service" ", const\ char\ *" "authtype" ", const\ char\ *" "authdata" ", int\ " "(*callback_func)" "\ (struct\ authinfo\ *,\ void\ *), void\ *" "callback_arg" ");" |
| 41 | .SH "DESCRIPTION" |
| 42 | .PP |
| 43 | \fBauth_generic\fR |
| 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\&. |
| 46 | \fIservice\fR |
| 47 | specifies which so\-called "service" is being authenticated; like |
| 48 | \(lqimap\(rq |
| 49 | or |
| 50 | \(lqpop3\(rq\&. |
| 51 | \fIservice\fR |
| 52 | may or may not be used by the Courier authentication library\*(Aqs configured back\-end module\&. |
| 53 | .PP |
| 54 | \fBauthtype\fR |
| 55 | specifies the format of the authentication request\&. Three authentication formats are defined in |
| 56 | courierauth\&.h: |
| 57 | .PP |
| 58 | AUTHTYPE_LOGIN |
| 59 | .RS 4 |
| 60 | \fIauthdata\fR |
| 61 | contains the following string: |
| 62 | \(lq\fIuserid\fR\en\fIpassword\fR\en\(rq\&. That is, the userid being authenticated, an |
| 63 | ASCII |
| 64 | newline character, the password, and a second newline character\&. |
| 65 | .RE |
| 66 | .PP |
| 67 | AUTHTYPE_CRAMMD5 or AUTHTYPE_CRAMSHA1 |
| 68 | .RS 4 |
| 69 | This format is used with |
| 70 | CRAM\-MD5 |
| 71 | or |
| 72 | CRAM\-SHA1\&. |
| 73 | \fIauthdata\fR |
| 74 | contains the following string: |
| 75 | \(lq\fIchallenge\fR\en\fIresponse\fR\en\(rq\&. |
| 76 | \fIchallenge\fR |
| 77 | is the base64\-encoded challenge, which is followed by an |
| 78 | ASCII |
| 79 | newline character\&. |
| 80 | \fIresponse\fR |
| 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\&. |
| 82 | .RE |
| 83 | .SH "RETURNS" |
| 84 | .PP |
| 85 | \fBcallback_func\fR |
| 86 | will be invoked if |
| 87 | \fBauth_generic\fR |
| 88 | succeeds, and |
| 89 | \fBcallback_func\fR\*(Aqs return value becomes the return value from |
| 90 | \fBauth_generic\fR |
| 91 | (which should be 0, by convention)\&. |
| 92 | \fBcallback_func\fR |
| 93 | will not be invoked if an error occurs, which is reported by a non\-zero return value from |
| 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\&. |
| 95 | .PP |
| 96 | The second argument to |
| 97 | \fBcallback_func\fR |
| 98 | will be |
| 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: |
| 100 | .PP |
| 101 | \fBExample\ \&1.\ \&struct authinfo\fR |
| 102 | .sp |
| 103 | .if n \{\ |
| 104 | .RS 4 |
| 105 | .\} |
| 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 |
| 124 | .if n \{\ |
| 125 | .RE |
| 126 | .\} |
| 127 | .PP |
| 128 | Description of the above fields: |
| 129 | .PP |
| 130 | address |
| 131 | .RS 4 |
| 132 | The authenticated login ID\&. |
| 133 | .RE |
| 134 | .PP |
| 135 | sysusername |
| 136 | .RS 4 |
| 137 | The authenticated account\*(Aqs userid and groupid can be looked up in the password file using |
| 138 | address\&. If this field is |
| 139 | NULL, obtain the userid and the groupid from |
| 140 | sysuserid |
| 141 | and |
| 142 | sysgroupid\&. |
| 143 | .RE |
| 144 | .PP |
| 145 | sysuserid |
| 146 | .RS 4 |
| 147 | sysuserid |
| 148 | may be |
| 149 | NULL |
| 150 | if |
| 151 | sysusername |
| 152 | is initialized, otherwise it\*(Aqs a pointer to the account\*(Aqs numeric userid\&. |
| 153 | .RE |
| 154 | .PP |
| 155 | sysgroupid |
| 156 | .RS 4 |
| 157 | Account\*(Aqs numeric groupid\&. |
| 158 | sysgroupid |
| 159 | is only used when |
| 160 | sysusername |
| 161 | is |
| 162 | NULL\&. |
| 163 | .RE |
| 164 | .PP |
| 165 | fullname |
| 166 | .RS 4 |
| 167 | This is the account\*(Aqs full name\&. This field is optional, it may be |
| 168 | NULL\&. |
| 169 | .RE |
| 170 | .PP |
| 171 | homedir |
| 172 | .RS 4 |
| 173 | The account\*(Aqs home directory\&. This field cannot be |
| 174 | NULL\&. |
| 175 | .RE |
| 176 | .PP |
| 177 | maildir |
| 178 | .RS 4 |
| 179 | The pathname to the account\*(Aqs mailbox\&. This field is optional, it can be |
| 180 | NULL |
| 181 | in which case the default location is assumed\&. |
| 182 | .RE |
| 183 | .PP |
| 184 | quota |
| 185 | .RS 4 |
| 186 | Optional maildir quota on the account\*(Aqs mailbox (and |
| 187 | NULL |
| 188 | if no quota is set)\&. |
| 189 | .RE |
| 190 | .PP |
| 191 | passwd |
| 192 | .RS 4 |
| 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: |
| 195 | .sp |
| 196 | .RS 4 |
| 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\&. |
| 205 | .RE |
| 206 | .sp |
| 207 | .RS 4 |
| 208 | .ie n \{\ |
| 209 | \h'-04'\(bu\h'+03'\c |
| 210 | .\} |
| 211 | .el \{\ |
| 212 | .sp -1 |
| 213 | .IP \(bu 2.3 |
| 214 | .\} |
| 215 | \(lq{MD5}\(rq |
| 216 | followed by a base64\-encoded MD5 hash of the password\&. |
| 217 | .RE |
| 218 | .sp |
| 219 | .RS 4 |
| 220 | .ie n \{\ |
| 221 | \h'-04'\(bu\h'+03'\c |
| 222 | .\} |
| 223 | .el \{\ |
| 224 | .sp -1 |
| 225 | .IP \(bu 2.3 |
| 226 | .\} |
| 227 | \(lq{SHA}\(rq |
| 228 | followed by a base64\-encoded SHA1 hash of the password\&. |
| 229 | .RE |
| 230 | .RE |
| 231 | .PP |
| 232 | clearpasswd |
| 233 | .RS 4 |
| 234 | The account\*(Aqs cleartext password, if available\&. If the account has an encrypted password defined, this field can be set to |
| 235 | NULL\&. |
| 236 | .RE |
| 237 | .PP |
| 238 | options |
| 239 | .RS 4 |
| 240 | A comma\-separated list of miscellaneous account options\&. See below for more information\&. |
| 241 | .RE |
| 242 | .SS "Account options" |
| 243 | .PP |
| 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 |
| 247 | \(lq\fIoption\fR=\fIvalue\fR\(rq |
| 248 | settings\&. |
| 249 | .if n \{\ |
| 250 | .sp |
| 251 | .\} |
| 252 | .RS 4 |
| 253 | .it 1 an-trap |
| 254 | .nr an-no-space-flag 1 |
| 255 | .nr an-break-flag 1 |
| 256 | .br |
| 257 | .ps +1 |
| 258 | \fBNote\fR |
| 259 | .ps -1 |
| 260 | .br |
| 261 | .PP |
| 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 \{\ |
| 271 | .sp |
| 272 | .\} |
| 273 | .RS 4 |
| 274 | .it 1 an-trap |
| 275 | .nr an-no-space-flag 1 |
| 276 | .nr an-break-flag 1 |
| 277 | .br |
| 278 | .ps +1 |
| 279 | \fBNote\fR |
| 280 | .ps -1 |
| 281 | .br |
| 282 | .PP |
| 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: |
| 288 | .PP |
| 289 | disableimap=\fIn\fR |
| 290 | .RS 4 |
| 291 | If "n" is 1, IMAP access to this account should be disabled\&. |
| 292 | .RE |
| 293 | .PP |
| 294 | disablepop3=\fIn\fR |
| 295 | .RS 4 |
| 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\&. |
| 307 | .RE |
| 308 | .PP |
| 309 | disablewebmail=\fIn\fR |
| 310 | .RS 4 |
| 311 | If "n" is 1, webmail access to this account should be disabled\&. |
| 312 | .RE |
| 313 | .PP |
| 314 | disableshared=\fIn\fR |
| 315 | .RS 4 |
| 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\&. |
| 317 | .RE |
| 318 | .PP |
| 319 | group=\fIname\fR |
| 320 | .RS 4 |
| 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\&. |
| 324 | .sp |
| 325 | The access group name |
| 326 | \(lqadministrators\(rq |
| 327 | is a reserved group\&. All accounts in the |
| 328 | administrators |
| 329 | group automatically receive all rights to all accessible folders\&. |
| 330 | .if n \{\ |
| 331 | .sp |
| 332 | .\} |
| 333 | .RS 4 |
| 334 | .it 1 an-trap |
| 335 | .nr an-no-space-flag 1 |
| 336 | .nr an-break-flag 1 |
| 337 | .br |
| 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 |
| 345 | .RE |
| 346 | .PP |
| 347 | sharedgroup=\fIname\fR |
| 348 | .RS 4 |
| 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\&. |
| 350 | .sp |
| 351 | For technical reasons, group names may not include comma, tab, "/" or "|" characters\&. |
| 352 | .RE |
| 353 | .SH "SEE ALSO" |
| 354 | .PP |
| 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\&. |
| 361 | .SH "NOTES" |
| 362 | .IP " 1." 4 |
| 363 | \fBauth_login\fR(3) |
| 364 | .RS 4 |
| 365 | \%http://www.courier-mta.org/authlib/auth_login.html |
| 366 | .RE |
| 367 | .IP " 2." 4 |
| 368 | \fBauthlib\fR(3) |
| 369 | .RS 4 |
| 370 | \%http://www.courier-mta.org/authlib/authlib.html |
| 371 | .RE |
| 372 | .IP " 3." 4 |
| 373 | \fBauth_getuserinfo\fR(3) |
| 374 | .RS 4 |
| 375 | \%http://www.courier-mta.org/authlib/auth_getuserinfo.html |
| 376 | .RE |
| 377 | .IP " 4." 4 |
| 378 | \fBauth_enumerate\fR(3) |
| 379 | .RS 4 |
| 380 | \%http://www.courier-mta.org/authlib/auth_enumerate.html |
| 381 | .RE |
| 382 | .IP " 5." 4 |
| 383 | \fBauth_passwd\fR(3) |
| 384 | .RS 4 |
| 385 | \%http://www.courier-mta.org/authlib/auth_passwd.html |
| 386 | .RE |
| 387 | .IP " 6." 4 |
| 388 | \fBauth_getoption\fR(3) |
| 389 | .RS 4 |
| 390 | \%http://www.courier-mta.org/authlib/auth_getoption.html |
| 391 | .RE |