NAME

       checkpassword - check a password

SYNOPSIS

       checkpassword prog

DESCRIPTION

       checkpassword reads descriptor 3 through end of file and then closes descriptor 3.  There must be at most
       512 bytes of data before end of file.

       The information supplied on descriptor 3 is a login name terminated by \0, a password terminated by \0, a
       timestamp  terminated  by \0, and possibly more data.  There are no other restrictions on the form of the
       login name, password, and timestamp.

       If the password is unacceptable, checkpassword exits 1.  If checkpassword is misused, it may instead exit
       2.  If there is a temporary problem checking the password, checkpassword exits 111.

       If the password is acceptable, checkpassword runs prog.  prog consists of one or more arguments.

COMPATIBLE TOOLS

       There  are  other  tools  that  offer  the  same  interface  as  checkpassword.   Applications  that  use
       checkpassword are encouraged to take the checkpassword name as an argument, so that they can be used with
       different tools.

       Note  that  these  tools do not follow the getopt(3) interface.  Optional features are controlled through
       (1) the tool name and (2) environment variables.

THE PASSWORD DATABASE

       checkpassword checks the login name and  password  against  /etc/passwd,  using  the  operating  system's
       getpwnam(3)  and crypt(3) functions, supplemented by getspnam.  It rejects accounts with empty passwords.
       It ignores the timestamp.

       Other checkpassword-compatible tools have  different  interpretations  of  login  names,  passwords,  and
       timestamps.  Both the login name and the password should be treated as secrets by the application calling
       checkpassword;  the only distinction is for administrative convenience.  The timestamp should include any
       other information that the password is based on; for  example,  the  challenge  in  a  challenge-response
       system such as APOP.

       WARNING:  getpwnam  is  inherently  unreliable.   It  fails  to  distinguish between temporary errors and
       nonexistent users.  Future versions of getpwnam(3) should return ETXTBSY to indicate temporary errors and
       ESRCH to indicate nonexistent users.

PROCESS-STATE CHANGES

       Before invoking prog, checkpassword sets up $USER, $HOME, $SHELL, its supplementary groups, its gid,  its
       uid, and its working directory.

       Other  checkpassword-compatible tools may make different changes to the process state.  It is crucial for
       these effects to be documented; different applications have different requirements.

SEE ALSO

       getpwnam(3), crypt(3)

                                                                                                checkpassword(8)