Mercurial > crates > nonstick

annotate libpam-sys/README.md @ 134:6c1e1bdb4164

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use standard #[cfg] directives rather than custom proc macros. Instead of having to do a bunch of custom parsing and other logic that tools often choke on, this change introduces an easy way to depend upon custom #[cfg]s provided by the libpam-sys crate.
author Paul Fisher <paul@pfish.zone>
date Thu, 03 Jul 2025 11:03:36 -0400
parents 5b2de52dd8b2
children efbc235f01d3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
1 # `libpam-sys`: low-level bindings to Pluggable Authentication Modules
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
2
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
3 This crate provides low-level access to PAM, working with multiple PAM implementations.
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
4 You do not need PAM system headers installed to use this!
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
5
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
6 If you're looking for a nice, safe, Rusty API to PAM, may I recommend [nonstick][nonstick]?
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
7
108
e97534be35e3 Make some proc macros for doing cfg-like stuff for PAM impls.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
8 ## Configuration
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
9
108
e97534be35e3 Make some proc macros for doing cfg-like stuff for PAM impls.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
10 By default, this crate guesses your system's PAM implementation based upon your OS.
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
11
108
e97534be35e3 Make some proc macros for doing cfg-like stuff for PAM impls.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
12 - Linux: `LinuxPam`
e97534be35e3 Make some proc macros for doing cfg-like stuff for PAM impls.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
13 - BSDs, including Mac OS: `OpenPam`
110
2346fd501b7a Add tests for constants and do other macro niceties.
Paul Fisher <paul@pfish.zone>
parents: 108
diff changeset
14 - Illumos/Solaris: `Sun`
118
39760dfc9b3b Detect PAM library based only on system lib; rename minimal lib to XSso.
Paul Fisher <paul@pfish.zone>
parents: 110
diff changeset
15 - Unknown: `XSso`
108
e97534be35e3 Make some proc macros for doing cfg-like stuff for PAM impls.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
16
e97534be35e3 Make some proc macros for doing cfg-like stuff for PAM impls.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
17 Each implementation exports all the functionality available in its respective PAM library.
125
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
18 `XSso` exports only what is in the [X/SSO specification][xsso].
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
19
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
20 ## Cargo Features
125
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
21
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
22 The `helpers` feature (optional, but on by default) exports two helpers for PAM memory management.
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
23
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
24 - A struct for managing the difference in memory management between Linux-PAM and all other implementations.
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
25 - A struct for handling the Linux-PAM–specific binary data payload structure.
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
26
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
27 Neither are directly referenced elsewhere, and both allow you to bring your own storage abstractions.
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
28
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
29 ## Testing
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
30
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
31 Tests are mostly run through `libpam-sys-test`, which lives in the crate's workspace in its repository (along with [nonstick]).
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
32
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
33 - [`ctest`][ctest] verifies the correctness of the FFI bindings (function/struct alignment, etc.).
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
34 - A kind of scuffed homebrew thing also verifies that the constants are correct.
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
35
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
36 Testing is mainly accomplished through the `libpam-sys-test` package in this crate's workspace.
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
37 There are some unit tests of glue code and other type checks.
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
38
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
39 ## Minimum Rust version
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
40
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
41 This crate supports **Rust 1.75**, the current version in Debian Trixie and Ubuntu 24.04.2 LTS.
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
42 There shouldn't be much that needs changing, since PAM's API is quite stable.
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
43
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
44 ## References
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
45
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
46 - [X/SSO PAM specification][xsso]: This 1997 document laid out the original specification for PAM.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
47 - [Linux-PAM repository][linux-pam]: The Linux-PAM implementation, used by most (all?) Linux distributions. Contains many extensions.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
48 - [Linux-PAM man page][man7]: Root man page for Linux-PAM, with links to additional PAM man pages.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
49 - [Linux-PAM guides][linux-guides]: Documentation for developers using PAM and sysadmins.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
50 - [OpenPAM repository][openpam]: The OpenPAM implementation, used by many BSD varieties. This hews very close to the spec.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
51 - [OpenPAM man page][manbsd]: NetBSD's root man page for OpenPAM.
110
2346fd501b7a Add tests for constants and do other macro niceties.
Paul Fisher <paul@pfish.zone>
parents: 108
diff changeset
52 - [Illumos PAM repository][illumos-pam]: Illumos's implementation of PAM, based on Sun's Solaris. Even more basic than OpenPAM.
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
53 - [Illumos PAM man page][manillumos]: Illumos's root man page for its PAM implementation.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
54
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
55 [ctest]: https://github.com/rust-lang/libc/tree/ctest-v0.4.11/ctest
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
56 [nonstick]: https://crates.io/crates/nonstick
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
57 [xsso]: https://pubs.opengroup.org/onlinepubs/8329799/toc.htm
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
58 [linux-pam]: https://github.com/linux-pam/linux-pam
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
59 [man7]: https://www.man7.org/linux/man-pages/man8/pam.8.html
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
60 [linux-guides]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
61 [openpam]: https://git.des.dev/OpenPAM/OpenPAM
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
62 [manbsd]: https://man.netbsd.org/pam.8
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
63 [illumos-pam]: https://code.illumos.org/plugins/gitiles/illumos-gate/+/refs/heads/master/usr/src/lib/libpam/
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
64 [manillumos]: https://illumos.org/man/3PAM/pam