Mercurial > crates > nonstick

annotate libpam-sys/README.md @ 171:e27c5c667a5a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Create full new types for return code and flags, separate end to end. This plumbs the ReturnCode and RawFlags types through the places where we call into or are called from PAM. Also adds Sun documentation to the project.
author Paul Fisher <paul@pfish.zone>
date Fri, 25 Jul 2025 20:52:14 -0400
parents 180237d0b498
children 0730f5f2ee2a
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
162
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
3 - Supports all known PAM implementations on Linux, Mac OS, BSD, and Illumos/Solaris
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
4 - Works with zero configuration for common use cases
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
5 - No need for system header files
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
6 - Depends only on `libc`
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
7
160
09dff285ff5e Switch default PAM detection strategy to target-based.
Paul Fisher <paul@pfish.zone>
parents: 158
diff changeset
8 If you're looking for a nice, safe, Rusty API to PAM, may I recommend [nonstick]?
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
9
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 129
diff changeset
10 ## PAM implementations
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
11
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 129
diff changeset
12 Supported PAM implementations are defined in the `pam_impl::PamImpl` enum.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 129
diff changeset
13
160
09dff285ff5e Switch default PAM detection strategy to target-based.
Paul Fisher <paul@pfish.zone>
parents: 158
diff changeset
14 This crate automatically chooses the appropriate PAM implementation you are most likely to need installed based on the target OS.
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 129
diff changeset
15 You can also explicitly specify the PAM implementation you want (if not detected correctly) by setting the `LIBPAMSYS_IMPL` environment variable **at build time**.
148
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents: 136
diff changeset
16 All build-time configuration is performed by the build script of the [`libpam-sys-consts` crate](https://crates.io/crates/libpam-sys-consts).
108
e97534be35e3 Make some proc macros for doing cfg-like stuff for PAM impls.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
17
160
09dff285ff5e Switch default PAM detection strategy to target-based.
Paul Fisher <paul@pfish.zone>
parents: 158
diff changeset
18 Normally, this crate exports all functionality available in the selected PAM library.
158
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
19 `XSso` exports only the subset of the [X/SSO specification][xsso] supported by both OpenPAM and Sun PAM.
125
2b255c92417b Introduce base PAM functions; use the real X/SSO PAM header for tests.
Paul Fisher <paul@pfish.zone>
parents: 118
diff changeset
20
161
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
21 ### Changing behavior based on PAM implementation
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
22
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
23 Downstream crates can detect the current PAM implementation using custom `#[cfg]`s:
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
24
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
25 ```rust
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
26 // Your package's build.rs:
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
27 use libpam_sys::pam_impl;
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
28
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
29 fn main() {
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
30 pam_impl::enable_pam_impl_cfg();
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
31
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
32 // the rest of your build script...
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
33 }
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
34 ```
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
35
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
36 This will enable the use of `#[cfg]`s that look like this:
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
37
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
38 ```rust
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
39 #[cfg(pam_impl = "Sun")]
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
40 fn some_func() { /* Sun-specific implementation */ }
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
41
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
42 #[cfg(any(pam_impl = "LinuxPam", pam_impl = "OpenPam"))]
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
43 fn some_func() { /* Linux-PAM / OpenPAM implementation */ }
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
44 ```
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
45
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
46 Further documentation on this is available in `libpam-sys-consts`.
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
47
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
48 ## Testing
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
49
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
50 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
51
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
52 - [`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
53 - 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
54
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
55 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
56
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
57 ## Minimum Rust version
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
58
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
59 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
60 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
61
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
62 ## References
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
63
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
64 - [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
65 - [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
66 - [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
67 - [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
68 - [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
69 - [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
70 - [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
71 - [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
72
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
73 [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
74 [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
75 [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
76 [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
77 [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
78 [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
79 [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
80 [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
81 [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
82 [manillumos]: https://illumos.org/man/3PAM/pam