Mercurial > crates > nonstick

comparison README.md @ 174:9e4ce1631bd3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Dramatically expand documentation.
author Paul Fisher <paul@pfish.zone>
date Tue, 29 Jul 2025 18:58:27 -0400
parents c9fc7e6257d3
children 42f747774d94
comparison
equal deleted inserted replaced
173:46e8ce5cd5d1 174:9e4ce1631bd3
1 # 🍳 nonstick 1 # 🍳 nonstick
2 2
3 Nonstick lets you use PAM (Pluggable Authentication Modules) from Rust without getting stuck in unsafe code. 3 Nonstick lets you use PAM (Pluggable Authentication Modules) from Rust safely.
4 Don't worry about getting stuck on unsafe code.
5
6 You can use nonstick for interacting with PAM from both sides:
7
8 - PAM applications: call into PAM to authenticate users.
9 - PAM modules: write a backend that PAM uses for authentication.
10
11 It supports all known PAM implementations:
12
13 - Linux-PAM, used on most (all?) Linux distributions.
14 - OpenPAM, used on most BSDs, including Mac OS.
15 - Sun's PAM, used on Solaris and derivatives like Illumos.
16
17 Further documentation can be found in the crate's rustdoc.
4 18
5 ## Status 19 ## Status
6 20
7 This is currently somewhat incomplete. 21 - **Modules**: full support for all calls by PAM into modules.
22 You can use nonstick to implement a PAM module that performs any stage of the PAM lifecycle.
8 23
9 It provides fairly robust functionality for developing PAM modules (i.e., backends that PAM calls to authenticate users or do something similar). 24 - **Applications**: supports only a subset of PAM features:
10 [Linux-PAM](https://github.com/linux-pam/linux-pam) is the only _tested_ PAM implementation, but it compiles against OpenPAM. 25
26 - Authentication
27 - Account management
28 - Password change
29
30 The remaining features (credential and session management) are coming in a future release.
31 (It needs work on a safe and ergonomic API.)
11 32
12 *If you’re looking for a library to implement a PAM client* (i.e., something that authenticates using PAM), consider the [`pam` crate](https://crates.io/crates/pam) for now. 33 The overall shape of the API is largely complete and its general shape should not change significantly.
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).
13 35
14 APIs are likely to break before v0.1.0, but thereafter should stabilize to an eventual 1.0 release. 36 ## Testing
15 After v0.1.0, the shape of the API should be mostly formed, and most of what happens will be adding new features.
16 37
17 Goals include: 38 Nonstick is tested against all supported PAM implementations.
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.
18 40
19 - Bindings for PAM clients. 41 ## Configuration
20 - Additional PAM features, like environment variables. 42
21 - Way more documentation. 43 By default, nonstick uses `libpam-sys` to detect which implementation of PAM it should build against.
44 You can also select to build your library or application against a specific PAM implementation by setting the `LIBPAMSYS_IMPL` environment variable.
45 See [the documentation for `libpam-sys`](https://docs.rs/libpam-sys/) for more details.
46
47 ## Cargo features
48
49 - `link` (enabled by default): Link against your system's PAM library.
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.
51 - `basic-ext` (enabled by default): Include enum values provided by both OpenPAM and Linux-PAM.
52 - `linux-pam-ext`: Include features specific to Linux-PAM, including enum values and the ability to send binary messages.
53 - `openpam-ext`: Include features specific to OpenPAM (just enum values).
54 - `sun-ext`: Include features specific to Sun PAM (just enum values).
55
56 When `link` is enabled, you can only use the PAM features available on the configured PAM implementation.
57 For instance, when building with Linux-PAM, `link` and `openpam-ext` cannot be used together.
58
59 However, when `link` is disabled, you could develop and test a crate with `sun-ext` enabled using any device.
22 60
23 ## Credits 61 ## Credits
24 62
25 This is a direct fork of [Anthony Nowell](http://anowell.com/)’s [`pam-rs`/`pam-bindings` crate](https://crates.io/crates/pam-bindings). 63 This is a direct fork of [Anthony Nowell](http://anowell.com/)’s [`pam-rs`/`pam-bindings` crate](https://crates.io/crates/pam-bindings).
26 `pam-rs` was in turn inspired by: 64 `pam-rs` was in turn inspired by: