Mercurial > crates > nonstick

annotate src/lib.rs @ 171:e27c5c667a5a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Create full new types for return code and flags, separate end to end. This plumbs the ReturnCode and RawFlags types through the places where we call into or are called from PAM. Also adds Sun documentation to the project.
author Paul Fisher <paul@pfish.zone>
date Fri, 25 Jul 2025 20:52:14 -0400
parents 2f5913131295
children 46e8ce5cd5d1
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
171
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
25 #[cfg(feature = "link")]
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
26 mod _compat_checker {
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
27 macro_rules! feature_check {
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
28 ($feature:literal, pam_impl = ($($pimpl:literal),*)) => {
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
29 #[cfg(all(feature = $feature, not(any($(pam_impl = $pimpl),*))))]
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
30 compile_error!(
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
31 concat!(
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
32 "The feature '", $feature, "' is only available ",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
33 "with these PAM implementations:\n",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
34 $("- ", $pimpl, "\n"),*,
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
35 "The current PAM implementation is:\n\n",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
36 " ", libpam_sys::pam_impl_name!(), "\n\n",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
37 "Set the 'LIBPAMSYS_IMPL' environment variable to one of ",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
38 "the above PAM implementation names to build ",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
39 "for that implementation of PAM."
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
40 )
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
41 );
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
42 }
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
43 }
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
44 feature_check!("linux-pam-ext", pam_impl = ("LinuxPam"));
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
45 feature_check!("basic-ext", pam_impl = ("LinuxPam", "OpenPam"));
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
46 feature_check!("openpam-ext", pam_impl = ("OpenPam"));
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
47 feature_check!("sun-ext", pam_impl = ("Sun"));
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
48 }
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
49
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
50 pub mod constants;
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
51 pub mod conv;
70
9f8381a1c09c Implement low-level conversation primitives.
Paul Fisher <paul@pfish.zone>
parents: 69
diff changeset
52 pub mod module;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
53
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
54 pub mod handle;
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
55
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
56 mod _doc;
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 96
diff changeset
57 mod environ;
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
58 pub mod items;
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
59 #[cfg(feature = "link")]
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
60 pub mod libpam;
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 75
diff changeset
61 pub mod logging;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
62
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
63 #[cfg(feature = "link")]
171
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
64 #[doc(hidden)]
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
65 pub use crate::libpam::ModuleExporter;
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
66 #[cfg(feature = "link")]
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 96
diff changeset
67 #[doc(inline)]
171
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
68 pub use crate::libpam::{LibPamHandle, LibPamTransaction, TransactionBuilder};
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
69 #[doc(inline)]
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
70 pub use crate::{
166
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
71 constants::{
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
72 AuthnFlags, AuthtokAction, AuthtokFlags, BaseFlags, CredAction, ErrorCode, Result,
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
73 },
96
f3e260f9ddcb Make conversation trait use immutable references.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
74 conv::{BinaryData, Conversation, ConversationAdapter},
100
3f11b8d30f63 Implement environment variable management.
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
75 environ::{EnvironMap, EnvironMapMut},
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
76 handle::{ModuleClient, PamShared, Transaction},
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 63
diff changeset
77 module::PamModule,
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
78 };