---
name: "checkpassword"
section: "8"
platform: "linux"
package: "fgetty"
version: "0.6-5"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/checkpassword"
---

# checkpassword(8)

check a password

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

## COMPATIBLE TOOLS

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)](/getopt/3.md) 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)](/getpwnam/3.md) and [**crypt**(3)](/crypt/3.md) 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)](/getpwnam/3.md) 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)](/getpwnam/3.md), [crypt(3)](/crypt/3.md)