Mercurial > crates > nonstick
comparison README.md @ 174:9e4ce1631bd3
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: |