crates/nonstick: src/handle.rs annotate

annotate src/handle.rs @ 98:b87100c5eed4

Start on environment variables, and make pointers nicer. This starts work on the PAM environment handling, and in so doing, introduces the CHeapBox and CHeapString structs. These are analogous to Box and CString, but they're located on the C heap rather than being Rust-managed memory. This is because environment variables deal with even more pointers and it turns out we can lose a lot of manual freeing using homemade smart pointers.

author	Paul Fisher <paul@pfish.zone>
date	Tue, 24 Jun 2025 04:25:25 -0400
parents	efe2f5f8b5b2
children	3f11b8d30f63

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};
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	6 use crate::logging::Level;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	7
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	8 macro_rules! trait_item {
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	9 ($(#[$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	10 $(#[$md])*
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	11 #[doc = ""]
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	12 #[doc = concat!("Gets the `", $item, "` of the PAM handle.")]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	13 $(
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	14 #[doc = concat!("See [`", stringify!($see), "`].")]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	15 )?
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	16 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	17 /// 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	18 /// 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	19 /// 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	20 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	21 /// See the [`pam_get_item`][man] manual page,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	22 /// [`pam_get_item` in the Module Writers' Guide][mwg], or
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	23 /// [`pam_get_item` in the Application Developers' Guide][adg].
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	24 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	25 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_item.3.html
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	26 /// [adg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/adg-interface-by-app-expected.html#adg-pam_get_item
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	27 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_item
95 51c9d7e8261a Return owned strings rather than borrowed strings. Paul Fisher <paul@pfish.zone> parents: 94 diff changeset	28 fn $getter(&self) -> Result<Option<String>>;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	29 };
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	30 ($(#[$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	31 $(#[$md])*
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	32 #[doc = concat!("Sets the `", $item, "` from the PAM handle.")]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	33 $(
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	34 #[doc = concat!("See [`", stringify!($see), "`].")]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	35 )?
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	36 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	37 /// 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	38 /// 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	39 /// a `ConversationError`.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	40 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	41 /// See the [`pam_set_item`][man] manual page,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	42 /// [`pam_set_item` in the Module Writers' Guide][mwg], or
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	43 /// [`pam_set_item` in the Application Developers' Guide][adg].
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	44 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	45 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_set_item.3.html
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	46 /// [adg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/adg-interface-by-app-expected.html#adg-pam_set_item
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	47 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_set_item
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	48 fn $setter(&mut self, value: Option<&str>) -> Result<()>;
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	49 };
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	50 }
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	51
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	52 /// 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	53 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	54 /// 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	55 /// to both applications and modules.
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	56 ///
75 c30811b4afae rename pam_ffi submodule to libpam. Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	57 /// 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	58 /// 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	59 /// to test PAM modules and applications.
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	60 pub trait PamShared {
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	61 /// 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	62 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	63 /// You probably want to use one of the logging macros,
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	64 /// like [`error!`], [`warning!`], [`info!`], or [`debug!`].
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	65 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	66 /// In most PAM implementations, this will go to syslog.
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	67 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	68 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	69 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	70 /// ```no_run
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	71 /// # use nonstick::{PamShared};
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	72 /// # use nonstick::logging::Level;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	73 /// # 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	74 /// # let delay_ms = 100;
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	75 /// # let url = "https://zombo.com";
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	76 /// // 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	77 /// 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	78 /// 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	79 /// 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	80 /// 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	81 /// // But if you really want to, you can call this yourself:
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	82 /// pam_hdl.log(Level::Warning, "this is unnecessarily verbose");
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	83 /// # }
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	84 /// ```
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	85 fn log(&self, level: Level, entry: &str);
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	86
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	87 /// 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	88 ///
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	89 /// 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	90 /// 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	91 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	92 /// 1. The prompt string passed to this function.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	93 /// 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	94 /// 3. The default prompt, `login: `.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	95 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	96 /// See the [`pam_get_user` manual page][man]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	97 /// or [`pam_get_user` in the Module Writer's Guide][mwg].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	98 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	99 /// # Example
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	100 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	101 /// ```no_run
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	102 /// # use nonstick::PamShared;
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	103 /// # 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	104 /// // Get the username using the default prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	105 /// let user = handle.username(None)?;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	106 /// // Get the username using a custom prompt.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	107 /// // If this were actually called right after the above,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	108 /// // 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	109 /// 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	110 /// # Ok(())
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	111 /// # }
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	112 /// ```
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	113 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	114 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_user.3.html
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	115 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/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	116 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	117
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	118 /// 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	119 fn environ(&self) -> impl EnvironMap;
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	120
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	121 /// A writable version of the environment.
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	122 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	123
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	124 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	125 /// 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	126 ///
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	127 /// 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	128 /// 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	129 /// 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	130 /// 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	131 /// 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	132 get = user_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	133 item = "PAM_USER",
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	134 see = Self::username
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	135 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	136 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	137 /// 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	138 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	139 /// Usually this will be set during the course of
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	140 /// 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	141 /// or change it during the PAM process.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	142 set = set_user_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	143 item = "PAM_USER",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	144 see = Self::user_item
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	145 );
44 50371046c61a Add support for pam_get_authtok and minor cleanups. Paul Fisher <paul@pfish.zone> parents: 34 diff changeset	146
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	147 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	148 /// 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	149 /// to perform authentication.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	150 get = service,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	151 item = "PAM_SERVICE"
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	152 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	153 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	154 /// 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	155 /// to perform authentication. 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	156 set = set_service,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	157 item = "PAM_SERVICE",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	158 see = Self::service
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	159 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	160
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	161 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	162 /// 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	163 /// 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	164 get = user_prompt,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	165 item = "PAM_USER_PROMPT"
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	166 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	167 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	168 /// 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	169 set = set_user_prompt,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	170 item = "PAM_USER_PROMPT",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	171 see = Self::user_prompt
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	172 );
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	173
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	174 trait_item!(
91 039aae9a01f7 Improve documentation on TTY functions. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	175 /// 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	176 ///
91 039aae9a01f7 Improve documentation on TTY functions. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	177 /// 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	178 /// 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	179 /// 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	180 get = tty_name,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	181 item = "PAM_TTY"
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	182 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	183 trait_item!(
91 039aae9a01f7 Improve documentation on TTY functions. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	184 /// 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	185 set = set_tty_name,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	186 item = "PAM_TTY",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	187 see = Self::tty_name
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	188 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	189
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	190 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	191 /// 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	192 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	193 /// 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	194 /// Also see [`remote_host`](Self::remote_host).
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	195 get = remote_user,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	196 item = "PAM_RUSER"
72 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 /// 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	200 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	201 /// This is usually set by the application before making calls
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	202 /// into a PAM session. (TODO: check this!)
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	203 set = set_remote_user,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	204 item = "PAM_RUSER"
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	205 );
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	206
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	207 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	208 /// 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	209 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	210 /// 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	211 /// 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	212 /// 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	213 /// with `remote_user@remote_host`.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	214 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	215 /// 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	216 /// is originating from."
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	217 get = remote_host,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	218 item = "PAM_RHOST"
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	219 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	220 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	221 /// 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	222 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	223 /// This is usually set by the application before making calls
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	224 /// into a PAM session. (TODO: check this!)
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	225 set = set_remote_host,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	226 item = "PAM_RHOST",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	227 see = Self::remote_host
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	228 );
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 /// 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	232 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	233 /// This is usually set automatically when
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	234 /// [`authtok`](PamHandleModule::authtok) is called,
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	235 /// but can be manually set.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	236 set = set_authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	237 item = "PAM_AUTHTOK",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	238 see = PamHandleModule::authtok_item
72 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
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	241 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	242 /// Sets 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	243 //
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	244 /// This is usually set automatically by PAM.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	245 set = set_old_authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	246 item = "PAM_OLDAUTHTOK",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	247 see = PamHandleModule::old_authtok_item
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	248 );
69 8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	249 }
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	250
69 8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	251 /// 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	252 ///
8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	253 /// 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	254 /// 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	255 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	256 /// 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	257 /// 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	258 pub trait PamHandleApplication: PamShared {
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	259 /// Starts the authentication process for the user.
efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	260 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	261
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	262 /// Does "account management".
efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	263 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	264
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	265 /// Changes the authentication token.
efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	266 fn change_authtok(&mut self, flags: Flags) -> Result<()>;
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	267 }
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	268
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	269 /// 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	270 ///
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	271 /// 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	272 /// 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	273 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	274 /// 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	275 /// 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	276 pub trait PamHandleModule: Conversation + PamShared {
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	277 /// Retrieves the authentication token from the user.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	278 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	279 /// This should only be used by authentication and password-change
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	280 /// PAM modules.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	281 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	282 /// See the [`pam_get_authtok` manual page][man]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	283 /// or [`pam_get_item` in the Module Writer's Guide][mwg].
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	284 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	285 /// # Example
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	286 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	287 /// ```no_run
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	288 /// # use nonstick::handle::PamHandleModule;
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	289 /// # 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	290 /// // Get the user's password using the default prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	291 /// let pass = handle.authtok(None)?;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	292 /// // Get the user's password using a custom prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	293 /// let pass = handle.authtok(Some("Reveal your secrets!"))?;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	294 /// Ok(())
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	295 /// # }
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	296 /// ```
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	297 ///
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	298 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_authtok.3.html
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	299 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_item
95 51c9d7e8261a Return owned strings rather than borrowed strings. Paul Fisher <paul@pfish.zone> parents: 94 diff changeset	300 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	301
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	302 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	303 /// 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	304 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	305 /// This is normally set automatically by PAM when calling
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	306 /// [`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	307 ///
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	308 /// 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	309 /// by authentication and password-change PAM modules.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	310 get = authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	311 item = "PAM_AUTHTOK",
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	312 see = Self::authtok
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	313 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	314
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	315 trait_item!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	316 /// 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	317 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	318 /// 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	319 get = old_authtok_item,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	320 item = "PAM_OLDAUTHTOK",
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	321 see = PamShared::set_old_authtok_item
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	322 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	323
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	324 /*
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	325 TODO: Re-enable this at some point.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	326 /// 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	327 /// using [`set_data`](Self::set_data).
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 /// 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	330 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	331 /// See the [`pam_get_data` manual page][man]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	332 /// 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	333 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	334 /// # Safety
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	335 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	336 /// 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	337 /// otherwise you'll get back a completely invalid `&T`
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	338 /// and further behavior is undefined.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	339 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	340 /// [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	341 /// [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	342 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	343
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	344 /// 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	345 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	346 /// 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	347 /// (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	348 /// 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	349 /// when the session ends.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	350 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	351 /// See the [`pam_set_data` manual page][man]
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	352 /// 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	353 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	354 /// [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	355 /// [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	356 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	357 */
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	358 }

Mercurial > crates > nonstick

annotate src/handle.rs @ 98:b87100c5eed4