initial commit: WIP debugging PAM module

README.md

@@ -0,0 +1,82 @@
+# 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
+```bash
+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
+
+```bash
+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:
+
+```bash
+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:
+
+```conf
+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:
+
+```conf
+auth required pam_module.so debug log_path=/var/log/pam_rust_backend.log
+account required pam_permit.so
+```
+
+### Run the test client
+
+```bash
+./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`.