Mercurial > crates > nonstick

changeset 193:5074d8e00560

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Doc improvements.
author Paul Fisher <paul@pfish.zone>
date Sat, 02 Aug 2025 19:49:21 -0400
parents 4c39eaa4a5ae
children 58c0118b8b77
files src/constants.rs src/environ.rs src/lib.rs src/module.rs
diffstat 4 files changed, 55 insertions(+), 41 deletions(-) [+]
line wrap: on
line diff
--- a/src/constants.rs	Sat Aug 02 19:24:12 2025 -0400
+++ b/src/constants.rs	Sat Aug 02 19:49:21 2025 -0400
@@ -229,6 +229,9 @@
 }
 
 flag_enum! {
+    /// The action that a module should take during a [`change_authtok`] call.
+    ///
+    /// [`change_authtok`]: crate::PamModule::change_authtok
     AuthtokAction {
         /// On this call, just validate that the password is acceptable
         /// and that you have all the resources you need to change it.
--- a/src/environ.rs	Sat Aug 02 19:24:12 2025 -0400
+++ b/src/environ.rs	Sat Aug 02 19:49:21 2025 -0400
@@ -1,14 +1,11 @@
-//! Traits and stuff for managing the environment of a PAM handle.
+//! Traits for managing the environment of a PAM handle.
 //!
 //! PAM modules can set environment variables to apply to a user session.
 //! This module manages the interface for doing all of that.
 
 use std::ffi::{OsStr, OsString};
 
-/// A key/value map for environment variables, as [`OsString`]s.
-///
-/// This is a limited subset of what [`HashMap`](std::collections::HashMap)
-/// can do. Notably, we do *not* support mutable iteration.
+/// A read-only key/value map for environment variables, as [`OsString`]s.
 pub trait EnvironMap<'a> {
     /// Gets the environment variable of the given key.
     fn get(&self, key: impl AsRef<OsStr>) -> Option<OsString>;
@@ -17,6 +14,10 @@
     fn iter(&self) -> impl Iterator<Item = (OsString, OsString)>;
 }
 
+/// A read/write key/value map for environment variables as [`OsString`]s.
+///
+/// This is a limited subset of what [`HashMap`](std::collections::HashMap)
+/// can do. Notably, we do *not* support mutable iteration.
 pub trait EnvironMapMut<'a>: EnvironMap<'a> {
     /// Sets the environment variable with the given key,
     /// returning the old one if present.
--- a/src/lib.rs	Sat Aug 02 19:24:12 2025 -0400
+++ b/src/lib.rs	Sat Aug 02 19:49:21 2025 -0400
@@ -84,15 +84,25 @@
 //! the address space of the calling application. To implement a module,
 //! create a `dylib` crate and implement a [`PamModule`], and export it
 //! using the [`pam_export!`] macro.
+//!
 //! ```toml
-//! ## Your Cargo.toml
+//! # Your Cargo.toml
 //! [package]
-//! name = "example-package"
-//! ## ...
+//! name = "samename"
+//! description = "Checks that username and password are the same"
+//! # ...
 //!
 //! [lib]
 //! crate-type = ["cdylib"]
+//!
+//! [dependencies]
+//! nonstick = "0.1"
+//! # ...
 //! ```
+//!
+//! Once you've set up the dylib crate and added `nonstick` as a dependency,
+//! you can write the code itself:
+//!
 //! ```
 //! // Your lib.rs
 //!
@@ -127,10 +137,10 @@
 //! }
 //! ```
 //!
-//! This gets built into a library like `pam_samename.so`. By installing this
-//! into your PAM library directory and configuring PAM to use it in
-//! the authentication stack (beyond the scope of this documentation), it will
-//! be used to authenticate users.
+//! This gets built into a shared object. By installing this into the PAM
+//! library directory at a place like `pam_samename.so` and configuring PAM
+//! to use it in the authentication stack (beyond the scope of this
+//! documentation), it will be used to authenticate users.
 //!
 //! # Configuration
 //!
--- a/src/module.rs	Sat Aug 02 19:24:12 2025 -0400
+++ b/src/module.rs	Sat Aug 02 19:49:21 2025 -0400
@@ -3,12 +3,25 @@
 // Temporarily allowed until we get the actual conversation functions hooked up.
 #![allow(dead_code)]
 
+use crate::_doc::{guide, linklist, stdlinks};
 use crate::constants::{
     AuthnFlags, AuthtokAction, AuthtokFlags, BaseFlags, CredAction, ErrorCode, Result,
 };
 use crate::handle::ModuleClient;
 use std::ffi::CStr;
 
+macro_rules! sm_refs {
+    ($sym:ident: $guide:literal) => {
+        concat!(
+            linklist!($sym: mwg, _std),
+            "\n\n",
+            guide!(mwg: $guide),
+            "\n",
+            stdlinks!(3 $sym),
+        )
+    }
+}
+
 /// A trait for a PAM module to implement.
 ///
 /// The default implementations of all these hooks tell PAM to ignore them
@@ -17,11 +30,10 @@
 /// After implementing this trait, use the [`pam_export!`](crate::pam_export!) macro
 /// to make the functions available to PAM.
 ///
-/// For more information, see [`pam(3)`’s root manual page][manpage]
-/// and the [PAM Module Writer’s Guide][mwg].
-///
-/// [manpage]: https://www.man7.org/linux/man-pages/man3/pam.3.html
-/// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/Linux-PAM_MWG.html
+/// For more information about how to write a module, see "[What is expected
+/// of a module?][what]" in the Module Writers' Guide.
+#[doc = ""]
+#[doc = guide!(what: "mwg-expected-of-module-overview.html")]
 #[allow(unused_variables)]
 pub trait PamModule<T: ModuleClient> {
     // Functions for auth modules.
@@ -34,9 +46,6 @@
     /// and [`ModuleClient::authtok`],
     /// and verify them against something.
     ///
-    /// See [the Module Writer's Guide entry for `pam_sm_authenticate`][mwg]
-    /// for more information.
-    ///
     /// # Returns
     ///
     /// If the password check was successful, return `Ok(())`.
@@ -53,7 +62,8 @@
     /// - [`ErrorCode::MaxTries`]: The user has tried authenticating too many times.
     ///   They should not try again.
     ///
-    /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-auth.html#mwg-pam_sm_authenticate
+    /// # References
+    #[doc = sm_refs!(pam_sm_authenticate: "mwg-expected-of-module-auth.html#mwg-pam_sm_authenticate")]
     fn authenticate(handle: &mut T, args: Vec<&CStr>, flags: AuthnFlags) -> Result<()> {
         Err(ErrorCode::Ignore)
     }
@@ -71,9 +81,6 @@
     /// and alert that the user change it before continuing,
     /// or really do whatever you want.
     ///
-    /// See [the Module Writer's Guide entry for `pam_sm_acct_mgmt`][mwg]
-    /// for more information.
-    ///
     /// # Returns
     ///
     /// If the user should be allowed to log in, return `Ok(())`.
@@ -88,7 +95,8 @@
     /// - [`ErrorCode::PermissionDenied`]: This one is pretty self-explanatory.
     /// - [`ErrorCode::UserUnknown`]: The supplied username is not known by this service.
     ///
-    /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-acct.html#mwg-pam_sm_acct_mgmt
+    /// # References
+    #[doc = sm_refs!(pam_sm_acct_mgmt: "mwg-expected-of-module-acct.html#mwg-pam_sm_acct_mgmt")]
     fn account_management(handle: &mut T, args: Vec<&CStr>, flags: AuthnFlags) -> Result<()> {
         Err(ErrorCode::Ignore)
     }
@@ -102,9 +110,6 @@
     ///
     /// The module should perform the specified `action`.
     ///
-    /// See [the Module Writer's Guide entry for `pam_sm_setcred`][mwg]
-    /// for more information.
-    ///
     /// # Returns
     ///
     /// If credentials were set successfully, return `Ok(())`.
@@ -116,7 +121,8 @@
     /// - [`ErrorCode::CredentialsError`]: Some other error occurred when setting credentials.
     /// - [`ErrorCode::UserUnknown`]: The supplied username is not known by this service.
     ///
-    /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-auth.html#mwg-pam_sm_setcred
+    /// # References
+    #[doc = sm_refs!(pam_sm_setcred: "mwg-expected-of-module-auth.html#mwg-pam_sm_setcred")]
     fn set_credentials(
         handle: &mut T,
         args: Vec<&CStr>,
@@ -144,9 +150,6 @@
     /// and the previous authentication token will be available in
     /// [`old_authtok`](ModuleClient::old_authtok).
     ///
-    /// See [the Module Writer's Guide entry for `pam_sm_chauthtok`][mwg]
-    /// for more information.
-    ///
     /// # Returns
     ///
     /// If the authentication token was changed successfully
@@ -164,7 +167,8 @@
     ///   ask the user for a new authentication token.
     /// - [`ErrorCode::UserUnknown`]: The supplied username is not known by this service.
     ///
-    /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-chauthtok.html#mwg-pam_sm_chauthtok
+    /// # References
+    #[doc = sm_refs!(pam_sm_chauthtok: "mwg-expected-of-module-acct.html#mwg-pam_sm_chauthtok")]
     fn change_authtok(
         handle: &mut T,
         args: Vec<&CStr>,
@@ -178,9 +182,6 @@
 
     /// Called when a session is opened.
     ///
-    /// See [the Module Writer's Guide entry for `pam_sm_open_session`][mwg]
-    /// for more information.
-    ///
     /// # Returns
     ///
     /// If the session was opened successfully, return `Ok(())`.
@@ -189,16 +190,14 @@
     ///
     /// - [`ErrorCode::SessionError`]: Cannot make an entry for this session.
     ///
-    /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-session.html#mwg-pam_sm_open_session
+    /// # References
+    #[doc = sm_refs!(pam_sm_open_session: "mwg-expected-of-module-session.html#mwg-pam_sm_open_session")]
     fn open_session(handle: &mut T, args: Vec<&CStr>, flags: BaseFlags) -> Result<()> {
         Err(ErrorCode::Ignore)
     }
 
     /// Called when a session is being terminated.
     ///
-    /// See [the Module Writer's Guide entry for `pam_sm_close_session`][mwg]
-    /// for more information.
-    ///
     /// # Returns
     ///
     /// If the session was closed successfully, return `Ok(())`.
@@ -207,7 +206,8 @@
     ///
     /// - [`ErrorCode::SessionError`]: Cannot remove an entry for this session.
     ///
-    /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-session.html#mwg-pam_sm_close_session
+    /// # References
+    #[doc = sm_refs!(pam_sm_close_session: "mwg-expected-of-module-session.html#mwg-pam_sm_close_session")]
     fn close_session(handle: &mut T, args: Vec<&CStr>, flags: BaseFlags) -> Result<()> {
         Err(ErrorCode::Ignore)
     }