Mercurial > crates > nonstick

comparison libpam-sys/README.md @ 129:5b2de52dd8b2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Cleanups: create readmes, add a few docs, remove cruft.
author Paul Fisher <paul@pfish.zone>
date Mon, 30 Jun 2025 23:49:54 -0400
parents 2b255c92417b
children
comparison
equal deleted inserted replaced
128:ad77f2af5ff4 129:5b2de52dd8b2
1 # libpam-sys 1 # `libpam-sys`: low-level bindings to Pluggable Authentication Modules
2 2
3 This crate provides low-level access to PAM. 3 This crate provides low-level access to PAM, working with multiple PAM implementations.
4 You do not need PAM system headers installed to use this!
5
6 If you're looking for a nice, safe, Rusty API to PAM, may I recommend [nonstick][nonstick]?
4 7
5 ## Configuration 8 ## Configuration
6 9
7 By default, this crate guesses your system's PAM implementation based upon your OS. 10 By default, this crate guesses your system's PAM implementation based upon your OS.
8 11
12 - Unknown: `XSso` 15 - Unknown: `XSso`
13 16
14 Each implementation exports all the functionality available in its respective PAM library. 17 Each implementation exports all the functionality available in its respective PAM library.
15 `XSso` exports only what is in the [X/SSO specification][xsso]. 18 `XSso` exports only what is in the [X/SSO specification][xsso].
16 19
17 ## Features 20 ## Cargo Features
18 21
19 The `helpers` feature (optional, but on by default) exports two helpers for PAM memory management. 22 The `helpers` feature (optional, but on by default) exports two helpers for PAM memory management.
20 23
21 - A struct for managing the difference in memory management between Linux-PAM and all other implementations. 24 - A struct for managing the difference in memory management between Linux-PAM and all other implementations.
22 - A struct for handling the Linux-PAM–specific binary data payload structure. 25 - A struct for handling the Linux-PAM–specific binary data payload structure.
23 26
24 Neither are directly referenced elsewhere, and both allow you to bring your own storage abstractions. 27 Neither are directly referenced elsewhere, and both allow you to bring your own storage abstractions.
28
29 ## Testing
30
31 Tests are mostly run through `libpam-sys-test`, which lives in the crate's workspace in its repository (along with [nonstick]).
32
33 - [`ctest`][ctest] verifies the correctness of the FFI bindings (function/struct alignment, etc.).
34 - A kind of scuffed homebrew thing also verifies that the constants are correct.
35
36 Testing is mainly accomplished through the `libpam-sys-test` package in this crate's workspace.
37 There are some unit tests of glue code and other type checks.
38
39 ## Minimum Rust version
40
41 This crate supports **Rust 1.75**, the current version in Debian Trixie and Ubuntu 24.04.2 LTS.
42 There shouldn't be much that needs changing, since PAM's API is quite stable.
25 43
26 ## References 44 ## References
27 45
28 - [X/SSO PAM specification][xsso]: This 1997 document laid out the original specification for PAM. 46 - [X/SSO PAM specification][xsso]: This 1997 document laid out the original specification for PAM.
29 - [Linux-PAM repository][linux-pam]: The Linux-PAM implementation, used by most (all?) Linux distributions. Contains many extensions. 47 - [Linux-PAM repository][linux-pam]: The Linux-PAM implementation, used by most (all?) Linux distributions. Contains many extensions.
32 - [OpenPAM repository][openpam]: The OpenPAM implementation, used by many BSD varieties. This hews very close to the spec. 50 - [OpenPAM repository][openpam]: The OpenPAM implementation, used by many BSD varieties. This hews very close to the spec.
33 - [OpenPAM man page][manbsd]: NetBSD's root man page for OpenPAM. 51 - [OpenPAM man page][manbsd]: NetBSD's root man page for OpenPAM.
34 - [Illumos PAM repository][illumos-pam]: Illumos's implementation of PAM, based on Sun's Solaris. Even more basic than OpenPAM. 52 - [Illumos PAM repository][illumos-pam]: Illumos's implementation of PAM, based on Sun's Solaris. Even more basic than OpenPAM.
35 - [Illumos PAM man page][manillumos]: Illumos's root man page for its PAM implementation. 53 - [Illumos PAM man page][manillumos]: Illumos's root man page for its PAM implementation.
36 54
55 [ctest]: https://github.com/rust-lang/libc/tree/ctest-v0.4.11/ctest
56 [nonstick]: https://crates.io/crates/nonstick
37 [xsso]: https://pubs.opengroup.org/onlinepubs/8329799/toc.htm 57 [xsso]: https://pubs.opengroup.org/onlinepubs/8329799/toc.htm
38 [linux-pam]: https://github.com/linux-pam/linux-pam 58 [linux-pam]: https://github.com/linux-pam/linux-pam
39 [man7]: https://www.man7.org/linux/man-pages/man8/pam.8.html 59 [man7]: https://www.man7.org/linux/man-pages/man8/pam.8.html
40 [linux-guides]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/ 60 [linux-guides]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/
41 [openpam]: https://git.des.dev/OpenPAM/OpenPAM 61 [openpam]: https://git.des.dev/OpenPAM/OpenPAM