Mercurial > crates > nonstick

annotate src/lib.rs @ 64:bbe84835d6db v0.0.5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More organization; add lots of docs. - moves `PamHandle` to its own module, since it will be used by both modules and clients. - adds a ton of documentation to the `PamModule` trait and reorders methods to most-interesting-first. - adds more flag values from pam_modules.h. - other misc cleanup.
author Paul Fisher <paul@pfish.zone>
date Thu, 22 May 2025 01:52:32 -0400
parents a7aa5ca0d00d
children
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),
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 63
diff changeset
12 //! this will be the [`PamModule::authenticate`] function.
62
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;
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 63
diff changeset
29 mod module;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
30
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 63
diff changeset
31 mod handle;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
32 mod memory;
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
33 mod pam_ffi;
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
34
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
35 #[doc(inline)]
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
36 pub use crate::{
63
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used.
Paul Fisher <paul@pfish.zone>
parents: 62
diff changeset
37 constants::{ErrorCode, Flags, Result},
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 63
diff changeset
38 handle::PamHandle,
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 63
diff changeset
39 module::PamModule,
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
40 };