# HG changeset patch # User Paul Fisher # Date 1751817566 14400 # Node ID 56b559b7ecea2cc83a846cf392cc1b6754187846 # Parent ebb71a412b5864e822f60dc8826e5b59dad299cb Big rename: separate concepts of Transaction from Handle. - An application that uses PAM creates a Transaction. - The Transaction has a Handle. Currently, a module still get something called a "handle", but that's probably going to change soon. diff -r ebb71a412b58 -r 56b559b7ecea src/handle.rs --- a/src/handle.rs Sat Jul 05 22:12:46 2025 -0400 +++ b/src/handle.rs Sun Jul 06 11:59:26 2025 -0400 @@ -59,7 +59,7 @@ /// This base trait includes features of a PAM handle that are available /// to both applications and modules. /// -/// You probably want [`LibPamHandle`](crate::libpam::OwnedLibPamHandle). +/// You probably want [`LibPamTransaction`](crate::libpam::LibPamTransaction). /// This trait is intended to allow creating mock PAM handle types /// to test PAM modules and applications. pub trait PamShared { @@ -268,7 +268,7 @@ /// /// Like [`PamShared`], this is intended to allow creating mock implementations /// of PAM for testing PAM applications. -pub trait PamHandleApplication: PamShared { +pub trait Transaction: PamShared { /// Starts the authentication process for the user. /// /// The application calls this to find out who the user is, and verify that diff -r ebb71a412b58 -r 56b559b7ecea src/lib.rs --- a/src/lib.rs Sat Jul 05 22:12:46 2025 -0400 +++ b/src/lib.rs Sun Jul 06 11:59:26 2025 -0400 @@ -40,12 +40,12 @@ #[cfg(feature = "link")] #[doc(inline)] -pub use crate::libpam::{OwnedLibPamHandle, RawPamHandle}; +pub use crate::libpam::{LibPamHandle, LibPamTransaction}; #[doc(inline)] pub use crate::{ constants::{ErrorCode, Flags, Result}, conv::{BinaryData, Conversation, ConversationAdapter}, environ::{EnvironMap, EnvironMapMut}, - handle::{PamHandleApplication, PamHandleModule, PamShared}, + handle::{PamHandleModule, PamShared, Transaction}, module::PamModule, }; diff -r ebb71a412b58 -r 56b559b7ecea src/libpam/environ.rs --- a/src/libpam/environ.rs Sat Jul 05 22:12:46 2025 -0400 +++ b/src/libpam/environ.rs Sun Jul 06 11:59:26 2025 -0400 @@ -1,13 +1,13 @@ use crate::environ::{EnvironMap, EnvironMapMut}; use crate::libpam::memory::{CHeapBox, CHeapString}; -use crate::libpam::{memory, RawPamHandle}; +use crate::libpam::{memory, LibPamHandle}; use std::ffi::{c_char, CStr, CString, OsStr, OsString}; use std::marker::PhantomData; use std::os::unix::ffi::{OsStrExt, OsStringExt}; use std::ptr; use std::ptr::NonNull; -impl RawPamHandle { +impl LibPamHandle { fn environ_get(&self, key: &OsStr) -> Option { let key = CString::new(key.as_bytes()).ok()?; // SAFETY: We are a valid handle and are calling with a good key. @@ -55,22 +55,22 @@ /// A view to the environment stored in a PAM handle. pub struct LibPamEnviron<'a> { - source: &'a RawPamHandle, + source: &'a LibPamHandle, } /// A mutable view to the environment stored in a PAM handle. pub struct LibPamEnvironMut<'a> { - source: &'a mut RawPamHandle, + source: &'a mut LibPamHandle, } impl<'a> LibPamEnviron<'a> { - pub fn new(source: &'a RawPamHandle) -> Self { + pub fn new(source: &'a LibPamHandle) -> Self { Self { source } } } impl<'a> LibPamEnvironMut<'a> { - pub fn new(source: &'a mut RawPamHandle) -> Self { + pub fn new(source: &'a mut LibPamHandle) -> Self { Self { source } } } @@ -113,7 +113,7 @@ start: NonNull>, /// The environment variable we're about to iterate into. current: NonNull>, - _owner: PhantomData<&'a RawPamHandle>, + _owner: PhantomData<&'a LibPamHandle>, } impl EnvList<'_> { diff -r ebb71a412b58 -r 56b559b7ecea src/libpam/handle.rs --- a/src/libpam/handle.rs Sat Jul 05 22:12:46 2025 -0400 +++ b/src/libpam/handle.rs Sun Jul 06 11:59:26 2025 -0400 @@ -7,8 +7,7 @@ use crate::libpam::memory; use crate::logging::{Level, Location}; use crate::{ - guide, linklist, stdlinks, Conversation, EnvironMap, Flags, PamHandleApplication, - PamHandleModule, + guide, linklist, stdlinks, Conversation, EnvironMap, Flags, PamHandleModule, Transaction, }; use libpam_sys_helpers::constants; use num_enum::{IntoPrimitive, TryFromPrimitive}; @@ -20,9 +19,9 @@ use std::ptr::NonNull; /// An owned PAM handle. -pub struct OwnedLibPamHandle { +pub struct LibPamTransaction { /// The handle itself. - handle: ManuallyDrop, + handle: ManuallyDrop, /// The last return value from the handle. last_return: Cell>, /// If set, the Conversation that this PAM handle owns. @@ -36,12 +35,12 @@ } #[derive(Debug, PartialEq)] -pub struct HandleBuilder { +pub struct TransactionBuilder { service_name: OsString, username: Option, } -impl HandleBuilder { +impl TransactionBuilder { /// Updates the service name. pub fn service_name(mut self, service_name: OsString) -> Self { self.service_name = service_name; @@ -55,12 +54,12 @@ self } /// Builds a PAM handle and starts the transaction. - pub fn build(self, conv: impl Conversation) -> Result> { - OwnedLibPamHandle::start(self.service_name, self.username, conv) + pub fn build(self, conv: impl Conversation) -> Result> { + LibPamTransaction::start(self.service_name, self.username, conv) } } -impl OwnedLibPamHandle { +impl LibPamTransaction { /// Creates a builder to start a PAM transaction for the given service. /// /// The service name is what controls the steps and checks PAM goes through @@ -72,8 +71,8 @@ /// #[doc = stdlinks!(3 pam_start)] #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_start")] - pub fn build_with_service(service_name: OsString) -> HandleBuilder { - HandleBuilder { + pub fn build_with_service(service_name: OsString) -> TransactionBuilder { + TransactionBuilder { service_name, username: None, } @@ -101,7 +100,7 @@ ErrorCode::result_from(result)?; let handle = NonNull::new(handle).ok_or(ErrorCode::BufferError)?; Ok(Self { - handle: ManuallyDrop::new(RawPamHandle(handle)), + handle: ManuallyDrop::new(LibPamHandle(handle)), last_return: Cell::new(Ok(())), conversation: conv, }) @@ -128,7 +127,7 @@ }; } -impl PamHandleApplication for RawPamHandle { +impl Transaction for LibPamHandle { wrap!(fn authenticate { pam_authenticate }); wrap!(fn account_management { pam_acct_mgmt }); wrap!(fn change_authtok { pam_chauthtok }); @@ -144,7 +143,7 @@ // pam_getenv - shared // pam_getenvlist - shared -impl Drop for OwnedLibPamHandle { +impl Drop for LibPamTransaction { /// Closes the PAM session on an owned PAM handle. /// /// This internally calls `pam_end` with the appropriate error code. @@ -205,7 +204,7 @@ result.as_ref().map(drop).map_err(|&e| e) } -impl PamShared for OwnedLibPamHandle { +impl PamShared for LibPamTransaction { delegate!(fn log(&self, level: Level, location: Location<'_>, entry: &str) -> ()); delegate!(fn environ(&self) -> impl EnvironMap); delegate!(fn environ_mut(&mut self) -> impl EnvironMapMut); @@ -237,14 +236,15 @@ /// An owned variation of a basic PAM handle. /// /// This is the most basic version of a wrapped PAM handle. It's mostly used -/// as the inside of the [`OwnedLibPamHandle`], but can also be used to "adopt" +/// as the inside of the [`LibPamTransaction`], but can also be used to "adopt" /// a PAM handle created by another library. /// /// If [`Self::end`] is not called, this will always call `pam_end` reporting /// successful completion. -pub struct RawPamHandle(NonNull); +#[repr(transparent)] +pub struct LibPamHandle(NonNull); -impl RawPamHandle { +impl LibPamHandle { /// Takes ownership of the pointer to the given PAM handle. /// /// **Do not use this just to get a reference to a PAM handle.** @@ -317,13 +317,13 @@ } } -impl Drop for RawPamHandle { +impl Drop for LibPamHandle { fn drop(&mut self) { unsafe { libpam_sys::pam_end(self.0.as_mut(), 0) }; } } -impl PamShared for RawPamHandle { +impl PamShared for LibPamHandle { #[cfg(any())] fn log(&self, level: Level, loc: Location<'_>, entry: &str) { let entry = match CString::new(entry).or_else(|_| CString::new(dbg!(entry))) { @@ -393,7 +393,7 @@ cstr_item!(set = set_old_authtok_item, item = ItemType::OldAuthTok); } -impl Conversation for RawPamHandle { +impl Conversation for LibPamHandle { fn communicate(&self, messages: &[Exchange]) { match self.conversation_item() { Ok(conv) => conv.communicate(messages), @@ -406,7 +406,7 @@ } } -impl PamHandleModule for RawPamHandle { +impl PamHandleModule for LibPamHandle { fn authtok(&mut self, prompt: Option<&OsStr>) -> Result { self.get_authtok(prompt, ItemType::AuthTok) } @@ -430,7 +430,7 @@ } // Implementations of internal functions. -impl RawPamHandle { +impl LibPamHandle { #[cfg(any(pam_impl = "LinuxPam", pam_impl = "OpenPam"))] fn get_authtok(&mut self, prompt: Option<&OsStr>, item_type: ItemType) -> Result { let prompt = memory::option_cstr_os(prompt); diff -r ebb71a412b58 -r 56b559b7ecea src/libpam/mod.rs --- a/src/libpam/mod.rs Sat Jul 05 22:12:46 2025 -0400 +++ b/src/libpam/mod.rs Sun Jul 06 11:59:26 2025 -0400 @@ -15,4 +15,4 @@ mod question; #[doc(inline)] -pub use handle::{OwnedLibPamHandle, RawPamHandle}; +pub use handle::{LibPamHandle, LibPamTransaction}; diff -r ebb71a412b58 -r 56b559b7ecea src/libpam/module.rs --- a/src/libpam/module.rs Sat Jul 05 22:12:46 2025 -0400 +++ b/src/libpam/module.rs Sun Jul 06 11:59:26 2025 -0400 @@ -11,7 +11,7 @@ /// /// ```no_run /// use nonstick::{ -/// pam_hooks, ConversationAdapter, Flags, OwnedLibPamHandle, PamHandleModule, PamModule, +/// pam_hooks, ConversationAdapter, Flags, LibPamTransaction, PamHandleModule, PamModule, /// Result as PamResult, /// }; /// use std::ffi::CStr; @@ -42,7 +42,7 @@ ($ident:ident) => { mod _pam_hooks_scope { use std::ffi::{c_char, c_int, c_void, CStr}; - use $crate::{ErrorCode, Flags, PamModule, RawPamHandle}; + use $crate::{ErrorCode, Flags, LibPamHandle, PamModule}; #[no_mangle] extern "C" fn pam_sm_acct_mgmt( @@ -51,7 +51,7 @@ argc: c_int, argv: *const *const c_char, ) -> c_int { - if let Some(handle) = unsafe { pamh.cast::().as_mut() } { + if let Some(handle) = unsafe { pamh.cast::().as_mut() } { let args = extract_argv(argc, argv); ErrorCode::result_to_c(super::$ident::account_management(handle, args, flags)) } else { @@ -66,7 +66,7 @@ argc: c_int, argv: *const *const c_char, ) -> c_int { - if let Some(handle) = unsafe { pamh.cast::().as_mut() } { + if let Some(handle) = unsafe { pamh.cast::().as_mut() } { let args = extract_argv(argc, argv); ErrorCode::result_to_c(super::$ident::authenticate(handle, args, flags)) } else { @@ -81,7 +81,7 @@ argc: c_int, argv: *const *const c_char, ) -> c_int { - if let Some(handle) = unsafe { pamh.cast::().as_mut() } { + if let Some(handle) = unsafe { pamh.cast::().as_mut() } { let args = extract_argv(argc, argv); ErrorCode::result_to_c(super::$ident::change_authtok(handle, args, flags)) } else { @@ -96,7 +96,7 @@ argc: c_int, argv: *const *const c_char, ) -> c_int { - if let Some(handle) = unsafe { pamh.cast::().as_mut() } { + if let Some(handle) = unsafe { pamh.cast::().as_mut() } { let args = extract_argv(argc, argv); ErrorCode::result_to_c(super::$ident::close_session(handle, args, flags)) } else { @@ -112,7 +112,7 @@ argv: *const *const c_char, ) -> c_int { let args = extract_argv(argc, argv); - if let Some(handle) = unsafe { pamh.cast::().as_mut() } { + if let Some(handle) = unsafe { pamh.cast::().as_mut() } { ErrorCode::result_to_c(super::$ident::open_session(handle, args, flags)) } else { ErrorCode::Ignore as c_int @@ -127,7 +127,7 @@ argv: *const *const c_char, ) -> c_int { let args = extract_argv(argc, argv); - if let Some(handle) = unsafe { pamh.cast::().as_mut() } { + if let Some(handle) = unsafe { pamh.cast::().as_mut() } { ErrorCode::result_to_c(super::$ident::set_credentials(handle, args, flags)) } else { ErrorCode::Ignore as c_int