Mercurial > crates > nonstick

annotate src/lib.rs @ 100:3f11b8d30f63

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Implement environment variable management. This actually wires up the environment variable handling to libpam, so that applications and modules can manage the environment through the authentication process.
author Paul Fisher <paul@pfish.zone>
date Tue, 24 Jun 2025 17:08:01 -0400
parents b87100c5eed4
children dfcd96a74ac4
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
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
25 // Temporary until everything is fully wired up.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
26 #![allow(dead_code)]
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
27
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
28 pub mod constants;
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
29 pub mod conv;
70
9f8381a1c09c Implement low-level conversation primitives.
Paul Fisher <paul@pfish.zone>
parents: 69
diff changeset
30 pub mod module;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
31
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
32 pub mod handle;
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
33
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 96
diff changeset
34 mod environ;
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
35 #[cfg(feature = "link")]
75
c30811b4afae rename pam_ffi submodule to libpam.
Paul Fisher <paul@pfish.zone>
parents: 74
diff changeset
36 mod libpam;
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 75
diff changeset
37 pub mod logging;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
38
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
39 #[cfg(feature = "link")]
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 96
diff changeset
40 #[doc(inline)]
75
c30811b4afae rename pam_ffi submodule to libpam.
Paul Fisher <paul@pfish.zone>
parents: 74
diff changeset
41 pub use crate::libpam::{LibPamHandle, OwnedLibPamHandle};
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
42 #[doc(inline)]
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
43 pub use crate::{
63
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used.
Paul Fisher <paul@pfish.zone>
parents: 62
diff changeset
44 constants::{ErrorCode, Flags, Result},
96
f3e260f9ddcb Make conversation trait use immutable references.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
45 conv::{BinaryData, Conversation, ConversationAdapter},
100
3f11b8d30f63 Implement environment variable management.
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
46 environ::{EnvironMap, EnvironMapMut},
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
47 handle::{PamHandleApplication, PamHandleModule, PamShared},
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 63
diff changeset
48 module::PamModule,
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
49 };