   D. J. Bernstein Internet mail checkpassword

                                                    The checkpassword
                                                    interface

      checkpassword prog

   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 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, supplemented
   by getuserpw and getspnam if necessary. 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 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.
