Mercurial > crates > nonstick
annotate libpam-sys/README.md @ 141:a508a69c068a
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 |
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 |