pam-duress: Installing Alternate PAM Passwords and Response Scripts

pam-duress addresses coerced PAM password disclosure

pam-duress addresses a narrow problem: a PAM user must provide a password under coercion without revealing the normal account password. The module lets administrators define an alternate duress password and associate it with shell scripts. When PAM receives the matching alternate password, it runs those scripts and can continue authentication as though the user had entered a valid credential.

The intended users are Linux system administrators, security engineers, and workstation owners responsible for PAM authentication and incident response. The README lists possible script actions, including deleting sensitive data, closing network connections, notifying IT or security staff, and sending information such as location, nearby Wi-Fi hotspots, camera images, or microphone streams. pam-duress does not implement those actions itself. It supplies the alternate-password check and script execution mechanism.

Global scripts live under `/etc/duress.d` and run as root. Per-user scripts live under `~/.duress` and run as the user attempting to authenticate. This split gives an administrator access to system-wide response actions while preserving a separate directory for actions that should run with the user's privileges.

The apparent benefit is continuity. According to the README, a matching duress password returns `PAM_SUCCESS`, allowing the PAM stack to proceed to an authenticated shell. The project does not document a central incident dashboard, automatic response policy, evidence vault, duplicate-action suppression, or recovery workflow. Those parts remain the deploying organization's responsibility.

pam-duress derives passwords from signed script files

The build produces a shared PAM module, `pam_duress.so`, and two utilities named `duress_sign` and `pam_test`. Each duress script has a companion `.sha256` file. The README states that `duress_sign` creates a password hash and an integrity hash for the script.

During authentication, `pam_duress.so` enumerates files in the applicable global and user directories. It looks for companion files with the `.sha256` extension, derives a hash from the submitted password and the script's SHA-256 hash, and compares the result with the stored value. If it finds a match, it executes the associated script. It repeats this process for eligible files and returns `PAM_SUCCESS` if any script ran. With no match, it returns `PAM_IGNORE`.

Global scripts use this mechanism and run as root:

export PAMUSER=[USERNAME]; /bin/sh [FILE]

User scripts run through `su` as the authenticating user:

export PAMUSER=[USERNAME]; su - [USERNAME] -c "/bin/sh [FILE]"

The `PAMUSER` variable exposes the account name to the script. If multiple scripts match, global scripts run first and the user's scripts follow. A personal script signed with the same password as a global script is reusable by that person only, according to the README.

This design makes the script file part of the credential relationship. Editing a signed script changes the file whose SHA-256 hash participates in password verification. The README does not document an integrated resign or rotation command, so changes require a controlled signing procedure. It also specifies accepted script permission masks of `500`, `540`, or `550`, with the accompanying example setting the `.sha256` file to `400`.

Building pam-duress from source on Ubuntu and Debian

The README lists the Ubuntu and Debian build dependencies:

sudo apt-get install build-essential libpam0g-dev libssl-dev

The default build and installation commands are:

make
sudo make install
make clean

The Makefile builds `bin/duress_sign`, `bin/pam_test`, and `bin/pam_duress.so`. On Linux, it links against PAM, OpenSSL, and C libraries, then installs the shared module in `/lib/security`. The two executables are copied to `/usr/local/bin`.

The maintainers state that development is primarily focused on Debian-flavored Linux. The repository also provides installation guides for Arch Linux and the Red Hat family. The Makefile includes a Darwin branch with Homebrew OpenSSL paths, the macOS Command Line Tools SDK, and `/usr/local/lib/pam`, but the README's dependency and configuration instructions remain Linux-oriented. A macOS build target should not be confused with a fully documented macOS deployment procedure.

The project has no GitHub releases. Installation therefore starts from the repository's `main` branch rather than a published release artifact. Before distributing a compiled module, an administrator needs to account for the host architecture, PAM location, OpenSSL libraries, and the LGPL-3.0 obligations associated with redistribution.

Creating a first pam-duress user script

Create local and global directories after installing the module:

mkdir -p ~/.duress
sudo mkdir -p /etc/duress.d

For a harmless functional check, the README creates a script that writes a marker file:

mkdir -p ~/.duress
echo '#!/bin/sh
echo "Hello World" > /tmp/test.txt' > ~/.duress/hello.sh

Sign the script with a password that is not the user's normal login password:

duress_sign ~/.duress/hello.sh

The utility prompts for the password twice. Set the script and signature file to the permissions used in the README:

