auth_login.3

   1 '\" t
   2 .\"  <!-- Copyright 2004 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: auth_login
   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_LOGIN" "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_login \- Validate a userid and password
  34 .SH "SYNOPSIS"
  35 .sp
  36 .nf
  37 #include <courierauth\&.h>
  38 .fi
  39 .HP \w'int\ rc=auth_login('u
  40 .BI "int rc=auth_login(const\ char\ *" "service" ", const\ char\ *" "userid" ", const\ char\ *" "password" ", int\ " "(*callback_func)" "(struct\ authinfo\ *,\ void\ *), void\ *" "callback_arg" ");"
  41 .SH "DESCRIPTION"
  42 .PP
  43 \fBauth_login\fR
  44 verifies whether
  45 \fIuserid\fR
  46 exists, and whether it\*(Aqs
  47 \fIpassword\fR
  48 is correct\&.
  49 \fIservice\fR
  50 specifies which so\-called "service" is being authenticated; like
  51 \(lqimap\(rq
  52 or
  53 \(lqpop3\(rq\&.
  54 \fIservice\fR
  55 may or may not be used by the Courier authentication library\*(Aqs configured back\-end module\&.
  56 .SH "RETURNS"
  57 .PP
  58 \fBcallback_func\fR
  59 will be invoked if
  60 \fBauth_login\fR
  61 succeeds, and
  62 \fBcallback_func\fR\*(Aqs return value becomes the return value from
  63 \fBauth_login\fR
  64 (which should be 0, by convention)\&.
  65 \fBcallback_func\fR
  66 will not be invoked if an error occurs, which is reported by a non\-zero return value from
  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\&.
  68 .PP
  69 The second argument to
  70 \fBcallback_func\fR
  71 will be
  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:
  73 .PP
  74 \fBExample\ \&1.\ \&struct authinfo\fR
  75 .sp
  76 .if n \{\
  77 .RS 4
  78 .\}
  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
  97 .if n \{\
  98 .RE
  99 .\}
 100 .PP
 101 Description of the above fields:
 102 .PP
 103 address
 104 .RS 4
 105 The authenticated login ID\&.
 106 .RE
 107 .PP
 108 sysusername
 109 .RS 4
 110 The authenticated account\*(Aqs userid and groupid can be looked up in the password file using
 111 address\&. If this field is
 112 NULL, obtain the userid and the groupid from
 113 sysuserid
 114 and
 115 sysgroupid\&.
 116 .RE
 117 .PP
 118 sysuserid
 119 .RS 4
 120 sysuserid
 121 may be
 122 NULL
 123 if
 124 sysusername
 125 is initialized, otherwise it\*(Aqs a pointer to the account\*(Aqs numeric userid\&.
 126 .RE
 127 .PP
 128 sysgroupid
 129 .RS 4
 130 Account\*(Aqs numeric groupid\&.
 131 sysgroupid
 132 is only used when
 133 sysusername
 134 is
 135 NULL\&.
 136 .RE
 137 .PP
 138 fullname
 139 .RS 4
 140 This is the account\*(Aqs full name\&. This field is optional, it may be
 141 NULL\&.
 142 .RE
 143 .PP
 144 homedir
 145 .RS 4
 146 The account\*(Aqs home directory\&. This field cannot be
 147 NULL\&.
 148 .RE
 149 .PP
 150 maildir
 151 .RS 4
 152 The pathname to the account\*(Aqs mailbox\&. This field is optional, it can be
 153 NULL
 154 in which case the default location is assumed\&.
 155 .RE
 156 .PP
 157 quota
 158 .RS 4
 159 Optional maildir quota on the account\*(Aqs mailbox (and
 160 NULL
 161 if no quota is set)\&.
 162 .RE
 163 .PP
 164 passwd
 165 .RS 4
 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:
 168 .sp
 169 .RS 4
 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\&.
 178 .RE
 179 .sp
 180 .RS 4
 181 .ie n \{\
 182 \h'-04'\(bu\h'+03'\c
 183 .\}
 184 .el \{\
 185 .sp -1
 186 .IP \(bu 2.3
 187 .\}
 188 \(lq{MD5}\(rq
 189 followed by a base64\-encoded MD5 hash of the password\&.
 190 .RE
 191 .sp
 192 .RS 4
 193 .ie n \{\
 194 \h'-04'\(bu\h'+03'\c
 195 .\}
 196 .el \{\
 197 .sp -1
 198 .IP \(bu 2.3
 199 .\}
 200 \(lq{SHA}\(rq
 201 followed by a base64\-encoded SHA1 hash of the password\&.
 202 .RE
 203 .RE
 204 .PP
 205 clearpasswd
 206 .RS 4
 207 The account\*(Aqs cleartext password, if available\&. If the account has an encrypted password defined, this field can be set to
 208 NULL\&.
 209 .RE
 210 .PP
 211 options
 212 .RS 4
 213 A comma\-separated list of miscellaneous account options\&. See below for more information\&.
 214 .RE
 215 .SS "Account options"
 216 .PP
 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
 220 \(lq\fIoption\fR=\fIvalue\fR\(rq
 221 settings\&.
 222 .if n \{\
 223 .sp
 224 .\}
 225 .RS 4
 226 .it 1 an-trap
 227 .nr an-no-space-flag 1
 228 .nr an-break-flag 1
 229 .br
 230 .ps +1
 231 \fBNote\fR
 232 .ps -1
 233 .br
 234 .PP
 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 \{\
 244 .sp
 245 .\}
 246 .RS 4
 247 .it 1 an-trap
 248 .nr an-no-space-flag 1
 249 .nr an-break-flag 1
 250 .br
 251 .ps +1
 252 \fBNote\fR
 253 .ps -1
 254 .br
 255 .PP
 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:
 261 .PP
 262 disableimap=\fIn\fR
 263 .RS 4
 264 If "n" is 1, IMAP access to this account should be disabled\&.
 265 .RE
 266 .PP
 267 disablepop3=\fIn\fR
 268 .RS 4
 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\&.
 280 .RE
 281 .PP
 282 disablewebmail=\fIn\fR
 283 .RS 4
 284 If "n" is 1, webmail access to this account should be disabled\&.
 285 .RE
 286 .PP
 287 disableshared=\fIn\fR
 288 .RS 4
 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\&.
 290 .RE
 291 .PP
 292 group=\fIname\fR
 293 .RS 4
 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\&.
 297 .sp
 298 The access group name
 299 \(lqadministrators\(rq
 300 is a reserved group\&. All accounts in the
 301 administrators
 302 group automatically receive all rights to all accessible folders\&.
 303 .if n \{\
 304 .sp
 305 .\}
 306 .RS 4
 307 .it 1 an-trap
 308 .nr an-no-space-flag 1
 309 .nr an-break-flag 1
 310 .br
 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
 318 .RE
 319 .PP
 320 sharedgroup=\fIname\fR
 321 .RS 4
 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\&.
 323 .sp
 324 For technical reasons, group names may not include comma, tab, "/" or "|" characters\&.
 325 .RE
 326 .SH "SEE ALSO"
 327 .PP
 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\&.
 334 .SH "NOTES"
 335 .IP " 1." 4
 336 \fBauthlib\fR(3)
 337 .RS 4
 338 \%http://www.courier-mta.org/authlib/authlib.html
 339 .RE
 340 .IP " 2." 4
 341 \fBauth_generic\fR(3)
 342 .RS 4
 343 \%http://www.courier-mta.org/authlib/auth_generic.html
 344 .RE
 345 .IP " 3." 4
 346 \fBauth_getuserinfo\fR(3)
 347 .RS 4
 348 \%http://www.courier-mta.org/authlib/auth_getuserinfo.html
 349 .RE
 350 .IP " 4." 4
 351 \fBauth_enumerate\fR(3)
 352 .RS 4
 353 \%http://www.courier-mta.org/authlib/auth_enumerate.html
 354 .RE
 355 .IP " 5." 4
 356 \fBauth_passwd\fR(3)
 357 .RS 4
 358 \%http://www.courier-mta.org/authlib/auth_passwd.html
 359 .RE
 360 .IP " 6." 4
 361 \fBauth_getoption\fR(3)
 362 .RS 4
 363 \%http://www.courier-mta.org/authlib/auth_getoption.html
 364 .RE