usercontainer/README.md

PAM C++ + Rust Backend Monorepo

This project provides a Linux PAM module written in C++ (GNU g++, C++17) that delegates authentication and logging to a Rust static library backend. The build is orchestrated by CMake, which triggers Cargo for the Rust backend.

Structure

• pam-module/: C++ PAM module source
• rust-backend/: Rust static library backend
• tests/: Integration tests

Build Requirements

• GNU g++ (C++17)
• CMake >= 3.15
• Rust (cargo)
• PAM development headers

Build Instructions

mkdir build && cd build
cmake ..
cmake --build .

Install

Copy the built PAM module to /lib/security/ or /lib64/security/ as needed.

Logging

Rust backend logs to /var/log/pam_rust_backend.log by default.

Safety

• Rust panics are contained and never cross FFI.
• C++ exceptions are caught before returning to PAM.

Extending

Add new subprojects as needed for future business logic or integrations.

Test Application (PAM Client)

This repository includes a test PAM client at tests/pam_test_app.cpp.

Build the test

mkdir -p build && cd build
cmake ..
cmake --build .

The executable will be generated at build/tests/pam_test_app.

Copy the PAM module

After building, copy the PAM module to the system PAM module path:

sudo cp build/pam-module/pam_module.so /lib/security/

On some distributions, use /lib64/security/ instead.

Configure /etc/pam.d service

Create /etc/pam.d/pam_test_app with:

auth required pam_module.so
account required pam_permit.so

You can also pass module arguments which are exposed as argc and argv to pam_sm_authenticate, for example:

auth required pam_module.so debug log_path=/var/log/pam_rust_backend.log
account required pam_permit.so

Run the test client

./tests/pam_test_app pam_test_app <user> <password>

The first argument (pam_test_app) must match the service filename in /etc/pam.d/pam_test_app.