crates/nonstick: src/handle.rs annotate

annotate src/handle.rs @ 116:a12706e42c9d

Logging, macros, and building: - Changes logging API to accept the `Location` of the log statement. Fixes OpenPAM implementation. - Stops publicly exporting doc macros. - Uses dlopen to detect the PAM library rather than header jankery.

author	Paul Fisher <paul@pfish.zone>
date	Sun, 29 Jun 2025 18:27:51 -0400
parents	dfcd96a74ac4
children

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
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	320 /// PAM modules. This is an extension provided by
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	321 /// both Linux-PAM and OpenPAM.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	322 ///
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	323 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	324 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	325 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	326 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	327 /// # Example
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	328 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	329 /// ```no_run
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	330 /// # use nonstick::handle::PamHandleModule;
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	331 /// # 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	332 /// // Get the user's password using the default prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	333 /// let pass = handle.authtok(None)?;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	334 /// // Get the user's password using a custom prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	335 /// let pass = handle.authtok(Some("Reveal your secrets!"))?;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	336 /// Ok(())
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	337 /// # }
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	338 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	339 #[doc = man7!(3 pam_get_authtok)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	340 #[doc = manbsd!(3 pam_get_authtok)]
95 51c9d7e8261a Return owned strings rather than borrowed strings. Paul Fisher <paul@pfish.zone> parents: 94 diff changeset	341 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	342
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	343 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	344 /// 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	345 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	346 /// This is normally set automatically by PAM when calling
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	347 /// [`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	348 ///
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	349 /// 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	350 /// by authentication and password-change PAM modules.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	351 get = authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	352 item = "PAM_AUTHTOK",
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	353 see = Self::authtok
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	354 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	355
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	356 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	357 /// 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	358 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	359 /// 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	360 get = old_authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	361 item = "PAM_OLDAUTHTOK",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	362 see = PamShared::set_old_authtok_item
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	363 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	364
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	365 /*
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	366 TODO: Re-enable this at some point.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	367 /// Gets some pointer, identified by `key`, that has been set previously
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	368 /// using [`set_data`](Self::set_data).
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	369 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	370 /// The data, if present, is still owned by the current PAM session.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	371 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	372 /// See the [`pam_get_data` manual page][man]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	373 /// or [`pam_get_data` in the Module Writer's Guide][mwg].
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	374 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	375 /// # Safety
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	376 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	377 /// The data stored under the provided key must be of type `T`,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	378 /// otherwise you'll get back a completely invalid `&T`
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	379 /// and further behavior is undefined.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	380 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	381 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_data.3.html
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	382 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_data
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	383 unsafe fn get_data<T>(&mut self, key: &str) -> Result<Option<&T>>;
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	384
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	385 /// Stores a pointer that can be retrieved later with [`get_data`](Self::get_data).
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	386 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	387 /// This data is accessible to this module and other PAM modules
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	388 /// (using the provided `key`), but is not accessible to the application.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	389 /// The PAM session takes ownership of the data, and it will be dropped
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	390 /// when the session ends.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	391 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	392 /// See the [`pam_set_data` manual page][man]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	393 /// or [`pam_set_data` in the Module Writer's Guide][mwg].
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	394 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	395 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_set_data.3.html
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	396 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_set_data
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	397 fn set_data<T>(&mut self, key: &str, data: Box<T>) -> Result<()>;
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	398 */
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	399 }

Mercurial > crates > nonstick

annotate src/handle.rs @ 116:a12706e42c9d