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.
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)