checkpassword(8)                                 checkpassword(8)

NAME
       checkpassword - check a password

SYNOPSIS
       checkpassword subprogram [ args ...  ]

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,  pass-
       word, 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, check-
       password exits 111.

       If the password is acceptable, checkpassword  uses  execvp
       to run subprogram with the given arguments.

CHECKPASSWORD-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 checkpassword-com-
       patible tools.

       Note  that these tools do not follow the getopt 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  and
       crypt  functions.   It  rejects  accounts with empty pass-
       words.  It ignores the timestamp.

       Other checkpassword-compatible tools have different inter-
       pretations  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 times-
       tamp  should  include any other information that the pass-
       word is based on; for example, the challenge  in  a  chal-
       lenge-response system such as APOP.

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

PROCESS-STATE CHANGES
       Before  invoking  subprogram, 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.  These effects must be docu-
       mented; applications will differ in their requirements.

VERSION
       This  documentation  describes checkpassword version 0.80.
       See http://pobox.com/~djb/checkpwd.html for updates.

SEE ALSO
       getpwnam(3), crypt(3)

                                                                1