PAM flagging module

This PAM module allows to create flag for a user who recently authenticated. The general purpose to flag recently authenticated users is to direct them to easier authentication methods(e.g. fingerprint) instead blindly granting, say sudo, for some time.

Use-cases

Smart sudo authentication

Require password for the first sudo command after login, then allow biometric authentication (e.g. fingerprint) for subsequent sudo commands within a time window. This provides security for initial access while maintaining convenience with increased security for frequent administrative tasks.

Stepped-down login

Allow users to unlock their screen or re-authenticate with a fingerprint after recently providing their full password. Perfect for users who frequently lock their workstation but need quick access throughout the workday.

Server room protection

Combine with physical authentication systems: require both physical badge scan AND password initially, then allow re-entry with just badge scan while the flag is valid.

Installation

From releases

1. Download the latest release from releases page along with SHA512SUMS and SHA512SUMS.sig files.
2. Use sha512sum and gpg to validate the release.
3. If checksums match, install to your PAM modules directory(depends on distro): sudo install -o root -g root -m 0644 pam_flag.so /usr/lib/security/pam_flag.so

Validation

Download my personal GPG key from GitHub or f104a.io. Then import it with gpg --import f104a_personal.asc and verify the release with gpg --verify SHA512SUMS.sig SHA512SUMS.

wget https://f104a.io/data/personal.asc
gpg --import personal.asc
gpg --verify SHA512SUM.sig SHA512SUM
sha512sum pam_flag.so
cat SHA512SUM # Verify that sha512sum from previous line matches the one in the file.

IN CASE IF ANY STEP FAILS DUE TO MISMATCH IN HASHSUM OR SIGNATURE, IT IS POSSIBLE THAT FILE IS TAMPERED. IN SUCH CASE REMOVE IT IMMEDIATELY.

From source

Clone the repository and follow the instructions below.

Building

To compile you would need cmake, make and libpam that is perhaps already installed and its headers which are usually called libpam-devel or something alike depending on your distribution. The compilation is straighforward with cmake:

cmake .
make

Installing module

To install the module you need to copy it to /usr/lib/security or /lib/security (depending on distro) directory. You can do it with install command:

sudo install -o root -g root -m 0644 pam_flag.so /usr/lib/security/pam_flag.so

After installing modify config to your choosing.

Don't forget to update your MAC(AppArmor, SELinux, etc) rules/policies to allow respective utilites/programs to read-write to /run/pam-flag/ directory.

Usage

mode

The module has two operating modes:

• set - sets flag, should be invoked when strong authentication succeeds
• require - requires flag to be set, fails if flag is not set The mode is passed as mode parameter.

timeout

A non-negative integer value in seconds. Descibes after which time the flag is invalidated. In other words, it is an actual flag time-to-live. If timeout is zero, it is ignored and flag is never invalidated.

Example

This example shows how you can direct authentication towards less secure but easier method if flag is present and towards secure method if flag is missing.

# --- Route based on flag ---
# If flag present: don't jump (we'll try fingerprint next).
# If flag missing: jump over fingerprint to secure auth.
auth    [success=ignore default=1] pam_flag.so mode=require timeout=600

# --- Less-secure path (only reached when flag is present) ---
# If fingerprint succeeds, we stop here and accept.
auth    sufficient                 pam_fprintd.so

# --- Secure path (always taken when flag is missing; fallback when fingerprint fails) ---
auth    requisite                  pam_unix.so try_first_pass nullok

# After a successful secure auth, set the flag (fingerprint-success won't reach this line).
auth    optional                   pam_flag.so mode=set timeout=600

# Account
account required                   pam_unix.so

# Session
session required                   pam_limits.so
session required                   pam_unix.so

How flags are stored?

Flags are empty files in /run/pam-flag/ directory. When mode=set is invoked the file is created or its last update timestamp is modified. When mode=require is invoked the files modifciation time is checked. If it was more then timeout seconds ago, the file is considered invalid and the module fails. If file does not exist, the module also fails. Each flag is identified by the user's numeric UID (file name equals the UID).