# `libpam-sys`: low-level bindings to Pluggable Authentication Modules

This crate provides low-level access to PAM, working with multiple PAM implementations.
You do not need PAM system headers installed to use this!

If you're looking for a nice, safe, Rusty API to PAM, may I recommend [nonstick][nonstick]?

## Configuration

By default, this crate guesses your system's PAM implementation based upon your OS.

- Linux: `LinuxPam`
- BSDs, including Mac OS: `OpenPam`
- Illumos/Solaris: `Sun`
- Unknown: `XSso`

Each implementation exports all the functionality available in its respective PAM library.
`XSso` exports only what is in the [X/SSO specification][xsso].

## Cargo Features

The `helpers` feature (optional, but on by default) exports two helpers for PAM memory management.

- A struct for managing the difference in memory management between Linux-PAM and all other implementations.
- A struct for handling the Linux-PAM–specific binary data payload structure.

Neither are directly referenced elsewhere, and both allow you to bring your own storage abstractions.

## Testing

Tests are mostly run through `libpam-sys-test`, which lives in the crate's workspace in its repository (along with [nonstick]).

- [`ctest`][ctest] verifies the correctness of the FFI bindings (function/struct alignment, etc.).
- A kind of scuffed homebrew thing also verifies that the constants are correct.

Testing is mainly accomplished through the `libpam-sys-test` package in this crate's workspace.
There are some unit tests of glue code and other type checks.

## Minimum Rust version

This crate supports **Rust 1.75**, the current version in Debian Trixie and Ubuntu 24.04.2 LTS.
There shouldn't be much that needs changing, since PAM's API is quite stable.

## References

- [X/SSO PAM specification][xsso]: This 1997 document laid out the original specification for PAM.
- [Linux-PAM repository][linux-pam]: The Linux-PAM implementation, used by most (all?) Linux distributions. Contains many extensions.
  - [Linux-PAM man page][man7]: Root man page for Linux-PAM, with links to additional PAM man pages.
  - [Linux-PAM guides][linux-guides]: Documentation for developers using PAM and sysadmins.
- [OpenPAM repository][openpam]: The OpenPAM implementation, used by many BSD varieties. This hews very close to the spec.
  - [OpenPAM man page][manbsd]: NetBSD's root man page for OpenPAM.
- [Illumos PAM repository][illumos-pam]: Illumos's implementation of PAM, based on Sun's Solaris. Even more basic than OpenPAM.
  - [Illumos PAM man page][manillumos]: Illumos's root man page for its PAM implementation.

[ctest]: https://github.com/rust-lang/libc/tree/ctest-v0.4.11/ctest
[nonstick]: https://crates.io/crates/nonstick
[xsso]: https://pubs.opengroup.org/onlinepubs/8329799/toc.htm
[linux-pam]: https://github.com/linux-pam/linux-pam
[man7]: https://www.man7.org/linux/man-pages/man8/pam.8.html
[linux-guides]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/
[openpam]: https://git.des.dev/OpenPAM/OpenPAM
[manbsd]: https://man.netbsd.org/pam.8
[illumos-pam]: https://code.illumos.org/plugins/gitiles/illumos-gate/+/refs/heads/master/usr/src/lib/libpam/
[manillumos]: https://illumos.org/man/3PAM/pam