<html> <body> <a href="../djb.html">D. J. Bernstein</a> <br><a href="../mail.html">Internet mail</a> <br><a href="../checkpwd.html">checkpassword</a> <h1>The checkpassword interface</h1> <pre> checkpassword <i>prog</i> </pre> <tt>checkpassword</tt> 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. <p> 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. <p> If the password is unacceptable, <tt>checkpassword</tt> exits 1. If <tt>checkpassword</tt> is misused, it may instead exit 2. If there is a temporary problem checking the password, <tt>checkpassword</tt> exits 111. <p> If the password is acceptable, <tt>checkpassword</tt> runs <tt><i>prog</i></tt>. <tt><i>prog</i></tt> consists of one or more arguments. <h2>Compatible tools</h2> There are other tools that offer the same interface as <tt>checkpassword</tt>. Applications that use <tt>checkpassword</tt> are encouraged to take the <tt>checkpassword</tt> name as an argument, so that they can be used with different tools. <p> Note that these tools do not follow the <tt>getopt</tt> interface. Optional features are controlled through (1) the tool name and (2) environment variables. <h2>The password database</h2> <tt>checkpassword</tt> checks the login name and password against <tt>/etc/passwd</tt>, using the operating system's <tt>getpwnam</tt> and <tt>crypt</tt> functions, supplemented by <tt>getuserpw</tt> and <tt>getspnam</tt> if necessary. It rejects accounts with empty passwords. It ignores the timestamp. <p> Other <tt>checkpassword</tt>-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 <tt>checkpassword</tt>; 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. <p> <b>WARNING:</b> <tt>getpwnam</tt> is inherently unreliable. It fails to distinguish between temporary errors and nonexistent users. Future versions of <tt>getpwnam</tt> should return ETXTBSY to indicate temporary errors and ESRCH to indicate nonexistent users. <h2>Process-state changes</h2> Before invoking <tt><i>prog</i></tt>, <tt>checkpassword</tt> sets up <tt>$USER</tt>, <tt>$HOME</tt>, <tt>$SHELL</tt>, its supplementary groups, its gid, its uid, and its working directory. <p> Other <tt>checkpassword</tt>-compatible tools may make different changes to the process state. It is crucial for these effects to be documented; different applications have different requirements. </body> </html>