SYNOPSIS

       qmail-authuser subprogram [ args	...  ]



DESCRIPTION

       qmail-authuser  is  a versatile authentication PAM. In it's native use,
       it accesses a local database or the Unix	/etc/password  file  (or  it's
       shadow  companion).   In	 qmail-authuser's alternate use, it may	call a
       virtual domain auth handler.

       qmail-authuser follows checkpassword's interface	specification  provid-
       ing  LOGIN, PLAIN, and CRAM-MD5 authentication for SMTP as well as USER
       and APOP	for POP3 in addition with the required environment settings.

       The information supplied	on descriptor 3	is a authuser name  terminated
       by  \0,	a  password  or	response terminated by \0, and a challenge for
       CRAM-MD5	authentication terminated by \0.  There	must be	 at  most  512
       bytes of	data before end	of file.



FILES

       /var/qmail/users/authuser  contains  pairs  of  authuser	 and  password
       tokens separated	by a colon (":").  Both	tokens may include white  spa-
       ces (if supported by the	OS) and	may use	special	characters for certain
       actions.	The provided password token should have	a  significant	length
       (> 2 characters).

       Lines  starting	with  the  '#' sign are	regarded as comment.  Trailing
       empty spaces in lines are removed prior of evaluation.

       The file	/var/qmail/users/authuser shall	be root	owned  and  belong  to
       group sqmail.



AUTHUSER

       The authuser token is the public	part of	the identity and may include a
       composit	information, typically the userid and the domain respectively,
       described  as  userid@domain.   qmail-authuser  may consider both parts
       independently.  Domain specific authentication can be triggered includ-
       ing the information @domain as authuser token. However, as an abbrevia-
       tion, this may be provided simply as @, telling qmail-authuser to  con-
       sider  all  unspecified	authusers solely and transparently as 'virtual
       users'.	On the other hand, the authuser	token may be wildcarded	as  *.
       Now,  qmail-authuser  is	 instructed to query the local Unix system for
       authentication.

       More specific authuser tokens have precedence over less specific, irre-
       spectively  of  their  order.  Particular users and domains can be dis-
       abled from authentication prepending the	name with  a  '!',  which  has
       precedence over acceptance: !authuser.

       qmail-authuser  support  thus  (1)  local  email users, (2) Unix system
       users, and (3) virtual domain users alltogether.

NATIVE USE

       qmail-authuser recalculates the MD5 digest  using  the  provided  plain
       challenge and the passwords from /var/qmail/users/authuser and compares
       it with response (2nd parameter). If they are the same,  qmail-authuser
       uses  pathexec  to  run subprogram with the given arguments and perhaps
       setting up the user environment.  The use of subprogram is required and
       can  be expressed as /bin/true or /usr/bin/true for compliance reasons.

       If no challenge is provided, qmail-authuser compares the supplied pass-
       word  with  the  stored  password  token  in /var/qmail/users/authuser.
       Thus, qmail-authuser can be used as a generic checkpassword program for
       PLAIN & LOGIN auth methods.

       qmail-authuser  may  also been used as a replacement for the checkpass-
       word PAM, allowing to evaluate the /etc/passwd and shadow files for the
       auth  methods USER, PLAIN & LOGIN.  In this case, qmail-authuser has to
       be 'sticky' and running as root.  Depending on  the  provided  password
       token, the Unix environment will be evaluated and setup.

ALTERNATE USE

       qmail-authuser	includes  the  call  of	 both  vpopmail's  vchkpw  and
       vmailmgr's checkvpw (which need to be in	the path)  and	transfers  the
       received	authentication information transparently to those.



QUERY AND STORAGE METHODS

       The  first  character  X	 of the	password token is used to indicate the
       password's query	and storage method.  The following cases may  be  con-
       sidered:

	 (1a) authuser:clearpwd
	 (1b) authuser:%pwdhash
	 (2a) authuser:?
	 (2b) authuser:!
	 (2c) *:?
	 (2d) *:!
	 (3a) authuser:+
	 (3b) @domain:+
	 (3c) @:+
	 (4a) authuser:&
	 (4b) @domain:&
	 (4c) @:&

       (1)  Local  query/storage:  Here,  together with	the authuser plaintext
       (1a)   or   hashed   passwords	(1b)   may   be	  provided   in	   the
       /var/qmail/users/authuser control file.	In case	of %pwdhash, the pass-
       word is stored as MD5 hash following the	'%'.  If the  plaintext	 pass-
       word  is	 given	as password this means,	that the following password is
       taken literally and may include a leading '%',

       (2) Unix	system query/storage: In case the password token  consists  of
       ?,  the	received authentication	information is used to trigger a stan-
       dard Unix login user query taking the userid information	as system user
       account.	 Therefore, no particular password token is required here.  If
       instead !  is used, additionally, the Unix  user	 environment  will  be
       evaluated  and  setup  according	 to  the checkpassword implementation,
       allowing	qmail-authuser to be used for qmail-popup and qmail-pop3d ser-
       vices.	The  inclusion	of  any	 specific  authuser information	can be
       avoided in case * is used as shortcut within  /var/qmail/users/authuser
       followed	by either ?  or	!  as password token. Now, the received	userid
       and password is fed automatically to the	Unix  system  for  authentica-
       tion.

       (3,4)  Virtual  domain query/storage: Alternatively, qmail-authuser may
       call either checkvpw once a + or vchkpw in case & is given as  password
       token.

       All  authentication  storage  and  query  mechanism can be used concur-
       rently, depending on the settings of the authuser and password token in
       /var/qmail/users/authuser.




EXIT CODES

       In  case  the  provided  authuser  or userid does not exist, or the MD5
       digest and the response, or the passwords differ, qmail-authuser  exits
       1.  If qmail-authuser is	misused, it may	instead	exit 2.	 If there is a
       temporary problem checking the password,	qmail-authuser exits 111.



SECURITY

       qmail-authuser is invoked in the	environment of qmail-smtpd  or	qmail-
       popup   which   is   typically	run   as   user	  qmaild.   Therefore,
       /var/qmail/users/authuser shall be readable  only  by  this  user.  The
       included	 password token	shall solely be	used for SMTP/POP3 authentica-
       tion and	should possess enough entropy.

       A sticky	and root-owned qmail-authuser is a potential security risk.



PASSWORD HASHES

       Instead of plaintext passwords, additionally MD5	hashes	of  the	 pass-
       words  may  be  used. However, in spite of rainbow tables this requires
       none-trival passwords.	Currenty,  qmail-authuser  only	 supports  MD5
       hashed  passwords having	32 hex characters length.  Other methods, like
       SHA1 and	SHA256,	may be supported in the	future	but  don't  solve  the
       problem of rainbow tables to reverse the	hash.



AUTH METHODS

       In  case	hashed passwords or the	UNIX passwords are used, only the auth
       methods USER, PLAIN, and	LOGIN are working.   Those  methods  are  only
       secure  on  encrypted  connections  and otherwise are easy victim of an
       eavesdropper.  Challenge/Response methods - like	CRAM-MD5  and  APOP  -
       require	having	access	to the plain-text passwords. For vchkpw	C/R is
       possible	querying the local 'vpopmail' database.



SEE ALSO

       qmail-popup(8),	qmail-smtpd(8),	 checkpassword(8),  vchkpw(8),	check-
       vpw(8).



				       8	      s/qmail:(qmail-authuser)

Man(1) output converted with man2html