Mercurial > crates > nonstick

annotate README.md @ 184:42f747774d94

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Really get documentation stuff squared away. Expand READMEs and polish off module documentation.
author Paul Fisher <paul@pfish.zone>
date Thu, 31 Jul 2025 14:36:50 -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
184
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
3 Nonstick lets you use PAM (Pluggable Authentication Modules) from Rust.
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
4 Never worry about getting stuck on unsafe code.
174
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
184
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
19 ## Why use nonstick?
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
20
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
21 - Safe, idiomatic Rust API.
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
22 - Supports both modules and client applications.
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
23 - Works with all PAM implementations.
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
24 - Does not require system headers.
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
25 - Few dependencies, fast builds (no `syn`!).
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
26 - Well-tested on multiple platforms (AMD64 Linux, FreeBSD, and Illumos).
42f747774d94 Really get documentation stuff squared away.
Paul Fisher <paul@pfish.zone>
parents: 174
diff changeset
27
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
28 ## Status
16
f64ee7b6cdf1 Update metadata and README
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
29
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
30 - **Modules**: full support for all calls by PAM into modules.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
31 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
32
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
33 - **Applications**: supports only a subset of PAM features:
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
34
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
35 - Authentication
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
36 - Account management
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
37 - Password change
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
38
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
39 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
40 (It needs work on a safe and ergonomic API.)
16
f64ee7b6cdf1 Update metadata and README
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
41
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
42 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
43 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
44
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
45 ## Testing
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 Nonstick is tested against all supported PAM implementations.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
48 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
49
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
50 ## Configuration
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
51
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
52 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
53 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
54 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
55
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
56 ## Cargo features
17
53efbcff805d Add pam-sober
Anthony Nowell <anthony@algorithmia.com>
parents: 16
diff changeset
57
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
58 - `link` (enabled by default): Link against your system's PAM library.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
59 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
60 - `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
61 - `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
62 - `openpam-ext`: Include features specific to OpenPAM (just enum values).
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
63 - `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
64
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
65 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
66 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
67
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 88
diff changeset
68 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
69
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
70 ## Credits
16
f64ee7b6cdf1 Update metadata and README
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
71
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
72 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
73 `pam-rs` was in turn inspired by:
16
f64ee7b6cdf1 Update metadata and README
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
74
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 17
diff changeset
75 - [`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
76 - [`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
77 - [`pam-http` by beatgammit](https://github.com/beatgammit/pam-http)