--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/libpam-sys/src/helpers.rs	Thu Jun 26 22:41:28 2025 -0400
@@ -0,0 +1,281 @@
+//! This module contains a few non-required helpers to deal with some of the
+//! more annoying memory-twiddling in the PAM API.
+//!
+//! Using these is optional but you might find it useful.
+use std::error::Error;
+use std::marker::{PhantomData, PhantomPinned};
+use std::mem::ManuallyDrop;
+use std::ptr::NonNull;
+use std::{fmt, slice};
+
+/// Error returned when attempting to allocate a buffer that is too big.
+///
+/// This is specifically used in [`OwnedBinaryPayload`] when you try to allocate
+/// a message larger than 2<sup>32</sup> bytes.
+#[derive(Debug, PartialEq)]
+pub struct TooBigError {
+    pub size: usize,
+    pub max: usize,
+}
+
+impl Error for TooBigError {}
+
+impl fmt::Display for TooBigError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "can't allocate a message of {size} bytes (max {max})",
+            size = self.size,
+            max = self.max
+        )
+    }
+}
+
+/// A trait wrapping memory management.
+///
+/// This is intended to allow you to bring your own allocator for
+/// [`OwnedBinaryPayload`]s.
+///
+/// For an implementation example, see the implementation of this trait
+/// for [`Vec`].
+pub trait Buffer<T: Default> {
+    /// Allocates a buffer of `len` elements, filled with the default.
+    fn allocate(len: usize) -> Self;
+
+    fn as_ptr(&self) -> *const T;
+
+    /// Returns a slice view of `size` elements of the given memory.
+    ///
+    /// # Safety
+    ///
+    /// The caller must not request more elements than are allocated.
+    unsafe fn as_mut_slice(&mut self, len: usize) -> &mut [T];
+
+    /// Consumes this ownership and returns a pointer to the start of the arena.
+    fn into_ptr(self) -> NonNull<T>;
+
+    /// "Adopts" the memory at the given pointer, taking it under management.
+    ///
+    /// Running the operation:
+    ///
+    /// ```
+    /// # use libpam_sys::helpers::Buffer;
+    /// # fn test<T: Default, OwnerType: Buffer<T>>(bytes: usize) {
+    /// let owner = OwnerType::allocate(bytes);
+    /// let ptr = owner.into_ptr();
+    /// let owner = unsafe { OwnerType::from_ptr(ptr, bytes) };
+    /// # }
+    /// ```
+    ///
+    /// must be a no-op.
+    ///
+    /// # Safety
+    ///
+    /// The pointer must be valid, and the caller must provide the exact size
+    /// of the given arena.
+    unsafe fn from_ptr(ptr: NonNull<T>, bytes: usize) -> Self;
+}
+
+impl<T: Default> Buffer<T> for Vec<T> {
+    fn allocate(bytes: usize) -> Self {
+        (0..bytes).map(|_| Default::default()).collect()
+    }
+
+    fn as_ptr(&self) -> *const T {
+        Vec::as_ptr(self)
+    }
+
+    unsafe fn as_mut_slice(&mut self, bytes: usize) -> &mut [T] {
+        debug_assert!(bytes <= self.len());
+        Vec::as_mut(self)
+    }
+
+    fn into_ptr(self) -> NonNull<T> {
+        let mut me = ManuallyDrop::new(self);
+        // SAFETY: a Vec is guaranteed to have a nonzero pointer.
+        unsafe { NonNull::new_unchecked(me.as_mut_ptr()) }
+    }
+
+    unsafe fn from_ptr(ptr: NonNull<T>, bytes: usize) -> Self {
+        Vec::from_raw_parts(ptr.as_ptr(), bytes, bytes)
+    }
+}
+
+/// A binary message owned by some storage.
+///
+/// This is an owned, memory-managed version of [`BinaryPayload`].
+/// The `O` type manages the memory where the payload lives.
+/// [`Vec<u8>`] is one such manager and can be used when ownership
+/// of the data does not need to transit through PAM.
+#[derive(Debug)]
+pub struct OwnedBinaryPayload<Owner: Buffer<u8>>(Owner);
+
+impl<O: Buffer<u8>> OwnedBinaryPayload<O> {
+    /// Allocates a new OwnedBinaryPayload.
+    ///
+    /// This will return a [`TooBigError`] if you try to allocate too much
+    /// (more than [`BinaryPayload::MAX_SIZE`]).
+    pub fn new(data_type: u8, data: &[u8]) -> Result<Self, TooBigError> {
+        let total_len: u32 = (data.len() + 5).try_into().map_err(|_| TooBigError {
+            size: data.len(),
+            max: BinaryPayload::MAX_SIZE,
+        })?;
+        let total_len = total_len as usize;
+        let mut buf = O::allocate(total_len);
+        // SAFETY: We just allocated this exact size.
+        BinaryPayload::fill(unsafe { &mut buf.as_mut_slice(total_len) }, data_type, data);
+        Ok(Self(buf))
+    }
+
+    /// The contents of the buffer.
+    pub fn contents(&self) -> (u8, &[u8]) {
+        unsafe { BinaryPayload::contents(self.as_ptr()) }
+    }
+
+    /// The total bytes needed to store this, including the header.
+    pub fn total_bytes(&self) -> usize {
+        unsafe {
+            self.0
+                .as_ptr()
+                .cast::<BinaryPayload>()
+                .as_ref()
+                .unwrap_unchecked()
+                .total_bytes()
+        }
+    }
+
+    /// Unwraps this into the raw storage backing it.
+    pub fn into_inner(self) -> O {
+        self.0
+    }
+
+    /// Gets a const pointer to the start of the message's buffer.
+    pub fn as_ptr(&self) -> *const BinaryPayload {
+        self.0.as_ptr().cast()
+    }
+
+    /// Consumes ownership of this message and converts it to a raw pointer
+    /// to the start of the message.
+    ///
+    /// To clean this up, you should eventually pass it into [`Self::from_ptr`]
+    /// with the same `O` ownership type.
+    pub fn into_ptr(self) -> NonNull<BinaryPayload> {
+        self.0.into_ptr().cast()
+    }
+
+    /// Takes ownership of the given pointer.
+    ///
+    /// # Safety
+    ///
+    /// You must provide a valid pointer, allocated by (or equivalent to one
+    /// allocated by) [`Self::new`]. For instance, passing a pointer allocated
+    /// by `malloc` to `OwnedBinaryPayload::<Vec<u8>>::from_ptr` is not allowed.
+    pub unsafe fn from_ptr(ptr: NonNull<BinaryPayload>) -> Self {
+        Self(O::from_ptr(ptr.cast(), ptr.as_ref().total_bytes() as usize))
+    }
+}
+
+/// The structure of the "binary message" payload for the `PAM_BINARY_PROMPT`
+/// extension from Linux-PAM.
+pub struct BinaryPayload {
+    /// The total length of the message, including this header,
+    /// as a u32 in network byte order (big endian).
+    total_length: [u8; 4],
+    /// A tag used to provide some kind of hint as to what the data is.
+    /// This is not defined by PAM.
+    data_type: u8,
+    /// Where the data itself would start, used as a marker to make this
+    /// not [`Unpin`] (since it is effectively an intrusive data structure
+    /// pointing to immediately after itself).
+    _marker: PhantomData<PhantomPinned>,
+}
+
+impl BinaryPayload {
+    /// The most data it's possible to put into a [`BinaryPayload`].
+    pub const MAX_SIZE: usize = (u32::MAX - 5) as usize;
+
+    /// Fills in the provided buffer with the given data.
+    ///
+    /// This uses [`copy_from_slice`](slice::copy_from_slice) internally,
+    /// so `buf` must be exactly 5 bytes longer than `data`, or this function
+    /// will panic.
+    pub fn fill(buf: &mut [u8], data_type: u8, data: &[u8]) {
+        let ptr: *mut Self = buf.as_mut_ptr().cast();
+        // SAFETY: We're given a slice, which always has a nonzero pointer.
+        let me = unsafe { ptr.as_mut().unwrap_unchecked() };
+        me.total_length = u32::to_be_bytes(buf.len() as u32);
+        me.data_type = data_type;
+        buf[5..].copy_from_slice(data)
+    }
+
+    /// The size of the message contained in the buffer.
+    fn len(&self) -> usize {
+        self.total_bytes().saturating_sub(5)
+    }
+
+    /// The total storage needed for the message, including header.
+    pub fn total_bytes(&self) -> usize {
+        u32::from_be_bytes(self.total_length) as usize
+    }
+
+    /// Gets the contents of the BinaryMessage starting at the given location.
+    ///
+    /// # Safety
+    ///
+    /// You must pass in a valid pointer, and ensure that the pointer passed in
+    /// outlives your borrow lifetime `'a`.
+    unsafe fn contents<'a>(ptr: *const Self) -> (u8, &'a [u8]) {
+        let header: &Self = ptr.as_ref().unwrap_unchecked();
+        let typ = header.data_type;
+        (
+            typ,
+            slice::from_raw_parts(ptr.cast::<u8>().offset(5), header.len()),
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    type VecPayload = OwnedBinaryPayload<Vec<u8>>;
+
+    #[test]
+    fn test_binary_payload() {
+        let simple_message = &[0u8, 0, 0, 16, 0xff, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        let empty = &[0u8; 5];
+
+        assert_eq!((0xff, &[0u8, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10][..]), unsafe {
+            BinaryPayload::contents(simple_message.as_ptr().cast())
+        });
+        assert_eq!((0x00, &[][..]), unsafe {
+            BinaryPayload::contents(empty.as_ptr().cast())
+        });
+    }
+
+    #[test]
+    fn test_owned_binary_payload() {
+        let (typ, data) = (
+            112,
+            &[0, 1, 1, 8, 9, 9, 9, 8, 8, 1, 9, 9, 9, 1, 1, 9, 7, 2, 5, 3][..],
+        );
+        let payload = VecPayload::new(typ, data).unwrap();
+        assert_eq!((typ, data), payload.contents());
+        let ptr = payload.into_ptr();
+        let payload = unsafe { VecPayload::from_ptr(ptr) };
+        assert_eq!((typ, data), payload.contents());
+    }
+
+    #[test]
+    #[ignore]
+    fn test_owned_too_big() {
+        let data = vec![0xFFu8; 0x1_0000_0001];
+        assert_eq!(
+            TooBigError {
+                max: 0xffff_fffa,
+                size: 0x1_0000_0001
+            },
+            VecPayload::new(5, &data).unwrap_err()
+        )
+    }
+}