Mercurial > crates > nonstick

annotate libpam-sys/README.md @ 183:4f46681b3f54 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Catch a few stray cargo fmt things.
author Paul Fisher <paul@pfish.zone>
date Wed, 30 Jul 2025 18:43:07 -0400
parents 0730f5f2ee2a
children
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**.
176
0730f5f2ee2a Turn `libpam-sys-consts` back into `libpam-sys-impls`.
Paul Fisher <paul@pfish.zone>
parents: 162
diff changeset
16 All build-time configuration is performed by the build script of the [`libpam-sys-impls` crate](https://crates.io/crates/libpam-sys-impls).
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
176
0730f5f2ee2a Turn `libpam-sys-consts` back into `libpam-sys-impls`.
Paul Fisher <paul@pfish.zone>
parents: 162
diff changeset
46 Further documentation on this is available in `libpam-sys-impls`.
161
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