Mercurial > crates > nonstick

annotate src/lib.rs @ 62:d83623951070

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Further improve docs and put `conv` behind a feature gate.
author Paul Fisher <paul@pfish.zone>
date Wed, 21 May 2025 23:10:09 -0400
parents 05cc2c27334f
children a7aa5ca0d00d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
1 //! A safe, nonstick interface to PAM.
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
2 //!
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
3 //! This implements a type-safe library to interact with PAM.
62
d83623951070 Further improve docs and put `conv` behind a feature gate.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
4 //! Currently, it implements a subset of PAM useful for implementing a module.
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
5 //!
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
6 //! To write a new PAM module using this crate:
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
7 //!
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
8 //! 1. Create a `dylib` crate.
62
d83623951070 Further improve docs and put `conv` behind a feature gate.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
9 //! 2. Implement a subset of the functions in the [`PamModule`] trait
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
10 //! corresponding to what you want your module to do.
62
d83623951070 Further improve docs and put `conv` behind a feature gate.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
11 //! In the simplest case (for a new password-based authenticator),
d83623951070 Further improve docs and put `conv` behind a feature gate.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
12 //! this will be the [`sm_authenticate`](PamModule::sm_authenticate) function.
d83623951070 Further improve docs and put `conv` behind a feature gate.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
13 //! 3. Export your PAM module using the [`pam_hooks!`] macro.
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
14 //! 4. Build and install the dynamic library.
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
15 //! This usually entails placing it at
62
d83623951070 Further improve docs and put `conv` behind a feature gate.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
16 //! <code>/usr/lib/security/pam_<var>your_module</var>.so</code>,
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
17 //! or maybe
62
d83623951070 Further improve docs and put `conv` behind a feature gate.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
18 //! <code>/usr/lib/<var>your-architecture</var>/security/pam_<var>your_module</var>.so</code>.
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
19 //!
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
20 //! For general information on writing PAM modules, see
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
21 //! [The Linux-PAM Module Writers' Guide][module-guide]
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
22 //!
45
ce47901aab7a Rename to “nonstick”, move to root, update docs and license.
Paul Fisher <paul@pfish.zone>
parents: 34
diff changeset
23 //! [module-guide]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/Linux-PAM_MWG.html
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
24
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
25 pub mod constants;
62
d83623951070 Further improve docs and put `conv` behind a feature gate.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
26 #[cfg(feature = "experimental")]
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
27 pub mod conv;
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
28 pub mod items;
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
29 pub mod module;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
30
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
31 mod memory;
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
32 mod pam_ffi;
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
33
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
34 #[doc(inline)]
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
35 pub use crate::{
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
36 constants::{ErrorCode, Flags, MessageStyle, Result},
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
37 module::{PamHandle, PamModule},
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
38 };