Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AUTH_LOGIN(3)		    Double Precision, Inc.		 AUTH_LOGIN(3)

NAME
       auth_login - Validate a userid and password

SYNOPSIS
       #include	<courierauth.h>

       int rc=auth_login(const char *service, const char *userid,
			 const char *password,
			 int (*callback_func)(struct authinfo *, void *),
			 void *callback_arg);

DESCRIPTION
       auth_login verifies whether userid exists, and whether it's password is
       correct.	 service specifies which so-called "service" is	being
       authenticated; like "imap" or "pop3".  service may or may not be	used
       by the Courier authentication library's configured back-end module.

RETURNS
       callback_func will be invoked if	auth_login succeeds, and
       callback_func's return value becomes the	return value from auth_login
       (which should be	0, by convention).  callback_func will not be invoked
       if an error occurs, which is reported by	a non-zero return value	from
       auth_login. 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.

       The second argument to callback_func will be callback_arg, which	is not
       interpreted by this function in any way.	The first argument will	be a
       pointer to the following	structure:

       Example 1. struct authinfo

	   struct authinfo {
		const char *sysusername;
		const uid_t *sysuserid;
		gid_t sysgroupid;
		const char *homedir;

		const char *address;
		const char *fullname;
		const char *maildir;
		const char *quota;
		const char *passwd;
		const char *clearpasswd;

		const char *options;

		} ;

       Description of the above	fields:

       address
	   The authenticated login ID.

       sysusername
	   The authenticated account's userid and groupid can be looked	up in
	   the password	file using address. If this field is NULL, obtain the
	   userid and the groupid from sysuserid and sysgroupid.

       sysuserid
	   sysuserid may be NULL if sysusername	is initialized,	otherwise it's
	   a pointer to	the account's numeric userid.

       sysgroupid
	   Account's numeric groupid.  sysgroupid is only used when
	   sysusername is NULL.

       fullname
	   This	is the account's full name. This field is optional, it may be
	   NULL.

       homedir
	   The account's home directory. This field cannot be NULL.

       maildir
	   The pathname	to the account's mailbox. This field is	optional, it
	   can be NULL in which	case the default location is assumed.

       quota
	   Optional maildir quota on the account's mailbox (and	NULL if	no
	   quota is set).

       passwd
	   The account's encrypted password, if	available. If the account has
	   a cleartext password	defined, this field can	be set to NULL.	The
	   encrypted password can take several formats:

	   o   A traditional triple-DES	crypted	password, or a MD5+salt-hashed
	       password, as used in Linux.

	   o   "{MD5}" followed	by a base64-encoded MD5	hash of	the password.

	   o   "{SHA}" followed	by a base64-encoded SHA1 hash of the password.

       clearpasswd
	   The account's cleartext password, if	available. If the account has
	   an encrypted	password defined, this field can be set	to NULL.

       options
	   A comma-separated list of miscellaneous account options. See	below
	   for more information.

   Account options
       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 NULL value.	Otherwise it will be a
       comma-separated list of "option=value" settings.

	   Note
	   The application is responsible for actually implementing the
	   options. For	example, sn authentication request for service "imap",
	   for example,	will succeed provided that the userid and the password
	   are valid, even if "disableimap=1" is set. The application's
	   callback_func should	check for this condition, and return a
	   negative return code.

	   Note
	   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.

       The following options are recognized by the various Courier packages:

       disableimap=n
	   If "n" is 1,	IMAP access to this account should be disabled.

       disablepop3=n
	   If "n" is 1,	POP3 access to this account should be disabled.

       disableinsecureimap=n
	   If "n" is 1,	unencrypted IMAP access	to this	account	should be
	   disabled.

       disableinsecurepop3=n
	   If "n" is 1,	unencrypted POP3 access	to this	account	should be
	   disabled.

       disablewebmail=n
	   If "n" is 1,	webmail	access to this account should be disabled.

       disableshared=n
	   If "n" is 1,	this account should not	have access to shared folders
	   or be able to share its own folders with other people.

       group=name
	   This	option is used by Courier-IMAP in calculating access control
	   lists. This option places the account as a member of	access group
	   name. Instead of granting access rights on individual mail folders
	   to individual accounts, the access rights can be granted to an
	   access group	"name",	and all	members	of this	group get the
	   specified access rights.

	   The access group name "administrators" is a reserved	group. All
	   accounts in the administrators group	automatically receive all
	   rights to all accessible folders.

	       Note
	       This option may be specified multiple times to specify that the
	       account belongs to multiple account groups.

       sharedgroup=name
	   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's on top of	whatever else the access control lists
	   say). See the virtual shared	folder documentation for more
	   information.

	   For technical reasons, group	names may not include comma, tab, "/"
	   or "|" characters.

SEE ALSO
       authlib(3)[1], auth_generic(3)[2], auth_getuserinfo(3)[3],
       auth_enumerate(3)[4], auth_passwd(3)[5],	auth_getoption(3)[6].

NOTES
	1. authlib(3)
	   http://www.courier-mta.org/authlib/authlib.html

	2. auth_generic(3)
	   http://www.courier-mta.org/authlib/auth_generic.html

	3. auth_getuserinfo(3)
	   http://www.courier-mta.org/authlib/auth_getuserinfo.html

	4. auth_enumerate(3)
	   http://www.courier-mta.org/authlib/auth_enumerate.html

	5. auth_passwd(3)
	   http://www.courier-mta.org/authlib/auth_passwd.html

	6. auth_getoption(3)
	   http://www.courier-mta.org/authlib/auth_getoption.html

Double Precision, Inc.		  06/20/2015			 AUTH_LOGIN(3)

NAME | SYNOPSIS | DESCRIPTION | RETURNS | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=auth_login&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help