chmod 500 ~/.duress/hello.sh
chmod 400 ~/.duress/hello.sh.sha256

The module must be ordered so PAM checks the normal password before the duress password, then reaches a final denial only when neither mechanism succeeds. The README shows this configuration for `/etc/pam.d/common-auth`:

auth    [success=2 default=ignore]      pam_unix.so
auth    [success=1 default=ignore]      pam_duress.so

auth    requisite                       pam_deny.so

Test the PAM stack with the supplied utility:

sudo pam_test $USER

Entering the duress password should authenticate and create `/tmp/test.txt` with `Hello World`. Entering the normal password should also authenticate through `pam_unix.so`, but it should not execute `hello.sh`.

This check confirms local execution and stack ordering. It does not establish that global scripts run correctly, modified scripts are rejected, several matching scripts execute in the intended order, or production response commands are safe.

Debug output changes what a duress login reveals

The Makefile provides a separate `debug` target that defines `DEBUG`. The documented debug build does not redirect script output to `/dev/null` by default, whereas a normal build does. This difference can expose script messages through the authentication environment when the module is configured for diagnosis.

The README documents this build sequence:

sudo make uninstall
make clean
make debug
sudo make install

Debug output can help an administrator locate a failing path or distinguish an authentication problem from a shell-script problem. It can also disclose information that a production duress action would normally suppress. The README does not define a dedicated production logging destination or explain whether script output and exit status enter a central audit system.

The debug build should therefore remain a diagnostic configuration. Its success output is not a substitute for validating a production response script. The repository's `CHANGELOG.md` may record version-specific changes, but the README does not establish a compatibility guarantee between branches or releases.

pam-duress execution privileges create hard-to-bound risk

pam-duress executes arbitrary shell scripts. That is useful because an administrator can implement actions specific to an incident, but it also makes script review the main adoption constraint. A global script runs as root, while a user script runs as the account logging in. Neither execution model is a sandbox described by the README.

The README does not document command allowlists, timeouts, transaction boundaries, duplicate-execution protection, recovery after partial failure, symlink handling, ownership validation, or a rollback process. It also presents removing the pam-duress module as a possible script action. That could hide the mechanism, but it would also change future authentication behavior and complicate recovery.

The module only applies where a service uses the configured PAM stack. The README does not claim support for application credentials, SSH keys, browser passwords, or services that bypass PAM. It also does not guarantee that every PAM consumer behaves like the documented shell login after `PAM_SUCCESS`.

A PAM configuration without a duress hook is a reasonable alternative for systems that cannot safely maintain arbitrary scripts. Application-level duress actions offer another approach because the application, not PAM, decides what to do when it detects a coercion signal. That approach can limit the scope to one application, but each protected application must implement its own trigger and response. pam-duress instead offers a shared authentication-layer trigger, at the cost of system-wide integration and privileged script execution.

The repository is not archived, and its last push was on 2026-07-16. That date indicates recent repository activity, not a published release schedule or a documented support commitment.

LGPL-3.0 and source maintenance for pam-duress

pam-duress is licensed under `LGPL-3.0`. Organizations distributing the module should review the license requirements for the shared object, related source, modifications, and distribution method. Different distributions may package and patch the software differently, so packaging policy must be checked separately from this repository. This is a compliance consideration rather than legal advice.

The repository contains `CHANGELOG.md`, contribution guidance in `docs/Contributing.md`, source under `src/`, and platform-specific documentation. No GitHub releases are published. An upgrade therefore means rebuilding from the selected repository state and checking compatibility with the existing PAM configuration, scripts, signatures, OpenSSL libraries, and host operating system.

The README does not document automated migrations or rollback. It also does not explain whether signatures created by one build remain compatible with another. A deployment should therefore retain the source revision used for an installed build, avoid editing production scripts in place, and test the replacement module in the same PAM stack before replacing an existing installation.

Editorial conclusion

Adopt pam-duress for PAM-managed Linux accounts when the organization can maintain signed scripts, strict permissions, and tested response actions. Do not adopt it for non-PAM services or use it as an undocumented emergency control. Before deployment, verify script ownership and permissions, global versus user execution, PAM stack ordering, script behavior after an edit, and the host's LGPL-3.0 compliance requirements.

Frequently asked questions

Official sources

1. Issues
2. License: LGPL-3.0
3. nuvious/pam-duress on GitHub
4. README