Mercurial > crates > nonstick
annotate src/handle.rs @ 75:c30811b4afae
rename pam_ffi submodule to libpam.
| author | Paul Fisher <paul@pfish.zone> |
|---|---|
| date | Fri, 06 Jun 2025 22:35:08 -0400 |
| parents | ac6881304c78 |
| children | 002adfb98c5c |
| 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. |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
2 use crate::constants::Result; |
| 72 | 3 use crate::conv::Conversation; |
|
15
27730595f1ea
Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff
changeset
|
4 |
| 72 | 5 macro_rules! trait_item { |
| 6 (get = $getter:ident, item = $item:literal $(, see = $see:path)? $(, $($doc:literal)*)?) => { | |
| 7 $( | |
| 8 $(#[doc = $doc])* | |
| 9 #[doc = ""] | |
| 10 )? | |
| 11 #[doc = concat!("Gets the `", $item, "` of the PAM handle.")] | |
| 12 $( | |
| 13 #[doc = concat!("See [`", stringify!($see), "`].")] | |
| 14 )? | |
| 15 #[doc = ""] | |
| 16 #[doc = "Returns a reference to the item's value, owned by PAM."] | |
| 17 #[doc = "The item is assumed to be valid UTF-8 text."] | |
| 18 #[doc = "If it is not, `ConversationError` is returned."] | |
| 19 #[doc = ""] | |
| 20 #[doc = "See the [`pam_get_item`][man] manual page,"] | |
| 21 #[doc = "[`pam_get_item` in the Module Writers' Guide][mwg], or"] | |
| 22 #[doc = "[`pam_get_item` in the Application Developers' Guide][adg]."] | |
| 23 #[doc = ""] | |
| 24 #[doc = "[man]: https://www.man7.org/linux/man-pages/man3/pam_get_item.3.html"] | |
| 25 #[doc = "[adg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/adg-interface-by-app-expected.html#adg-pam_get_item"] | |
| 26 #[doc = "[mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_item"] | |
| 27 fn $getter(&mut self) -> Result<Option<&str>>; | |
| 28 }; | |
| 29 (set = $setter:ident, item = $item:literal $(, see = $see:path)? $(, $($doc:literal)*)?) => { | |
| 30 $( | |
| 31 $(#[doc = $doc])* | |
| 32 #[doc = ""] | |
| 33 )? | |
| 34 #[doc = concat!("Sets the `", $item, "` from the PAM handle.")] | |
| 35 $( | |
| 36 #[doc = concat!("See [`", stringify!($see), "`].")] | |
| 37 )? | |
| 38 #[doc = ""] | |
| 39 #[doc = "Sets the item's value. PAM copies the string's contents."] | |
| 40 #[doc = "If the string contains a null byte, this will return "] | |
| 41 #[doc = "a `ConversationError`."] | |
| 42 #[doc = ""] | |
| 43 #[doc = "See the [`pam_set_item`][man] manual page,"] | |
| 44 #[doc = "[`pam_set_item` in the Module Writers' Guide][mwg], or"] | |
| 45 #[doc = "[`pam_set_item` in the Application Developers' Guide][adg]."] | |
| 46 #[doc = ""] | |
| 47 #[doc = "[man]: https://www.man7.org/linux/man-pages/man3/pam_set_item.3.html"] | |
| 48 #[doc = "[adg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/adg-interface-by-app-expected.html#adg-pam_set_item"] | |
| 49 #[doc = "[mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_set_item"] | |
| 50 fn $setter(&mut self, value: Option<&str>) -> Result<()>; | |
| 51 }; | |
| 52 } | |
| 53 | |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
54 /// All-in-one trait for what you should expect from PAM as an application. |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
55 pub trait PamHandleApplication: PamApplicationOnly + PamShared {} |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
56 impl<T> PamHandleApplication for T where T: PamApplicationOnly + PamShared {} |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
57 |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
58 /// All-in-one trait for what you should expect from PAM as a module. |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
59 pub trait PamHandleModule: PamModuleOnly + PamShared {} |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
60 impl<T> PamHandleModule for T where T: PamModuleOnly + PamShared {} |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
61 |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
62 /// 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
|
63 /// |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
64 /// 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
|
65 /// to both applications and modules. |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
66 /// |
|
75
c30811b4afae
rename pam_ffi submodule to libpam.
Paul Fisher <paul@pfish.zone>
parents:
73
diff
changeset
|
67 /// You probably want [`LibPamHandle`](crate::libpam::OwnedLibPamHandle). |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
68 /// 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
|
69 /// to test PAM modules and applications. |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
70 pub trait PamShared { |
|
19
d654aa0655e5
Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents:
15
diff
changeset
|
71 /// 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
|
72 /// |
| 72 | 73 /// If the username has previously been obtained, this uses that username; |
| 74 /// otherwise it prompts the user with the first of these that is present: | |
| 75 /// | |
| 76 /// 1. The prompt string passed to this function. | |
| 77 /// 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
|
78 /// 3. The default prompt, `login: `. |
| 72 | 79 /// |
|
64
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
80 /// See the [`pam_get_user` manual page][man] |
|
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
81 /// or [`pam_get_user` in the Module Writer's Guide][mwg]. |
|
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
82 /// |
|
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
83 /// # Example |
|
19
d654aa0655e5
Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents:
15
diff
changeset
|
84 /// |
|
64
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
85 /// ```no_run |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
86 /// # use nonstick::PamShared; |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
87 /// # 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
|
88 /// // Get the username using the default prompt. |
|
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
89 /// let user = handle.get_user(None)?; |
|
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
90 /// // Get the username using a custom prompt. |
| 72 | 91 /// // If this were actually called right after the above, |
| 92 /// // both user and user_2 would have the same value. | |
| 93 /// let user_2 = handle.get_user(Some("who ARE you even???"))?; | |
|
64
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
94 /// # Ok(()) |
|
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
95 /// # } |
|
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
96 /// ``` |
|
66
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
97 /// |
|
64
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
98 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_user.3.html |
|
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
99 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_user |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
100 fn get_user(&mut self, prompt: Option<&str>) -> Result<&str>; |
| 72 | 101 |
| 102 trait_item!( | |
| 103 get = user_item, | |
| 104 item = "PAM_USER", | |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
105 see = Self::get_user, |
| 72 | 106 "The identity of the user for whom service is being requested." |
| 107 "" | |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
108 "Unlike [`get_user`](Self::get_user), this will simply get" |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
109 "the current state of the user item, and not request the username. " |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
110 "While PAM usually sets this automatically in the `get_user` call, " |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
111 "it may be changed by a module during the PAM transaction. " |
| 72 | 112 "Applications should check it after each step of the PAM process." |
| 113 ); | |
| 114 trait_item!( | |
| 115 set = set_user_item, | |
| 116 item = "PAM_USER", | |
| 117 see = Self::user_item, | |
| 118 "Sets the identity of the logging-in user." | |
| 119 "" | |
| 120 "Usually this will be set during the course of " | |
| 121 "a [`get_user`](Self::get_user) call, but you may set it manually " | |
| 122 "or change it during the PAM process." | |
| 123 ); | |
|
44
50371046c61a
Add support for pam_get_authtok and minor cleanups.
Paul Fisher <paul@pfish.zone>
parents:
34
diff
changeset
|
124 |
| 72 | 125 trait_item!( |
| 126 get = service, | |
| 127 item = "PAM_SERVICE", | |
| 128 "The service name, which identifies the PAM stack which is used " | |
| 129 "to perform authentication." | |
| 130 ); | |
| 131 trait_item!( | |
| 132 set = set_service, | |
| 133 item = "PAM_SERVICE", | |
| 134 see = Self::service, | |
| 135 "The service name, which identifies the PAM stack which is used " | |
| 136 "to perform authentication. It's probably a bad idea to change this." | |
| 137 ); | |
| 138 | |
| 139 trait_item!( | |
| 140 get = user_prompt, | |
| 141 item = "PAM_USER_PROMPT", | |
| 142 "The string used to prompt for a user's name." | |
| 143 "By default, this is a localized version of `login: `." | |
| 144 ); | |
| 145 trait_item!( | |
| 146 set = set_user_prompt, | |
| 147 item = "PAM_USER_PROMPT", | |
| 148 see = Self::user_prompt, | |
| 149 "Sets the string used to prompt for a user's name." | |
| 150 ); | |
|
64
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
151 |
| 72 | 152 trait_item!( |
| 153 get = tty_name, | |
| 154 item = "PAM_TTY", | |
| 155 "\"The terminal name prefixed by /dev/ for device files.\"" | |
| 156 "" | |
| 157 "This is the terminal the user is logging in on." | |
| 158 "Very old applications may use this instead of `PAM_XDISPLAY`." | |
| 159 ); | |
| 160 trait_item!( | |
| 161 set = set_tty_name, | |
| 162 item = "PAM_TTY", | |
| 163 see = Self::tty_name, | |
| 164 "Sets the terminal name." | |
| 165 "" | |
| 166 "(TODO: See if libpam sets this itself or if the application does.)" | |
| 167 ); | |
| 168 | |
| 169 trait_item!( | |
| 170 get = remote_user, | |
| 171 item = "PAM_RUSER", | |
| 172 "If set, the identity of the remote user logging in." | |
| 173 "" | |
| 174 "This is only as trustworthy as the application calling PAM." | |
| 175 "Also see [`remote_host`](Self::remote_host)." | |
| 176 ); | |
| 177 trait_item!( | |
| 178 set = set_remote_user, | |
| 179 item = "PAM_RUSER", | |
| 180 "Sets the identity of the remote user logging in." | |
| 181 "" | |
| 182 "This is usually set by the application before making calls " | |
| 183 "into a PAM session. (TODO: check this!)" | |
| 184 ); | |
|
64
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
185 |
| 72 | 186 trait_item!( |
| 187 get = remote_host, | |
| 188 item = "PAM_RHOST", | |
| 189 "If set, the remote location where the user is coming from." | |
| 190 "" | |
| 191 "This is only as trustworthy as the application calling PAM. " | |
| 192 "This can be combined with [`Self::remote_user`] to identify " | |
| 193 "the account the user is attempting to log in from, " | |
| 194 "with `remote_user@remote_host`." | |
| 195 "" | |
| 196 "If unset, \"it is unclear where the authentication request " | |
| 197 "is originating from.\"" | |
| 198 ); | |
| 199 trait_item!( | |
| 200 set = set_remote_host, | |
| 201 item = "PAM_RHOST", | |
| 202 see = Self::remote_host, | |
| 203 "Sets the location where the user is coming from." | |
| 204 "" | |
| 205 "This is usually set by the application before making calls " | |
| 206 "into a PAM session. (TODO: check this!)" | |
| 207 ); | |
| 208 | |
| 209 trait_item!( | |
| 210 set = set_authtok_item, | |
| 211 item = "PAM_AUTHTOK", | |
| 212 see = PamModuleHandle::authtok_item, | |
| 213 "Sets the user's authentication token (e.g., password)." | |
| 214 "" | |
| 215 "This is usually set automatically when " | |
| 216 "[`get_authtok`](PamModuleHandle::get_authtok) is called, " | |
| 217 "but can be manually set." | |
| 218 ); | |
| 219 | |
| 220 trait_item!( | |
| 221 set = set_old_authtok_item, | |
| 222 item = "PAM_OLDAUTHTOK", | |
| 223 see = PamModuleHandle::old_authtok_item, | |
| 224 "Sets the user's \"old authentication token\" when changing passwords." | |
| 225 "" | |
| 226 "This is usually set automatically by PAM." | |
| 227 ); | |
|
69
8f3ae0c7ab92
Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents:
66
diff
changeset
|
228 } |
|
64
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
229 |
|
69
8f3ae0c7ab92
Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents:
66
diff
changeset
|
230 /// 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
|
231 /// |
|
8f3ae0c7ab92
Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents:
66
diff
changeset
|
232 /// 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
|
233 /// 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
|
234 /// |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
235 /// 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
|
236 /// of PAM for testing PAM applications. |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
237 pub trait PamApplicationOnly { |
|
66
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
238 /// Closes the PAM session on an owned PAM handle. |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
239 /// |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
240 /// This should be called with the result of the application's last call |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
241 /// into PAM services. Since this is only applicable to *owned* PAM handles, |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
242 /// a PAM module should never call this (and it will never be handed |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
243 /// an owned `PamHandle` that it can `close`). |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
244 /// |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
245 /// See the [`pam_end` manual page][man] for more information. |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
246 /// |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
247 /// ```no_run |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
248 /// # use nonstick::handle::PamApplicationOnly; |
|
66
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
249 /// # use std::error::Error; |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
250 /// # fn _doc(handle: impl PamApplicationOnly, auth_result: nonstick::Result<()>) -> Result<(), Box<dyn Error>> { |
|
66
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
251 /// // Earlier: authentication was performed and the result was stored |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
252 /// // into auth_result. |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
253 /// handle.close(auth_result)?; |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
254 /// # Ok(()) |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
255 /// # } |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
256 /// ``` |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
257 /// |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
258 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_end.3.html |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
259 fn close(self, status: Result<()>) -> Result<()>; |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
260 } |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
261 |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
262 /// 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
|
263 /// |
|
a674799a5cd3
Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents:
64
diff
changeset
|
264 /// 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
|
265 /// 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
|
266 /// |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
267 /// 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
|
268 /// of PAM for testing PAM modules. |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
269 pub trait PamModuleOnly: Conversation { |
| 72 | 270 /// Retrieves the authentication token from the user. |
| 271 /// | |
| 272 /// This should only be used by *authentication* and *password-change* | |
| 273 /// PAM modules. | |
| 274 /// | |
| 275 /// See the [`pam_get_authtok` manual page][man] | |
| 276 /// or [`pam_get_item` in the Module Writer's Guide][mwg]. | |
| 277 /// | |
| 278 /// # Example | |
| 279 /// | |
| 280 /// ```no_run | |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
281 /// # use nonstick::handle::PamModuleOnly; |
|
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
282 /// # fn _doc(handle: &mut impl PamModuleOnly) -> Result<(), Box<dyn std::error::Error>> { |
| 72 | 283 /// // Get the user's password using the default prompt. |
| 284 /// let pass = handle.get_authtok(None)?; | |
| 285 /// // Get the user's password using a custom prompt. | |
| 286 /// let pass = handle.get_authtok(Some("Reveal your secrets!"))?; | |
| 287 /// Ok(()) | |
| 288 /// # } | |
| 289 /// ``` | |
|
64
bbe84835d6db
More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents:
60
diff
changeset
|
290 /// |
| 72 | 291 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_authtok.3.html |
| 292 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_item | |
|
73
ac6881304c78
Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents:
72
diff
changeset
|
293 fn get_authtok(&mut self, prompt: Option<&str>) -> Result<&str>; |
| 72 | 294 |
| 295 trait_item!( | |
| 296 get = authtok_item, | |
| 297 item = "PAM_AUTHTOK", | |
| 298 see = Self::get_authtok, | |
| 299 "Gets the user's authentication token (e.g., password)." | |
| 300 "" | |
| 301 "This is normally set automatically by PAM when calling " | |
| 302 "[`get_authtok`](Self::get_authtok), but can be set explicitly." | |
| 303 "" | |
| 304 "Like `get_authtok`, this should only ever be called " | |
| 305 "by *authentication* and *password-change* PAM modules." | |
| 306 ); | |
| 307 | |
| 308 trait_item!( | |
| 309 get = old_authtok_item, | |
| 310 item = "PAM_OLDAUTHTOK", | |
| 311 see = PamHandle::set_old_authtok_item, | |
| 312 "Gets the user's old authentication token when changing passwords." | |
| 313 "" | |
| 314 "This should only ever be called by *password-change* PAM modules." | |
| 315 ); | |
| 316 | |
| 317 /* | |
| 318 TODO: Re-enable this at some point. | |
| 319 /// Gets some pointer, identified by `key`, that has been set previously | |
| 320 /// using [`set_data`](Self::set_data). | |
| 321 /// | |
| 322 /// The data, if present, is still owned by the current PAM session. | |
| 323 /// | |
| 324 /// See the [`pam_get_data` manual page][man] | |
| 325 /// or [`pam_get_data` in the Module Writer's Guide][mwg]. | |
| 326 /// | |
| 327 /// # Safety | |
| 328 /// | |
| 329 /// The data stored under the provided key must be of type `T`, | |
| 330 /// otherwise you'll get back a completely invalid `&T` | |
| 331 /// and further behavior is undefined. | |
| 332 /// | |
| 333 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_data.3.html | |
| 334 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_data | |
| 335 unsafe fn get_data<T>(&mut self, key: &str) -> Result<Option<&T>>; | |
| 336 | |
| 337 /// Stores a pointer that can be retrieved later with [`get_data`](Self::get_data). | |
| 338 /// | |
| 339 /// This data is accessible to this module and other PAM modules | |
| 340 /// (using the provided `key`), but is *not* accessible to the application. | |
| 341 /// The PAM session takes ownership of the data, and it will be dropped | |
| 342 /// when the session ends. | |
| 343 /// | |
| 344 /// See the [`pam_set_data` manual page][man] | |
| 345 /// or [`pam_set_data` in the Module Writer's Guide][mwg]. | |
| 346 /// | |
| 347 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_set_data.3.html | |
| 348 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_set_data | |
| 349 fn set_data<T>(&mut self, key: &str, data: Box<T>) -> Result<()>; | |
| 350 */ | |
| 351 } |