Mercurial > crates > nonstick

comparison src/handle.rs @ 98:b87100c5eed4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Start on environment variables, and make pointers nicer. This starts work on the PAM environment handling, and in so doing, introduces the CHeapBox and CHeapString structs. These are analogous to Box and CString, but they're located on the C heap rather than being Rust-managed memory. This is because environment variables deal with even more pointers and it turns out we can lose a lot of manual freeing using homemade smart pointers.
author Paul Fisher <paul@pfish.zone>
date Tue, 24 Jun 2025 04:25:25 -0400
parents efe2f5f8b5b2
children 3f11b8d30f63
comparison
equal deleted inserted replaced
97:efe2f5f8b5b2 98:b87100c5eed4
1 //! The wrapper types and traits for handles into the PAM library. 1 //! The wrapper types and traits for handles into the PAM library.
2 2
3 use crate::constants::{Flags, Result}; 3 use crate::constants::{Flags, Result};
4 use crate::conv::Conversation; 4 use crate::conv::Conversation;
5 use crate::environ::{EnvironMap, EnvironMapMut};
5 use crate::logging::Level; 6 use crate::logging::Level;
6 7
7 macro_rules! trait_item { 8 macro_rules! trait_item {
8 ($(#[$md:meta])* get = $getter:ident, item = $item:literal $(, see = $see:path)?) => { 9 ($(#[$md:meta])* get = $getter:ident, item = $item:literal $(, see = $see:path)?) => {
9 $(#[$md])* 10 $(#[$md])*
67 /// # Example 68 /// # Example
68 /// 69 ///
69 /// ```no_run 70 /// ```no_run
70 /// # use nonstick::{PamShared}; 71 /// # use nonstick::{PamShared};
71 /// # use nonstick::logging::Level; 72 /// # use nonstick::logging::Level;
72 /// # let pam_hdl: Box<dyn PamShared> = unimplemented!(); 73 /// # fn _test(pam_hdl: impl PamShared) {
73 /// # let delay_ms = 100; 74 /// # let delay_ms = 100;
74 /// # let url = "https://zombo.com"; 75 /// # let url = "https://zombo.com";
75 /// // Usually, instead of calling this manually, just use the macros. 76 /// // Usually, instead of calling this manually, just use the macros.
76 /// nonstick::error!(pam_hdl, "something bad happened!"); 77 /// nonstick::error!(pam_hdl, "something bad happened!");
77 /// nonstick::warn!(pam_hdl, "loading information took {delay_ms} ms"); 78 /// nonstick::warn!(pam_hdl, "loading information took {delay_ms} ms");
78 /// nonstick::info!(pam_hdl, "using network backend"); 79 /// nonstick::info!(pam_hdl, "using network backend");
79 /// nonstick::debug!(pam_hdl, "sending GET request to {url}"); 80 /// nonstick::debug!(pam_hdl, "sending GET request to {url}");
80 /// // But if you really want to, you can call this yourself: 81 /// // But if you really want to, you can call this yourself:
81 /// pam_hdl.log(Level::Warning, "this is unnecessarily verbose"); 82 /// pam_hdl.log(Level::Warning, "this is unnecessarily verbose");
83 /// # }
82 /// ``` 84 /// ```
83 fn log(&self, level: Level, entry: &str); 85 fn log(&self, level: Level, entry: &str);
84 86
85 /// Retrieves the name of the user who is authenticating or logging in. 87 /// Retrieves the name of the user who is authenticating or logging in.
86 /// 88 ///
111 /// 113 ///
112 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_user.3.html 114 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_user.3.html
113 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_user 115 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_user
114 fn username(&mut self, prompt: Option<&str>) -> Result<String>; 116 fn username(&mut self, prompt: Option<&str>) -> Result<String>;
115 117
118 /// The contents of the environment to set, read-only.
119 fn environ(&self) -> impl EnvironMap;
120
121 /// A writable version of the environment.
122 fn environ_mut(&mut self) -> impl EnvironMapMut;
123
116 trait_item!( 124 trait_item!(
117 /// The identity of the user for whom service is being requested. 125 /// The identity of the user for whom service is being requested.
118 /// 126 ///
119 /// Unlike [`username`](Self::username), this will simply get 127 /// Unlike [`username`](Self::username), this will simply get
120 /// the current state of the user item, and not request the username. 128 /// the current state of the user item, and not request the username.
248 /// Like [`PamShared`], this is intended to allow creating mock implementations 256 /// Like [`PamShared`], this is intended to allow creating mock implementations
249 /// of PAM for testing PAM applications. 257 /// of PAM for testing PAM applications.
250 pub trait PamHandleApplication: PamShared { 258 pub trait PamHandleApplication: PamShared {
251 /// Starts the authentication process for the user. 259 /// Starts the authentication process for the user.
252 fn authenticate(&mut self, flags: Flags) -> Result<()>; 260 fn authenticate(&mut self, flags: Flags) -> Result<()>;
253 261
254 /// Does "account management". 262 /// Does "account management".
255 fn account_management(&mut self, flags: Flags) -> Result<()>; 263 fn account_management(&mut self, flags: Flags) -> Result<()>;
256 264
257 /// Changes the authentication token. 265 /// Changes the authentication token.
258 fn change_authtok(&mut self, flags: Flags) -> Result<()>; 266 fn change_authtok(&mut self, flags: Flags) -> Result<()>;
259 } 267 }
260 268
261 /// Functionality of a PAM handle that can be expected by a PAM module. 269 /// Functionality of a PAM handle that can be expected by a PAM module.