crates/nonstick: src/handle.rs annotate

annotate src/handle.rs @ 171:e27c5c667a5a

Create full new types for return code and flags, separate end to end. This plumbs the ReturnCode and RawFlags types through the places where we call into or are called from PAM. Also adds Sun documentation to the project.

author	Paul Fisher <paul@pfish.zone>
date	Fri, 25 Jul 2025 20:52:14 -0400
parents	77470e45e397
children	9e4ce1631bd3

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};
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 159 diff changeset	4 use crate::constants::{AuthnFlags, AuthtokFlags, 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};
159 634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM. Paul Fisher <paul@pfish.zone> parents: 157 diff changeset	8 use crate::logging::Logger;
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.
159 634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM. Paul Fisher <paul@pfish.zone> parents: 157 diff changeset	19 pub trait PamShared: Logger {
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	20 /// 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	21 ///
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	22 /// 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	23 /// 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	24 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	25 /// 1. The prompt string passed to this function.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	26 /// 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	27 /// 3. The default prompt, `login: `.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	28 ///
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	29 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	30 #[doc = linklist!(pam_get_user: mwg, _std)]
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	31 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	32 /// # Example
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	33 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	34 /// ```no_run
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	35 /// # use nonstick::PamShared;
ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	36 /// # 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	37 /// // Get the username using the default prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	38 /// let user = handle.username(None)?;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	39 /// // Get the username using a custom prompt.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	40 /// // If this were actually called right after the above,
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	41 /// // 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	42 /// 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	43 /// # Ok(())
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	44 /// # }
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	45 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	46 #[doc = stdlinks!(3 pam_get_user)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	47 #[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	48 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	49
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	50 /// 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	51 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	52 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	53 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	54 #[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	55 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	56 #[doc = stdlinks!(3 pam_getenv)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	57 #[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	58 #[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	59 fn environ(&self) -> impl EnvironMap;
b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	60
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	61 /// 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	62 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	63 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	64 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	65 #[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	66 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	67 #[doc = stdlinks!(3 pam_putenv)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	68 #[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	69 #[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	70 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	71
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	72 /// 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	73 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	74 /// 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	75 /// 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	76 /// by PAM modules only.
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	77 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	78 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	79 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	80 #[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	81 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	82 #[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	83 #[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	84 #[doc = stdlinks!(3 pam_get_item)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	85 fn items(&self) -> impl Items;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	86
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	87 /// Read-write access to PAM Items.
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	88 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	89 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	90 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	91 #[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	92 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	93 #[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	94 #[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	95 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	96 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	97 }
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	98
69 8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	99 /// 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	100 ///
8f3ae0c7ab92 Rework conversation data types and make safe wrappers. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	101 /// 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	102 /// 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	103 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	104 /// 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	105 /// 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	106 pub trait Transaction: PamShared {
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	107 /// 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	108 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	109 /// 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	110 /// 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	111 /// this will return an `Ok(())` [`Result`].
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	112 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	113 /// 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	114 /// 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	115 /// any PAM application call.
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	116 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	117 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	118 #[doc = linklist!(pam_authenticate: adg, _std)]
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	119 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	120 #[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	121 #[doc = stdlinks!(3 pam_authenticate)]
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 159 diff changeset	122 fn authenticate(&mut self, flags: AuthnFlags) -> Result<()>;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	123
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	124 /// 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	125 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	126 /// 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	127 /// 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	128 /// 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	129 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	130 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	131 #[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	132 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	133 #[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	134 #[doc = stdlinks!(3 pam_acct_mgmt)]
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 159 diff changeset	135 fn account_management(&mut self, flags: AuthnFlags) -> Result<()>;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 97 diff changeset	136
97 efe2f5f8b5b2 Implement "stateless" application-side PAM calls. Paul Fisher <paul@pfish.zone> parents: 95 diff changeset	137 /// Changes the authentication token.
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	138 ///
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	139 /// # References
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	140 #[doc = linklist!(pam_chauthtok: adg, _std)]
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	141 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	142 #[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	143 #[doc = stdlinks!(3 pam_chauthtok)]
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 159 diff changeset	144 fn change_authtok(&mut self, flags: AuthtokFlags) -> Result<()>;
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	145 }
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	146
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	147 /// 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	148 ///
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	149 /// 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	150 /// 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	151 ///
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	152 /// 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	153 /// 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	154 pub trait ModuleClient: Conversation + PamShared {
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	155 /// Retrieves the authentication token from the user.
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	156 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	157 /// 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	158 /// PAM modules.
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	159 ///
169 77470e45e397 Set up stuff to work the way Sun expects it to. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	160 /// With Sun's PAM implementation, this works a little bit differently
77470e45e397 Set up stuff to work the way Sun expects it to. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	161 /// than it does everywhere else. Sun's PAM provides for password input
77470e45e397 Set up stuff to work the way Sun expects it to. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	162 /// exclusively though module stacking with the
77470e45e397 Set up stuff to work the way Sun expects it to. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	163 /// [`pam_authtok_get` module][pam_authtok_get]. On Sun, this function
77470e45e397 Set up stuff to work the way Sun expects it to. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	164 /// is exactly equivalent to [`Self::authtok_item`], in that it only
77470e45e397 Set up stuff to work the way Sun expects it to. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	165 /// retrieves the existing item.
77470e45e397 Set up stuff to work the way Sun expects it to. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	166 ///
103 dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	167 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation Paul Fisher <paul@pfish.zone> parents: 100 diff changeset	168 ///
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	169 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	170 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	171 /// # Example
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	172 ///
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	173 /// ```no_run
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	174 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	175 /// # 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	176 /// // Get the user's password using the default prompt.
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	177 /// let pass = handle.authtok(None)?;
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	178 /// // 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	179 /// 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	180 /// Ok(())
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	181 /// # }
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	182 /// ```
116 a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	183 #[doc = man7!(3 pam_get_authtok)]
a12706e42c9d Logging, macros, and building: Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	184 #[doc = manbsd!(3 pam_get_authtok)]
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 169 diff changeset	185 /// [pam_authtok_get]: https://smartos.org/man/7/pam_authtok_get
143 ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul. Paul Fisher <paul@pfish.zone> parents: 141 diff changeset	186 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	187
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	188 /// 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	189 ///
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	190 /// 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	191 ///
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	192 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	193 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	194 #[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	195 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	196 /// # Example
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	197 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	198 /// ```no_run
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	199 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	200 /// # 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	201 /// // 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	202 /// let pass = handle.old_authtok(None)?;
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	203 /// // 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	204 /// 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	205 /// Ok(())
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	206 /// # }
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	207 /// ```
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	208 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	209 #[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	210 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	211
153 3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	212 /// 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	213 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	214 /// 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	215 /// [`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	216 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	217 /// Data is in a module-specific, type-specific namespace.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	218 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	219 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	220 /// # use nonstick::ModuleClient;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	221 /// # use std::path::PathBuf;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	222 /// # fn test(client: &impl ModuleClient) {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	223 /// // These two can coexist and do not overlap.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	224 /// 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	225 /// 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	226 /// // ...
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	227 /// 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	228 /// # }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	229 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	230 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	231 /// # References
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	232 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	233 #[doc = linklist!(pam_get_data: mwg, _std)]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	234 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	235 #[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	236 #[doc = stdlinks!(3 pam_get_data)]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	237
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	238 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	239
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	240 /// Sets module-specific data.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	241 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	242 /// 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	243 /// 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	244 /// 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	245 /// 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	246 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	247 /// 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	248 /// 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	249 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	250 /// 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	251 /// below for details on how cleanup is handled.
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 /// # Examples
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 /// Each type of data is in a separate namespace:
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 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	258 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	259 /// # fn test(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	260 /// client.set_module_data("count", 999i32)?;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	261 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	262 /// 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	263 /// // count_int = Some(&999i32)
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	264 /// 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	265 /// // count_string = None
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	266 /// # Ok(())
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 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	269 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	270 /// Data persist across invocations of the same module:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	271 ///
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 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	274 /// // In a pam_authenticate call, this function is called:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	275 /// fn authenticate(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	276 /// client.set_module_data::<u64>("TOKEN_ID", 0x0fa1afe10000beef)?;
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	277 /// Ok(())
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 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	280 /// // Later, in a pam_session_start call:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	281 /// fn start_session(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	282 /// match client.get_module_data::<u64>("TOKEN_ID") {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	283 /// Some(&tid) => {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	284 /// // This will execute and tid will be 0x0fa1afe10000beef.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	285 /// },
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	286 /// None => { /* This will not execute. */ },
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 /// Ok(())
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	289 /// }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	290 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	291 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	292 /// Each module has its own set of data:
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 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	296 /// // 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	297 /// 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	298 /// 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	299 /// Ok(())
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	300 /// }
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	301 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	302 /// // 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	303 /// 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	304 /// match client.get_module_data::<String>("value") {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	305 /// Some(value) => {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	306 /// // This will match, because pam_module_a's data
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	307 /// // is completely unrelated to pam_module_b's data.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	308 /// },
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	309 /// None => {
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	310 /// // This branch will execute.
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 /// }
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 /// # Cleanup
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 /// 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	321 /// address space, because PAM applications may `fork()`:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	322 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	323 /// ```plain
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	324 /// ┃ let tx = start_pam_transaction();
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	325 /// ┃
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	326 /// ┃ tx.authenticate();
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	327 /// ┃ │ // PAM calls into your module where you set data:
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	328 /// ┃ │ handle.set_module_data("key", the_data);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	329 /// ┃
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	330 /// ┃ fork();
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	331 /// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━┓
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	332 /// Parent process Child process
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	333 /// ┃ wait(child); ┃ setuid(user_to_login);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	334 /// ┃ ┆ ┃ // ... do other stuff ...
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	335 /// ┃ ┆ ┃ drop(tx);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	336 /// ┃ ┆ ┃ │ // PAM cleans up your data.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	337 /// ┃ ┆ ┃ │ drop(the_data);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	338 /// ┃ ┆ ┗ exec(user's shell)
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	339 /// ┃ ┆ ┃ // user does stuff over their session
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	340 /// ┃ ┆ ┃ // ...
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	341 /// ┃ ┆ X
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 /// ┃ drop(tx);
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	344 /// ┃ │ // Parent PAM cleans up your data.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	345 /// ┃ │ 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	346 /// ```
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	347 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	348 /// 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	349 /// we do not (yet) offer this.
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	350 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	351 /// # References
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	352 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	353 #[doc = linklist!(pam_set_data: mwg, _std)]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	354 ///
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	355 #[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	356 #[doc = stdlinks!(3 pam_set_data)]
3036f2e6a022 Add module-specific data support. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	357 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	358
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	359 getter!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	360 /// 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	361 ///
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	362 /// 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	363 /// 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	364 ///
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	365 /// 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	366 /// 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	367 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	368 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	369 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	370 #[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	371 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	372 #[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	373 #[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	374 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	375 authtok_item("PAM_AUTHTOK", see = Self::authtok)
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	376 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	377
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	378 getter!(
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	379 /// 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	380 ///
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	381 /// 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	382 /// [`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	383 /// without prompting the user.
141 a508a69c068a Remove a lot of Results from functions. Paul Fisher <paul@pfish.zone> parents: 116 diff changeset	384 ///
80 5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction. Paul Fisher <paul@pfish.zone> parents: 78 diff changeset	385 /// 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	386 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	387 /// # References
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	388 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	389 #[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	390 ///
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	391 #[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	392 #[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	393 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	394 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	395 );
47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	396 }

Mercurial > crates > nonstick

annotate src/handle.rs @ 171:e27c5c667a5a