/usr/share/doc/checkpw/interface.html is in checkpw 1.02-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | <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>
|