Mercurial > crates > nonstick

comparison 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
comparison
equal deleted inserted replaced
59:3f4a77aa88be 60:05cc2c27334f
1 //! Interface to the pluggable authentication module framework (PAM). 1 //! A safe, nonstick interface to PAM.
2 //! 2 //!
3 //! The goal of this library is to provide a type-safe API that can be used to 3 //! This implements a type-safe library to interact with PAM.
4 //! interact with PAM. The library is incomplete - currently it supports 4 //! Currently, it implements the subset of PAM useful for implementing a module.
5 //! a subset of functions for use in a pam authentication module. A pam module
6 //! is a shared library that is invoked to authenticate a user, or to perform
7 //! other functions.
8 //! 5 //!
9 //! For general information on writing pam modules, see 6 //! To write a new PAM module using this crate:
7 //!
8 //! 1. Create a `dylib` crate.
9 //! 2. Implement a subset of the functions in the [PamModule] trait
10 //! corresponding to what you want your module to do.
11 //! In the simplest case (for a password-authentication system),
12 //! this will be the [PamModule::sm_authenticate] function.
13 //! 3. Export your PAM module using the [pam_hooks!] macro.
14 //! 4. Build and install the dynamic library.
15 //! This usually entails placing it at
16 //! `/usr/lib/security/pam_your_module.so`,
17 //! or maybe
18 //! <code>/usr/lib/<var>your-architecture</var>/security/pam_your_module.so</code>.
19 //!
20 //! For general information on writing PAM modules, see
10 //! [The Linux-PAM Module Writers' Guide][module-guide] 21 //! [The Linux-PAM Module Writers' Guide][module-guide]
11 //! 22 //!
12 //! [module-guide]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/Linux-PAM_MWG.html 23 //! [module-guide]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/Linux-PAM_MWG.html
13 //!
14 //! A typical authentication module will define an external function called
15 //! `pam_sm_authenticate()`, which will use functions in this library to
16 //! interrogate the program that requested authentication for more information,
17 //! and to render a result.
18 //!
19 //! Note that constants that are normally read from pam header files are
20 //! hard-coded in the `constants` module. The values there are taken from
21 //! a Linux system. That means that it might take some work to get this library
22 //! to work on other platforms.
23
24 extern crate libc;
25 24
26 pub mod constants; 25 pub mod constants;
27 pub mod conv; 26 pub mod conv;
28 pub mod items; 27 pub mod items;
29 #[doc(hidden)]
30 pub mod macros;
31 pub mod module; 28 pub mod module;
29
30 mod memory;
31 mod pam_ffi;
32
33 #[doc(inline)]
34 pub use crate::{
35 constants::{ErrorCode, Flags, MessageStyle, Result},
36 conv::Conversation,
37 module::{PamHandle, PamModule},
38 };