Mercurial > crates > nonstick

annotate libpam-sys/README.md @ 141:a508a69c068a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Remove a lot of Results from functions. Many functions are documented to only return failing Results when given improper inputs or when there is a memory allocation failure (which can be verified by looking at the source). In cases where we know our input is correct, we don't need to check for memory allocation errors for the same reason that Rust doesn't do so when you, e.g., create a new Vec.
author Paul Fisher <paul@pfish.zone>
date Sat, 05 Jul 2025 17:16:56 -0400
parents efbc235f01d3
children 4b3a5095f68c
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
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 129
diff changeset
8 ## PAM implementations
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 This crate detects the PAM implementation you have installed, or guesses based on the OS if that's unavailable.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 129
diff changeset
11 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
12
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 129
diff changeset
13 You can also explicitly specify the PAM implementation you want (if not detected correctly) by setting the `LIBPAMSYS_IMPL` environment variable **at build time**.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents: 129
diff changeset
14 All build-time configuration is performed by the build script of the [`libpam-sys-helpers` crate](https://crates.io/crates/libpam-sys-helpers).
108
e97534be35e3 Make some proc macros for doing cfg-like stuff for PAM impls.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
15
e97534be35e3 Make some proc macros for doing cfg-like stuff for PAM impls.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
16 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
17 `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
18
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
19 ## Testing
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
20
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
21 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
22
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
23 - [`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
24 - 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
25
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
26 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
27 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
28
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
29 ## Minimum Rust version
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 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
32 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
33
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
34 ## References
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
35
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
36 - [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
37 - [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
38 - [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
39 - [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
40 - [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
41 - [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
42 - [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
43 - [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
44
129
5b2de52dd8b2 Cleanups: create readmes, add a few docs, remove cruft.
Paul Fisher <paul@pfish.zone>
parents: 125
diff changeset
45 [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
46 [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
47 [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
48 [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
49 [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
50 [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
51 [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
52 [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
53 [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
54 [manillumos]: https://illumos.org/man/3PAM/pam