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

FreeBSD Manual Pages


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

       auth_generic_meta, auth_generic - Generic authentication	request

       #include	<courierauth.h>

       int rc=auth_generic_meta(struct auth_meta *meta,	const char *service,
				const char *authtype, const char *authdata,
				int (*callback_func) (struct authinfo *, void *),
				void *callback_arg);

       int rc=auth_generic(const char *service,	const char *authtype,
			   const char *authdata,
			   int (*callback_func)	(struct	authinfo *, void *),
			   void	*callback_arg);

       auth_generic_meta processes a generic authentication request. You do
       not want	to use this function by	itself.	You really want	to use
       auth_login_meta(3)[1].  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

       authtype	specifies the format of	the authentication request. Three
       authentication formats are defined in courierauth.h:

	   authdata contains the following string: "userid\npassword\n". That
	   is, the userid being	authenticated, an ASCII	newline	character, the
	   password, and a second newline character.

	   This	format is used with CRAM-MD5 or	CRAM-SHA1.  authdata contains
	   the following string: "challenge\nresponse\n".  challenge is	the
	   base64-encoded challenge, which is followed by an ASCII newline
	   character.  response	is a base64-encoded string that's 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.

       A NULL meta is equivalent to using the default auth_meta	returned by

       auth_generic_meta() should not be used by itself, but only together
       with auth_sasl_ex(3)[3].

       auth_generic() is deprecated and	should not be used in new code.

       callback_func will be invoked if	auth_generic_meta succeeds, and
       callback_func's return value becomes the	return value from
       auth_generic_meta (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_generic_meta. 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:

	   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:

	   The authenticated login ID.

	   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 may be NULL if sysusername	is initialized,	otherwise it's
	   a pointer to	the account's numeric userid.

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

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

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

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

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

	   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.

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

	   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.

	   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.

	   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:

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

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

	   If "n" is 1,	unencrypted IMAP access	to this	account	should be

	   If "n" is 1,	unencrypted POP3 access	to this	account	should be

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

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

	   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.

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

	   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

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

       authlib(3)[4], auth_meta(3)[2], auth_login_meta(3)[1],
       auth_getuserinfo_meta(3)[5], auth_enumerate(3)[6], auth_passwd(3)[7],

	1. auth_login_meta(3)

	2. auth_meta_init_default(3)

	3. auth_sasl_ex(3)

	4. authlib(3)

	5. auth_getuserinfo_meta(3)

	6. auth_enumerate(3)

	7. auth_passwd(3)

	8. auth_getoption(3)

Double Precision, Inc.		  05/27/2020		  AUTH_GENERIC_META(3)


Want to link to this manual page? Use this URL:

home | help