chkusr/README.md

# checkpw

checkpw is a program that checks the validity of a users password on a UNIX/PAM-based system.

Currently only tested on Linux, but it should work on the [AIX](https://en.wikipedia.org/wiki/IBM_AIX), [DragonFly BSD](https://www.dragonflybsd.org/), [FreeBSD](https://www.freebsd.org/), [HP-UX](https://en.wikipedia.org/wiki/HP-UX), [Linux](https://kernel.org/), [macOS](https://en.wikipedia.org/wiki/MacOS), [NetBSD](https://netbsd.org/) and [Solaris](https://en.wikipedia.org/wiki/Oracle_Solaris) operating system too.

## The idea

I needed a program to verify passwords of users on Linux/UNIX systems using PAM that just return 0 on success and 1 on error.

## Building checkpw

```
git clone https://git.xw3.org/xw3/checkpw.git
cd checkpw
make
```

The code only supports verifying passwords for user id 1000 by default. Look at the file checkpw.h for some compile time options!

### Custom build example

Set MAX_UID and MIN_UID at compile time:

```
gcc -Wall -DMAX_UID=1000 -DMIN_UID=1000 -o checkpw checkpw.c -lpam -lpam_misc
```

## Installation

**WARNING:** Install this software with care. checkpw could easily be used for bruteforcing passwords from local users!

```
sudo make install
```

checkpw is installed to /usr/bin/.

checkpw.h is installed to /usr/include/ for use in other applications.

## Uninstall

```
sudo make uninstall
```

## Usage

```
checkpw -h
Usage: checkpw [-u <username>] [-p <password>] [-v] [-V] [-h]

Options:
  -u <username>  Specify username.
  -p <password>  Specify password.
  -v             Enable verbose mode.
  -V             Print program version.
  -h             Show this help.
```

You can also use checkpw even without installing by just running the following command:

```
./checkpk
```

checkpw returns 0 on success, 1 otherwise.

### Examples


#### Interactive mode asking for a username and a password

```
checkpw
```

#### Interactive mode only asking for a password

```
checkpw -u hanez
```

#### None interactive mode with username and password provided as arguments to checkpw

```
checkpw -u hanez -p password
```

#### Request the result from the above commands

```
echo $?
```

## License

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

## Links

 - [Homepage of checkpw](https://git.xw3.org/xw3/checkpw)
 - [https://cr.yp.to/checkpwd.html](https://cr.yp.to/checkpwd.html)
 - [https://pamtester.sourceforge.net/](https://pamtester.sourceforge.net/)