Mercurial > crates > nonstick

annotate 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 9e4ce1631bd3
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
1 # 🍳 nonstick
16
f64ee7b6cdf1 Update metadata and README
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
2
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
3 Nonstick lets you use PAM (Pluggable Authentication Modules) from Rust safely.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
4 Don't worry about getting stuck on unsafe code.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
5
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
6 You can use nonstick for interacting with PAM from both sides:
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
7
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
8 - PAM applications: call into PAM to authenticate users.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
9 - PAM modules: write a backend that PAM uses for authentication.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
10
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
11 It supports all known PAM implementations:
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
12
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
13 - Linux-PAM, used on most (all?) Linux distributions.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
14 - OpenPAM, used on most BSDs, including Mac OS.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
15 - Sun's PAM, used on Solaris and derivatives like Illumos.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
16
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
17 Further documentation can be found in the crate's rustdoc.
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
18
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
19 ## Status
16
f64ee7b6cdf1 Update metadata and README
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
20
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
21 - **Modules**: full support for all calls by PAM into modules.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
22 You can use nonstick to implement a PAM module that performs any stage of the PAM lifecycle.
88
c9fc7e6257d3 This is a v0.0.7 if I ever saw one.
Paul Fisher <paul@pfish.zone>
parents: 62
diff changeset
23
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
24 - **Applications**: supports only a subset of PAM features:
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
25
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
26 - Authentication
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
27 - Account management
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
28 - Password change
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
29
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
30 The remaining features (credential and session management) are coming in a future release.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
31 (It needs work on a safe and ergonomic API.)
16
f64ee7b6cdf1 Update metadata and README
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
32
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
33 The overall shape of the API is largely complete and its general shape should not change significantly.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
34 While there may still be minor source incompatibilities pre-1.0 (e.g., moving methods around), it is unlikely that the library will be radically reworked (and I will try to avoid them unless needed).
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
35
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
36 ## Testing
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
37
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
38 Nonstick is tested against all supported PAM implementations.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
39 In addition to doctests and unit tests in the source itself, the (non-public) `testharness` sub-package performs end-to-end tests against the whole authentication process.
62
d83623951070 Further improve docs and put `conv` behind a feature gate.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
40
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
41 ## Configuration
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
42
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
43 By default, nonstick uses `libpam-sys` to detect which implementation of PAM it should build against.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
44 You can also select to build your library or application against a specific PAM implementation by setting the `LIBPAMSYS_IMPL` environment variable.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
45 See [the documentation for `libpam-sys`](https://docs.rs/libpam-sys/) for more details.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
46
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
47 ## Cargo features
17
53efbcff805d Add pam-sober
Anthony Nowell <anthony@algorithmia.com>
parents: 16
diff changeset
48
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
49 - `link` (enabled by default): Link against your system's PAM library.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
50 If disabled, you can still use the PAM traits and enum types to build and test your own PAM code independent of your system PAM.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
51 - `basic-ext` (enabled by default): Include enum values provided by both OpenPAM and Linux-PAM.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
52 - `linux-pam-ext`: Include features specific to Linux-PAM, including enum values and the ability to send binary messages.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
53 - `openpam-ext`: Include features specific to OpenPAM (just enum values).
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
54 - `sun-ext`: Include features specific to Sun PAM (just enum values).
17
53efbcff805d Add pam-sober
Anthony Nowell <anthony@algorithmia.com>
parents: 16
diff changeset
55
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
56 When `link` is enabled, you can only use the PAM features available on the configured PAM implementation.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
57 For instance, when building with Linux-PAM, `link` and `openpam-ext` cannot be used together.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
58
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
59 However, when `link` is disabled, you could develop and test a crate with `sun-ext` enabled using any device.
17
53efbcff805d Add pam-sober
Anthony Nowell <anthony@algorithmia.com>
parents: 16
diff changeset
60
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
61 ## Credits
16
f64ee7b6cdf1 Update metadata and README
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
62
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
63 This is a direct fork of [Anthony Nowell](http://anowell.com/)’s [`pam-rs`/`pam-bindings` crate](https://crates.io/crates/pam-bindings).
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
64 `pam-rs` was in turn inspired by:
16
f64ee7b6cdf1 Update metadata and README
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
65
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
66 - [`rust-pam` by tozny](https://github.com/tozny/rust-pam)
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
67 - [`pam_groupmap` by ndenev](https://github.com/ndenev/pam_groupmap)
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
68 - [`pam-http` by beatgammit](https://github.com/beatgammit/pam-http)