crates/nonstick: src/handle.rs annotate

annotate src/handle.rs @ 141:a508a69c068a

Remove a lot of Results from functions. Many functions are documented to only return failing Results when given improper inputs or when there is a memory allocation failure (which can be verified by looking at the source). In cases where we know our input is correct, we don't need to check for memory allocation errors for the same reason that Rust doesn't do so when you, e.g., create a new Vec.

author	Paul Fisher <paul@pfish.zone>
date	Sat, 05 Jul 2025 17:16:56 -0400
parents	a12706e42c9d
children	ebb71a412b58

rev	line source
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	1 //! The wrapper types and traits for handles into the PAM library.
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	2
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	3 use crate::constants::{Flags, Result};
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	4 use crate::conv::Conversation;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	5 use crate::environ::{EnvironMap, EnvironMapMut};
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	6 use crate::logging::{Level, Location};
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	7 use crate::{guide, linklist, man7, manbsd, stdlinks};
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	8
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	9 macro_rules! trait_item {
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	10 ($(#[$md:meta])* get = $getter:ident, item = $item:literal $(, see = $see:path)?) => {
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	11 $(#[$md])*
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	12 #[doc = ""]
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	13 #[doc = concat!("Gets the `", $item, "` of the PAM handle.")]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	14 $(
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	15 #[doc = concat!("See [`", stringify!($see), "`].")]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	16 )?
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	17 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	18 /// Returns a reference to the item's value, owned by PAM.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	19 /// The item is assumed to be valid UTF-8 text.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	20 /// If it is not, `ConversationError` is returned.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	21 ///
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	22 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	23 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	24 #[doc = linklist!(pam_get_item: mwg, adg, _std)]
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	25 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	26 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_get_item")]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	27 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_item")]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	28 #[doc = stdlinks!(3 pam_get_item)]
95 51c9d7e8261a Return owned strings rather than borrowed strings. Paul Fisher <paul@pfish.zone> parents: 94 diff changeset	29 fn $getter(&self) -> Result<Option<String>>;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	30 };
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	31 ($(#[$md:meta])* set = $setter:ident, item = $item:literal $(, see = $see:path)?) => {
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	32 $(#[$md])*
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	33 #[doc = ""]
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	34 #[doc = concat!("Sets the `", $item, "` from the PAM handle.")]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	35 $(
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	36 #[doc = concat!("See [`", stringify!($see), "`].")]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	37 )?
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	38 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	39 /// Sets the item's value. PAM copies the string's contents.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	40 /// If the string contains a null byte, this will return
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	41 /// a `ConversationError`.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	42 ///
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	43 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	44 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	45 #[doc = linklist!(pam_set_item: mwg, adg, _std)]
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	46 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	47 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	48 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	49 #[doc = stdlinks!(3 pam_set_item)]
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	50 fn $setter(&mut self, value: Option<&str>) -> Result<()>;
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	51 };
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	52 }
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	53
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	54 /// Functionality for both PAM applications and PAM modules.
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	55 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	56 /// This base trait includes features of a PAM handle that are available
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	57 /// to both applications and modules.
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	58 ///
75 c30811b4afae rename pam_ffi submodule to libpam. Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	59 /// You probably want [`LibPamHandle`](crate::libpam::OwnedLibPamHandle).
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	60 /// This trait is intended to allow creating mock PAM handle types
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	61 /// to test PAM modules and applications.
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	62 pub trait PamShared {
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	63 /// Logs something via this PAM handle.
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	64 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	65 /// You probably want to use one of the logging macros,
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	66 /// like [`error!`](crate::error!),
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	67 /// [`warn!`](crate::warn!),
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	68 /// [`info!`](crate::info!),
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	69 /// or [`debug!`](crate::debug!).
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	70 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	71 /// In most PAM implementations, this will go to syslog.
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	72 /// See [Linux-PAM's `pam_syslog`][man7] or
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	73 /// [OpenPAM's `openpam_log`][manbsd] for more details.
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	74 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	75 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	76 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	77 /// ```no_run
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	78 /// # use nonstick::PamShared;
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	79 /// use nonstick::logging::Level;
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	80 /// use nonstick::location;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	81 /// # fn _test(pam_hdl: impl PamShared) {
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	82 /// # let delay_ms = 100;
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	83 /// # let url = "https://zombo.com";
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	84 /// // Usually, instead of calling this manually, just use the macros.
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	85 /// nonstick::error!(pam_hdl, "something bad happened!");
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	86 /// nonstick::warn!(pam_hdl, "loading information took {delay_ms} ms");
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	87 /// nonstick::info!(pam_hdl, "using network backend");
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	88 /// nonstick::debug!(pam_hdl, "sending GET request to {url}");
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	89 /// // But if you really want to, you can call this yourself:
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	90 /// pam_hdl.log(Level::Warning, location!(), "this is unnecessarily verbose");
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	91 /// # }
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	92 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	93 #[doc = man7!(3 pam_syslog)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	94 #[doc = manbsd!(3 openpam_log)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	95 fn log(&self, level: Level, loc: Location<'_>, entry: &str);
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	96
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	97 /// Retrieves the name of the user who is authenticating or logging in.
d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	98 ///
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	99 /// If the username has previously been obtained, this uses that username;
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	100 /// otherwise it prompts the user with the first of these that is present:
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	101 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	102 /// 1. The prompt string passed to this function.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	103 /// 2. The string returned by `get_user_prompt_item`.
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	104 /// 3. The default prompt, `login: `.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	105 ///
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	106 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	107 #[doc = linklist!(pam_get_user: mwg, _std)]
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	108 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	109 /// # Example
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	110 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	111 /// ```no_run
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	112 /// # use nonstick::PamShared;
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	113 /// # fn _doc(handle: &mut impl PamShared) -> Result<(), Box<dyn std::error::Error>> {
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	114 /// // Get the username using the default prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	115 /// let user = handle.username(None)?;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	116 /// // Get the username using a custom prompt.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	117 /// // If this were actually called right after the above,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	118 /// // both user and user_2 would have the same value.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	119 /// let user_2 = handle.username(Some("who ARE you even???"))?;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	120 /// # Ok(())
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	121 /// # }
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	122 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	123 #[doc = stdlinks!(3 pam_get_user)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	124 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
95 51c9d7e8261a Return owned strings rather than borrowed strings. Paul Fisher <paul@pfish.zone> parents: 94 diff changeset	125 fn username(&mut self, prompt: Option<&str>) -> Result<String>;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	126
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	127 /// The contents of the environment to set, read-only.
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	128 fn environ(&self) -> impl EnvironMap;
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	129
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	130 /// A writable version of the environment.
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	131 fn environ_mut(&mut self) -> impl EnvironMapMut;
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	132
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	133 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	134 /// The identity of the user for whom service is being requested.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	135 ///
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	136 /// Unlike [`username`](Self::username), this will simply get
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	137 /// the current state of the user item, and not request the username.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	138 /// While PAM usually sets this automatically in the `username` call,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	139 /// it may be changed by a module during the PAM transaction.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	140 /// Applications should check it after each step of the PAM process.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	141 get = user_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	142 item = "PAM_USER",
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	143 see = Self::username
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	144 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	145 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	146 /// Sets the identity of the logging-in user.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	147 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	148 /// Usually this will be set during the course of
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	149 /// a [`username`](Self::username) call, but you may set it manually
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	150 /// or change it during the PAM process.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	151 set = set_user_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	152 item = "PAM_USER",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	153 see = Self::user_item
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	154 );
44 50371046c61a Add support for pam_get_authtok and minor cleanups. Paul Fisher <paul@pfish.zone> parents: 34 diff changeset	155
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	156 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	157 /// The service name, which identifies the PAM stack which is used
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	158 /// to perform authentication.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	159 get = service,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	160 item = "PAM_SERVICE"
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	161 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	162 trait_item!(
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	163 /// Sets the service name. It's probably a bad idea to change this.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	164 set = set_service,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	165 item = "PAM_SERVICE",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	166 see = Self::service
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	167 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	168
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	169 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	170 /// The string used to prompt for a user's name.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	171 /// By default, this is a localized version of `login: `.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	172 get = user_prompt,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	173 item = "PAM_USER_PROMPT"
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	174 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	175 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	176 /// Sets the string used to prompt for a user's name.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	177 set = set_user_prompt,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	178 item = "PAM_USER_PROMPT",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	179 see = Self::user_prompt
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	180 );
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	181
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	182 trait_item!(
91 039aae9a01f7 Improve documentation on TTY functions. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	183 /// The device path of the TTY being used to log in.
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	184 ///
91 039aae9a01f7 Improve documentation on TTY functions. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	185 /// This is the terminal the user is logging in on,
039aae9a01f7 Improve documentation on TTY functions. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	186 /// specified as the full device path (e.g. `/dev/tty0`).
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	187 /// Very old applications may use this instead of `PAM_XDISPLAY`.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	188 get = tty_name,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	189 item = "PAM_TTY"
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	190 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	191 trait_item!(
91 039aae9a01f7 Improve documentation on TTY functions. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	192 /// Sets the path to the terminal where the user is logging on.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	193 set = set_tty_name,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	194 item = "PAM_TTY",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	195 see = Self::tty_name
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	196 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	197
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	198 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	199 /// If set, the identity of the remote user logging in.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	200 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	201 /// This is only as trustworthy as the application calling PAM.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	202 get = remote_user,
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	203 item = "PAM_RUSER",
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	204 see = Self::remote_host
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	205 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	206 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	207 /// Sets the identity of the remote user logging in.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	208 ///
100 3f11b8d30f63 Implement environment variable management. Paul Fisher <paul@pfish.zone> parents: 98 diff changeset	209 /// This may be set by the application before making calls
3f11b8d30f63 Implement environment variable management. Paul Fisher <paul@pfish.zone> parents: 98 diff changeset	210 /// into a PAM transaction.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	211 set = set_remote_user,
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	212 item = "PAM_RUSER",
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	213 see = Self::remote_user
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	214 );
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	215
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	216 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	217 /// If set, the remote location where the user is coming from.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	218 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	219 /// This is only as trustworthy as the application calling PAM.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	220 /// This can be combined with [`Self::remote_user`] to identify
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	221 /// the account the user is attempting to log in from,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	222 /// with `remote_user@remote_host`.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	223 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	224 /// If unset, "it is unclear where the authentication request
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	225 /// is originating from."
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	226 get = remote_host,
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	227 item = "PAM_RHOST",
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	228 see = Self::remote_user
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	229 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	230 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	231 /// Sets the location where the user is coming from.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	232 ///
100 3f11b8d30f63 Implement environment variable management. Paul Fisher <paul@pfish.zone> parents: 98 diff changeset	233 /// This may be set by the application before making calls
3f11b8d30f63 Implement environment variable management. Paul Fisher <paul@pfish.zone> parents: 98 diff changeset	234 /// into a PAM transaction.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	235 set = set_remote_host,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	236 item = "PAM_RHOST",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	237 see = Self::remote_host
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	238 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	239
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	240 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	241 /// Gets the user's authentication token (e.g., password).
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	242 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	243 /// This is usually set automatically when
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	244 /// [`authtok`](PamHandleModule::authtok) is called,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	245 /// but can be manually set.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	246 set = set_authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	247 item = "PAM_AUTHTOK",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	248 see = PamHandleModule::authtok_item
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	249 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	250
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	251 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	252 /// Sets the user's "old authentication token" when changing passwords.
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	253 ///
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	254 /// This is usually set automatically by PAM.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	255 set = set_old_authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	256 item = "PAM_OLDAUTHTOK",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	257 see = PamHandleModule::old_authtok_item
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	258 );
69 8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	259 }
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	260
69 8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	261 /// Functionality of a PAM handle that can be expected by a PAM application.
8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	262 ///
8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	263 /// If you are not writing a PAM client application (e.g., you are writing
8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	264 /// a module), you should not use the functionality exposed by this trait.
8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	265 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	266 /// Like [`PamShared`], this is intended to allow creating mock implementations
69 8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	267 /// of PAM for testing PAM applications.
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	268 pub trait PamHandleApplication: PamShared {
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	269 /// Starts the authentication process for the user.
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	270 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	271 /// The application calls this to find out who the user is, and verify that
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	272 /// they are really that person. If authentication is successful,
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	273 /// this will return an `Ok(())` [`Result`].
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	274 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	275 /// A PAM module may change the caller's [username](PamShared::username)
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	276 /// as part of the login process, so be sure to check it after making
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	277 /// any PAM application call.
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	278 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	279 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	280 #[doc = linklist!(pam_authenticate: adg, _std)]
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	281 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	282 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_authenticate")]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	283 #[doc = stdlinks!(3 pam_authenticate)]
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	284 fn authenticate(&mut self, flags: Flags) -> Result<()>;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	285
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	286 /// Verifies the validity of the user's account (and other stuff).
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	287 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	288 /// After [authentication](Self::authenticate), an application should call
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	289 /// this to ensure that the user's account is still valid. This may check
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	290 /// for token expiration or that the user's account is not locked.
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	291 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	292 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	293 #[doc = linklist!(pam_acct_mgmt: adg, _std)]
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	294 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	295 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_acct_mgmt")]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	296 #[doc = stdlinks!(3 pam_acct_mgmt)]
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	297 fn account_management(&mut self, flags: Flags) -> Result<()>;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	298
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	299 /// Changes the authentication token.
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	300 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	301 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	302 #[doc = linklist!(pam_chauthtok: adg, _std)]
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	303 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	304 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_chauthtok")]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	305 #[doc = stdlinks!(3 pam_chauthtok)]
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	306 fn change_authtok(&mut self, flags: Flags) -> Result<()>;
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	307 }
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	308
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	309 /// Functionality of a PAM handle that can be expected by a PAM module.
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	310 ///
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	311 /// If you are not writing a PAM module (e.g., you are writing an application),
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	312 /// you should not use any of the functionality exposed by this trait.
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	313 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	314 /// Like [`PamShared`], this is intended to allow creating mock implementations
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	315 /// of PAM for testing PAM modules.
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	316 pub trait PamHandleModule: Conversation + PamShared {
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	317 /// Retrieves the authentication token from the user.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	318 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	319 /// This should only be used by authentication and password-change
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	320 /// PAM modules.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	321 ///
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	322 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	323 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	324 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	325 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	326 /// # Example
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	327 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	328 /// ```no_run
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	329 /// # use nonstick::handle::PamHandleModule;
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	330 /// # fn _doc(handle: &mut impl PamHandleModule) -> Result<(), Box<dyn std::error::Error>> {
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	331 /// // Get the user's password using the default prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	332 /// let pass = handle.authtok(None)?;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	333 /// // Get the user's password using a custom prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	334 /// let pass = handle.authtok(Some("Reveal your secrets!"))?;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	335 /// Ok(())
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	336 /// # }
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	337 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	338 #[doc = man7!(3 pam_get_authtok)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	339 #[doc = manbsd!(3 pam_get_authtok)]
95 51c9d7e8261a Return owned strings rather than borrowed strings. Paul Fisher <paul@pfish.zone> parents: 94 diff changeset	340 fn authtok(&mut self, prompt: Option<&str>) -> Result<String>;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	341
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	342 /// Retrieves the user's old authentication token when changing passwords.
a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	343 ///
a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	344 ///
a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	345 fn old_authtok(&mut self, prompt: Option<&str>) -> Result<String>;
a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	346
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	347 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	348 /// Gets the user's authentication token (e.g., password).
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	349 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	350 /// This is normally set automatically by PAM when calling
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	351 /// [`authtok`](Self::authtok), but can be set explicitly.
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	352 ///
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	353 /// Like `authtok`, this should only ever be called
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	354 /// by authentication and password-change PAM modules.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	355 get = authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	356 item = "PAM_AUTHTOK",
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	357 see = Self::authtok
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	358 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	359
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	360 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	361 /// Gets the user's old authentication token when changing passwords.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	362 ///
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	363 /// This is normally set automatically by PAM when calling
a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	364 /// [`old_authtok`](Self::old_authtok), but can be set explicitly.
a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	365 ///
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	366 /// This should only ever be called by password-change PAM modules.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	367 get = old_authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	368 item = "PAM_OLDAUTHTOK",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	369 see = PamShared::set_old_authtok_item
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	370 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	371 }

Mercurial > crates > nonstick

annotate src/handle.rs @ 141:a508a69c068a