Mercurial > crates > nonstick

annotate src/lib.rs @ 60:05cc2c27334f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
The Big Refactor: clean up docs and exports. - Brings the most important symbols in the library to the root with `pub use` statements. - Expands and updates documentation. - Rearranges things extensively to make the external interface nicer and make the structure easier to understand. - Renames a few things (e.g. `Result`).
author Paul Fisher <paul@pfish.zone>
date Wed, 21 May 2025 19:00:51 -0400
parents 2a5c83d04b93
children d83623951070
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.
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
4 //! Currently, it implements the subset of PAM useful for implementing a module.
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.
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
9 //! 2. Implement a subset of the functions in the [PamModule] trait
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.
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
11 //! In the simplest case (for a password-authentication system),
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
12 //! this will be the [PamModule::sm_authenticate] function.
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
13 //! 3. Export your PAM module using the [pam_hooks!] macro.
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
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
16 //! `/usr/lib/security/pam_your_module.so`,
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
17 //! or maybe
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
18 //! <code>/usr/lib/<var>your-architecture</var>/security/pam_your_module.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;
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
26 pub mod conv;
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
27 pub mod items;
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
28 pub mod module;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
29
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
30 mod memory;
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
31 mod pam_ffi;
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
32
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
33 #[doc(inline)]
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
34 pub use crate::{
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
35 constants::{ErrorCode, Flags, MessageStyle, Result},
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
36 conv::Conversation,
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 };