crates/nonstick: src/handle.rs annotate

annotate src/handle.rs @ 153:3036f2e6a022

Add module-specific data support. This adds support for a safe form of `pam_get_data` and `pam_set_data`, where data is (as best as humanly possible) type-safe and restricted to only the module where it was created.

author	Paul Fisher <paul@pfish.zone>
date	Tue, 08 Jul 2025 00:31:54 -0400
parents	1bc52025156b
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
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	3 use crate::_doc::{guide, linklist, man7, manbsd, stdlinks};
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	4 use crate::constants::{Flags, Result};
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	5 use crate::conv::Conversation;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	6 use crate::environ::{EnvironMap, EnvironMapMut};
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	7 use crate::items::{getter, Items, ItemsMut};
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	8 use crate::logging::{Level, Location};
143 ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul. Paul Fisher <paul@pfish.zone> parents: 141 diff changeset	9 use std::ffi::{OsStr, OsString};
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	10
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	11 /// 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	12 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	13 /// 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	14 /// to both applications and modules.
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	15 ///
144 56b559b7ecea Big rename: separate concepts of Transaction from Handle. Paul Fisher <paul@pfish.zone> parents: 143 diff changeset	16 /// You probably want [`LibPamTransaction`](crate::libpam::LibPamTransaction).
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	17 /// 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	18 /// to test PAM modules and applications.
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	19 pub trait PamShared {
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	20 /// 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	21 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	22 /// 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	23 /// like [`error!`](crate::error!),
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	24 /// [`warn!`](crate::warn!),
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	25 /// [`info!`](crate::info!),
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	26 /// or [`debug!`](crate::debug!).
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	27 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	28 /// 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	29 /// 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	30 /// [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	31 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	32 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	33 ///
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	34 /// ```no_run
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	35 /// # use nonstick::PamShared;
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	36 /// use nonstick::logging::Level;
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	37 /// use nonstick::location;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	38 /// # 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	39 /// # let delay_ms = 100;
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	40 /// # let url = "https://zombo.com";
5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	41 /// // 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	42 /// 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	43 /// 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	44 /// 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	45 /// 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	46 /// // 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	47 /// 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	48 /// # }
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 91 diff changeset	49 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	50 #[doc = man7!(3 pam_syslog)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	51 #[doc = manbsd!(3 openpam_log)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	52 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	53
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	54 /// 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	55 ///
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	56 /// 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	57 /// 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	58 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	59 /// 1. The prompt string passed to this function.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	60 /// 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	61 /// 3. The default prompt, `login: `.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	62 ///
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	63 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	64 #[doc = linklist!(pam_get_user: mwg, _std)]
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	65 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	66 /// # Example
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	67 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	68 /// ```no_run
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	69 /// # use nonstick::PamShared;
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	70 /// # 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	71 /// // Get the username using the default prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	72 /// let user = handle.username(None)?;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	73 /// // Get the username using a custom prompt.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	74 /// // If this were actually called right after the above,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	75 /// // both user and user_2 would have the same value.
143 ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul. Paul Fisher <paul@pfish.zone> parents: 141 diff changeset	76 /// let user_2 = handle.username(Some("who ARE you even???".as_ref()))?;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	77 /// # Ok(())
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	78 /// # }
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	79 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	80 #[doc = stdlinks!(3 pam_get_user)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	81 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
143 ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul. Paul Fisher <paul@pfish.zone> parents: 141 diff changeset	82 fn username(&mut self, prompt: Option<&OsStr>) -> Result<OsString>;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	83
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	84 /// The contents of the environment to set for the logged-in user.
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	85 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	86 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	87 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	88 #[doc = linklist!(pam_getenv: adg, mwg, _std)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	89 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	90 #[doc = stdlinks!(3 pam_getenv)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	91 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_getenv")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	92 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#adg-pam_getenv")]
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	93 fn environ(&self) -> impl EnvironMap;
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	94
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	95 /// A writable map of the environment to set for the logged-in user.
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	96 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	97 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	98 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	99 #[doc = linklist!(pam_putenv: adg, mwg, _std)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	100 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	101 #[doc = stdlinks!(3 pam_putenv)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	102 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_putenv")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	103 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#adg-pam_putenv")]
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	104 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	105
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	106 /// Gets Items, data shared by PAM, the application, and modules.
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	107 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	108 /// Certain Items should not be accessed by a PAM application;
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	109 /// those are available directly on [`ModuleClient`] for use
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	110 /// by PAM modules only.
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	111 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	112 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	113 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	114 #[doc = linklist!(pam_get_item: mwg, adg, _std)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	115 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	116 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_get_item")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	117 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_item")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	118 #[doc = stdlinks!(3 pam_get_item)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	119 fn items(&self) -> impl Items;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	120
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	121 /// Read-write access to PAM Items.
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	122 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	123 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	124 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	125 #[doc = linklist!(pam_set_item: mwg, adg, _std)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	126 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	127 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	128 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	129 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	130 fn items_mut(&mut self) -> impl ItemsMut;
69 8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	131 }
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	132
69 8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	133 /// 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	134 ///
8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	135 /// 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	136 /// 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	137 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	138 /// 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	139 /// of PAM for testing PAM applications.
144 56b559b7ecea Big rename: separate concepts of Transaction from Handle. Paul Fisher <paul@pfish.zone> parents: 143 diff changeset	140 pub trait Transaction: PamShared {
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	141 /// 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	142 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	143 /// 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	144 /// 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	145 /// this will return an `Ok(())` [`Result`].
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	146 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	147 /// 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	148 /// 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	149 /// any PAM application call.
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	150 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	151 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	152 #[doc = linklist!(pam_authenticate: adg, _std)]
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	153 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	154 #[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	155 #[doc = stdlinks!(3 pam_authenticate)]
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	156 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	157
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	158 /// 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	159 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	160 /// 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	161 /// 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	162 /// 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	163 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	164 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	165 #[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	166 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	167 #[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	168 #[doc = stdlinks!(3 pam_acct_mgmt)]
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	169 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	170
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	171 /// Changes the authentication token.
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	172 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	173 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	174 #[doc = linklist!(pam_chauthtok: adg, _std)]
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	175 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	176 #[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	177 #[doc = stdlinks!(3 pam_chauthtok)]
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	178 fn change_authtok(&mut self, flags: Flags) -> Result<()>;
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	179 }
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	180
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	181 /// 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	182 ///
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	183 /// 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	184 /// 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	185 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	186 /// 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	187 /// of PAM for testing PAM modules.
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	188 pub trait ModuleClient: Conversation + PamShared {
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	189 /// Retrieves the authentication token from the user.
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 /// This should only be used by authentication and password-change
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	192 /// PAM modules.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	193 ///
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	194 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	195 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	196 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
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 /// # Example
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	199 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	200 /// ```no_run
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	201 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	202 /// # fn _doc(handle: &mut impl ModuleClient) -> Result<(), Box<dyn std::error::Error>> {
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	203 /// // Get the user's password using the default prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	204 /// let pass = handle.authtok(None)?;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	205 /// // Get the user's password using a custom prompt.
143 ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul. Paul Fisher <paul@pfish.zone> parents: 141 diff changeset	206 /// let pass = handle.authtok(Some("Reveal your secrets!".as_ref()))?;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	207 /// Ok(())
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	208 /// # }
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	209 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	210 #[doc = man7!(3 pam_get_authtok)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	211 #[doc = manbsd!(3 pam_get_authtok)]
143 ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul. Paul Fisher <paul@pfish.zone> parents: 141 diff changeset	212 fn authtok(&mut self, prompt: Option<&OsStr>) -> Result<OsString>;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	213
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	214 /// Retrieves the user's old authentication token when changing passwords.
a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	215 ///
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	216 /// This should only be used by a password-change module.
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	217 ///
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	218 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	219 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	220 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	221 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	222 /// # Example
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	223 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	224 /// ```no_run
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	225 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	226 /// # fn _doc(handle: &mut impl ModuleClient) -> Result<(), Box<dyn std::error::Error>> {
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	227 /// // Get the user's password using the default prompt.
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	228 /// let pass = handle.old_authtok(None)?;
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	229 /// // Get the user's password using a custom prompt.
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	230 /// let pass = handle.old_authtok(Some("Reveal your secrets!".as_ref()))?;
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	231 /// Ok(())
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	232 /// # }
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	233 /// ```
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	234 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	235 #[doc = stdlinks!(3 pam_get_authtok)]
143 ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul. Paul Fisher <paul@pfish.zone> parents: 141 diff changeset	236 fn old_authtok(&mut self, prompt: Option<&OsStr>) -> Result<OsString>;
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	237
153 3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	238 /// Gets an item of module-specific data stored over the transaction.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	239 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	240 /// This gives you a reference to the data that was earlier set with
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	241 /// [`Self::set_module_data`]. If not present, you get `None`.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	242 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	243 /// Data is in a module-specific, type-specific namespace.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	244 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	245 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	246 /// # use nonstick::ModuleClient;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	247 /// # use std::path::PathBuf;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	248 /// # fn test(client: &impl ModuleClient) {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	249 /// // These two can coexist and do not overlap.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	250 /// let str_data: Option<&String> = client.get_module_data("the_key");
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	251 /// let num_data: Option<&u64> = client.get_module_data("the_key");
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	252 /// // ...
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	253 /// let nothing_data: Option<&PathBuf> = client.get_module_data("this does not exist");
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	254 /// # }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	255 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	256 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	257 /// # References
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	258 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	259 #[doc = linklist!(pam_get_data: mwg, _std)]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	260 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	261 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_data")]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	262 #[doc = stdlinks!(3 pam_get_data)]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	263
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	264 fn get_module_data<T: 'static>(&self, key: &str) -> Option<&T>;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	265
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	266 /// Sets module-specific data.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	267 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	268 /// A PAM module may need to store data across multiple invocations within
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	269 /// the same PAM transaction. For instance, a module that stores credentials
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	270 /// would need to know where those credentials were stored in order to
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	271 /// update or destroy them later. Also see [`Self::get_module_data`].
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	272 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	273 /// Module-specific data gives a module a way to store such data.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	274 /// Data are stored in a module-specific, type-specific namespace.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	275 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	276 /// PAM takes ownership of the data passed in. See the Cleanup section
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	277 /// below for details on how cleanup is handled.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	278 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	279 /// # Examples
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	280 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	281 /// Each type of data is in a separate namespace:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	282 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	283 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	284 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	285 /// # fn test(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	286 /// client.set_module_data("count", 999i32)?;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	287 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	288 /// let count_int: Option<&i32> = client.get_module_data("count");
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	289 /// // count_int = Some(&999i32)
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	290 /// let count_string: Option<&String> = client.get_module_data("count");
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	291 /// // count_string = None
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	292 /// # Ok(())
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	293 /// # }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	294 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	295 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	296 /// Data persist across invocations of the same module:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	297 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	298 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	299 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	300 /// // In a pam_authenticate call, this function is called:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	301 /// fn authenticate(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	302 /// client.set_module_data::<u64>("TOKEN_ID", 0x0fa1afe10000beef)?;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	303 /// Ok(())
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	304 /// }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	305 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	306 /// // Later, in a pam_session_start call:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	307 /// fn start_session(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	308 /// match client.get_module_data::<u64>("TOKEN_ID") {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	309 /// Some(&tid) => {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	310 /// // This will execute and tid will be 0x0fa1afe10000beef.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	311 /// },
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	312 /// None => { /* This will not execute. */ },
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	313 /// }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	314 /// Ok(())
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	315 /// }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	316 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	317 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	318 /// Each module has its own set of data:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	319 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	320 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	321 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	322 /// // This function is called somewhere in pam_module_a.so.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	323 /// fn in_pam_module_a(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	324 /// client.set_module_data("value", String::from("pam_module_a data"))?;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	325 /// Ok(())
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	326 /// }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	327 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	328 /// // This function is called later in pam_module_b.so.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	329 /// fn in_pam_module_b(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	330 /// match client.get_module_data::<String>("value") {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	331 /// Some(value) => {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	332 /// // This will match, because pam_module_a's data
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	333 /// // is completely unrelated to pam_module_b's data.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	334 /// },
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	335 /// None => {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	336 /// // This branch will execute.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	337 /// },
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	338 /// }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	339 /// // ...
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	340 /// # Ok(())
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	341 /// }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	342 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	343 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	344 /// # Cleanup
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	345 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	346 /// PAM modules should be careful about cleaning up data outside their own
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	347 /// address space, because PAM applications may `fork()`:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	348 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	349 /// ```plain
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	350 /// ┃ let tx = start_pam_transaction();
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	351 /// ┃
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	352 /// ┃ tx.authenticate();
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	353 /// ┃ │ // PAM calls into your module where you set data:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	354 /// ┃ │ handle.set_module_data("key", the_data);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	355 /// ┃
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	356 /// ┃ fork();
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	357 /// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━┓
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	358 /// Parent process Child process
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	359 /// ┃ wait(child); ┃ setuid(user_to_login);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	360 /// ┃ ┆ ┃ // ... do other stuff ...
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	361 /// ┃ ┆ ┃ drop(tx);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	362 /// ┃ ┆ ┃ │ // PAM cleans up your data.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	363 /// ┃ ┆ ┃ │ drop(the_data);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	364 /// ┃ ┆ ┗ exec(user's shell)
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	365 /// ┃ ┆ ┃ // user does stuff over their session
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	366 /// ┃ ┆ ┃ // ...
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	367 /// ┃ ┆ X
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	368 /// ┃
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	369 /// ┃ drop(tx);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	370 /// ┃ │ // Parent PAM cleans up your data.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	371 /// ┃ │ drop(the_data); // Called again, but in this process instead!
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	372 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	373 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	374 /// While LibPAM offers a way to customize the action taken on cleanup,
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	375 /// we do not (yet) offer this.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	376 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	377 /// # References
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	378 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	379 #[doc = linklist!(pam_set_data: mwg, _std)]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	380 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	381 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_data")]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	382 #[doc = stdlinks!(3 pam_set_data)]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	383 fn set_module_data<T: 'static>(&mut self, key: &str, data: T) -> Result<()>;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	384
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	385 getter!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	386 /// 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	387 ///
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	388 /// This is normally set automatically by PAM through [`Self::authtok`],
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	389 /// but this will get its value (if set) without prompting the user.
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	390 ///
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	391 /// 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	392 /// by authentication and password-change PAM modules.
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	393 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	394 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	395 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	396 #[doc = linklist!(pam_set_item: mwg, adg, _std)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	397 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	398 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	399 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	400 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	401 authtok_item("PAM_AUTHTOK", see = Self::authtok)
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	402 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	403
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	404 getter!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	405 /// 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	406 ///
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	407 /// This is normally set automatically by PAM through
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	408 /// [`Self::old_authtok`], but this will get its value (if set)
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	409 /// without prompting the user.
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	410 ///
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	411 /// This should only ever be called by password-change PAM modules.
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	412 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	413 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	414 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	415 #[doc = linklist!(pam_set_item: mwg, adg, _std)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	416 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	417 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	418 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	419 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	420 old_authtok_item("PAM_OLDAUTHTOK", see = ItemsMut::set_old_authtok)
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	421 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	422 }

Mercurial > crates > nonstick

annotate src/handle.rs @ 153:3036f2e6a022