The checkpassword interface
Copyright 1996
D. J. Bernstein, djb@pobox.com


1. Introduction

This document describes the checkpassword interface, an executable
interface to UNIX password-checking tools.

Today, password-checking code is copied from one application to another.
Upgrading the system---encrypting passwords with MD5, keeping login
names secret, recording failed login attempts, supporting subaccounts,
handling one-time passwords, etc.---means changing all the applications.
Using an application in more than one way---for example, setting up
remote logins with /etc/passwd for ``inside'' connections, but setting
up a much more restricted system for ``outside'' connections---is
impossible.

In contrast, checkpassword-based applications are independent of the
details of password checking. To upgrade the system you can simply
upgrade one password-checking tool. Applications are also encouraged to
allow command-line tool selection, so that they can be used with more
than one tool at the same time.


2. Using checkpassword

A checkpassword-compatible tool is an executable program. It accepts a
command line in the following format:

   [tool] [subprogram]

Here [tool] is the name of the tool and [subprogram] is a
user-specified program to run if the password is acceptable. Note that
[tool] does not take any options and does not obey the getopt standard;
all optional features should be set with environment variables.

Programs that use the checkpassword interface are encouraged to take
[tool] as an argument.

When [tool] starts, it reads descriptor 3 through EOF and then closes
descriptor 3. There must be at most 512 bytes of data before EOF.

The data supplied on descriptor 3 is a login name terminated by a 0
byte, a password terminated by a 0 byte, a timestamp terminated by a 0
byte, and possibly more data. There are no other restrictions on the
form of the login name, password, and timestamp. Both the login name and
the password should be treated as secrets by [tool]'s caller; the only
distinction is for administrative convenience. The timestamp should
include any information that the password is based on: for example, the
challenge in a challenge-response system such as APOP.

If the password is invalid, [tool] will exit 1. If [tool] is misused, it
may instead exit 2. If there is a temporary problem checking the
password, [tool] will exit 111.

If the password is acceptable, [tool] will use execvp() to run
[subprogram] with any supplied arguments. It may first change the
process state in various ways: for example, adding a HOME environment
variable and chdir()ing there, or adding a USER environment variable and
setuid()ing to that user. These effects should be documented;
applications will differ in their requirements.
