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.