Mercurial > crates > nonstick

comparison libpam-sys/libpam-sys-helpers/src/memory.rs @ 136:efbc235f01d3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Separate libpam-sys-helpers from libpam-sys. This separates the parts of libpam-sys that don't need linking against libpam from the parts that do need to link against libpam.
author Paul Fisher <paul@pfish.zone>
date Thu, 03 Jul 2025 14:28:04 -0400
parents libpam-sys/src/helpers.rs@6c1e1bdb4164
children 33b9622ed6d2
comparison
equal deleted inserted replaced
135:b52594841480 136:efbc235f01d3
1 //! Helpers to deal with annoying memory management in the PAM API.
2 //!
3 //!
4
5 use std::error::Error;
6 use std::marker::{PhantomData, PhantomPinned};
7 use std::mem::ManuallyDrop;
8 use std::ptr::NonNull;
9 use std::{any, fmt, mem, slice};
10
11 /// A pointer-to-pointer-to-message container for PAM's conversation callback.
12 ///
13 /// The PAM conversation callback requires a pointer to a pointer of
14 /// `pam_message`s. Linux-PAM handles this differently than all other
15 /// PAM implementations (including the X/SSO PAM standard).
16 ///
17 /// X/SSO appears to specify a pointer-to-pointer-to-array:
18 ///
19 /// ```text
20 /// points to ┌────────────┐ ╔═ Message[] ═╗
21 /// messages ┄┄┄┄┄┄┄┄┄┄> │ *messages ┄┼┄┄┄┄┄> ║ style ║
22 /// └────────────┘ ║ data ┄┄┄┄┄┄┄╫┄┄> ...
23 /// ╟─────────────╢
24 /// ║ style ║
25 /// ║ data ┄┄┄┄┄┄┄╫┄┄> ...
26 /// ╟─────────────╢
27 /// ║ ... ║
28 /// ```
29 ///
30 /// whereas Linux-PAM uses an `**argv`-style pointer-to-array-of-pointers:
31 ///
32 /// ```text
33 /// points to ┌──────────────┐ ╔═ Message ═╗
34 /// messages ┄┄┄┄┄┄┄┄┄┄> │ messages[0] ┄┼┄┄┄┄> ║ style ║
35 /// │ messages[1] ┄┼┄┄┄╮ ║ data ┄┄┄┄┄╫┄┄> ...
36 /// │ ... │ ┆ ╚═══════════╝
37 /// ┆
38 /// ┆ ╔═ Message ═╗
39 /// ╰┄┄> ║ style ║
40 /// ║ data ┄┄┄┄┄╫┄┄> ...
41 /// ╚═══════════╝
42 /// ```
43 ///
44 /// Because the `messages` remain owned by the application which calls into PAM,
45 /// we can solve this with One Simple Trick: make the intermediate list point
46 /// into the same array:
47 ///
48 /// ```text
49 /// points to ┌──────────────┐ ╔═ Message[] ═╗
50 /// messages ┄┄┄┄┄┄┄┄┄┄> │ messages[0] ┄┼┄┄┄┄> ║ style ║
51 /// │ messages[1] ┄┼┄┄╮ ║ data ┄┄┄┄┄┄┄╫┄┄> ...
52 /// │ ... │ ┆ ╟─────────────╢
53 /// ╰┄> ║ style ║
54 /// ║ data ┄┄┄┄┄┄┄╫┄┄> ...
55 /// ╟─────────────╢
56 /// ║ ... ║
57 ///
58 /// ```
59 #[derive(Debug)]
60 pub struct PtrPtrVec<T> {
61 data: Vec<T>,
62 pointers: Vec<*const T>,
63 }
64
65 // Since this is a wrapper around a Vec with no dangerous functionality*,
66 // this can be Send and Sync provided the original Vec is.
67 //
68 // * It will only become unsafe when the user dereferences a pointer or sends it
69 // to an unsafe function.
70 unsafe impl<T> Send for PtrPtrVec<T> where Vec<T>: Send {}
71 unsafe impl<T> Sync for PtrPtrVec<T> where Vec<T>: Sync {}
72
73 impl<T> PtrPtrVec<T> {
74 /// Takes ownership of the given Vec and creates a vec of pointers to it.
75 pub fn new(data: Vec<T>) -> Self {
76 let pointers: Vec<_> = data.iter().map(|r| r as *const T).collect();
77 Self { data, pointers }
78 }
79
80 /// Gives you back your Vec.
81 pub fn into_inner(self) -> Vec<T> {
82 self.data
83 }
84
85 /// Gets a pointer-to-pointer suitable for passing into the Conversation.
86 pub fn as_ptr<Dest>(&self) -> *const *const Dest {
87 Self::assert_size::<Dest>();
88 self.pointers.as_ptr().cast::<*const Dest>()
89 }
90
91 /// Iterates over a Linux-PAM–style pointer-to-array-of-pointers.
92 ///
93 /// # Safety
94 ///
95 /// `ptr_ptr` must be a valid pointer to an array of pointers,
96 /// there must be at least `count` valid pointers in the array,
97 /// and each pointer in that array must point to a valid `T`.
98 #[deprecated = "use [`Self::iter_over`] instead, unless you really need this specific version"]
99 #[allow(dead_code)]
100 pub unsafe fn iter_over_linux<'a, Src>(
101 ptr_ptr: *const *const Src,
102 count: usize,
103 ) -> impl Iterator<Item = &'a T>
104 where
105 T: 'a,
106 {
107 Self::assert_size::<Src>();
108 slice::from_raw_parts(ptr_ptr.cast::<&T>(), count)
109 .iter()
110 .copied()
111 }
112
113 /// Iterates over an X/SSO–style pointer-to-pointer-to-array.
114 ///
115 /// # Safety
116 ///
117 /// You must pass a valid pointer to a valid pointer to an array,
118 /// there must be at least `count` elements in the array,
119 /// and each value in that array must be a valid `T`.
120 #[deprecated = "use [`Self::iter_over`] instead, unless you really need this specific version"]
121 #[allow(dead_code)]
122 pub unsafe fn iter_over_xsso<'a, Src>(
123 ptr_ptr: *const *const Src,
124 count: usize,
125 ) -> impl Iterator<Item = &'a T>
126 where
127 T: 'a,
128 {
129 Self::assert_size::<Src>();
130 slice::from_raw_parts(*ptr_ptr.cast(), count).iter()
131 }
132
133 /// Iterates over a PAM message list appropriate to your system's impl.
134 ///
135 /// This selects the correct pointer/array structure to use for a message
136 /// that was given to you by your system.
137 ///
138 /// # Safety
139 ///
140 /// `ptr_ptr` must point to a valid message list, there must be at least
141 /// `count` messages in the list, and all messages must be a valid `Src`.
142 #[allow(deprecated)]
143 pub unsafe fn iter_over<'a, Src>(
144 ptr_ptr: *const *const Src,
145 count: usize,
146 ) -> impl Iterator<Item = &'a T>
147 where
148 T: 'a,
149 {
150 #[cfg(pam_impl = "LinuxPam")]
151 return Self::iter_over_linux(ptr_ptr, count);
152 #[cfg(not(pam_impl = "LinuxPam"))]
153 return Self::iter_over_xsso(ptr_ptr, count);
154 }
155
156 fn assert_size<That>() {
157 debug_assert_eq!(
158 mem::size_of::<T>(),
159 mem::size_of::<That>(),
160 "type {t} is not the size of {that}",
161 t = any::type_name::<T>(),
162 that = any::type_name::<That>(),
163 );
164 }
165 }
166
167 /// Error returned when attempting to allocate a buffer that is too big.
168 ///
169 /// This is specifically used in [`OwnedBinaryPayload`] when you try to allocate
170 /// a message larger than 2<sup>32</sup> bytes.
171 #[derive(Debug, PartialEq)]
172 pub struct TooBigError {
173 pub size: usize,
174 pub max: usize,
175 }
176
177 impl Error for TooBigError {}
178
179 impl fmt::Display for TooBigError {
180 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
181 write!(
182 f,
183 "can't allocate a message of {size} bytes (max {max})",
184 size = self.size,
185 max = self.max
186 )
187 }
188 }
189
190 /// A trait wrapping memory management.
191 ///
192 /// This is intended to allow you to bring your own allocator for
193 /// [`OwnedBinaryPayload`]s.
194 ///
195 /// For an implementation example, see the implementation of this trait
196 /// for [`Vec`].
197 pub trait Buffer<T: Default> {
198 /// Allocates a buffer of `len` elements, filled with the default.
199 fn allocate(len: usize) -> Self;
200
201 fn as_ptr(&self) -> *const T;
202
203 /// Returns a slice view of `size` elements of the given memory.
204 ///
205 /// # Safety
206 ///
207 /// The caller must not request more elements than are allocated.
208 unsafe fn as_mut_slice(&mut self, len: usize) -> &mut [T];
209
210 /// Consumes this ownership and returns a pointer to the start of the arena.
211 fn into_ptr(self) -> NonNull<T>;
212
213 /// "Adopts" the memory at the given pointer, taking it under management.
214 ///
215 /// Running the operation:
216 ///
217 /// ```
218 /// # use libpam_sys_helpers::memory::Buffer;
219 /// # fn test<T: Default, OwnerType: Buffer<T>>(bytes: usize) {
220 /// let owner = OwnerType::allocate(bytes);
221 /// let ptr = owner.into_ptr();
222 /// let owner = unsafe { OwnerType::from_ptr(ptr, bytes) };
223 /// # }
224 /// ```
225 ///
226 /// must be a no-op.
227 ///
228 /// # Safety
229 ///
230 /// The pointer must be valid, and the caller must provide the exact size
231 /// of the given arena.
232 unsafe fn from_ptr(ptr: NonNull<T>, bytes: usize) -> Self;
233 }
234
235 impl<T: Default> Buffer<T> for Vec<T> {
236 fn allocate(bytes: usize) -> Self {
237 (0..bytes).map(|_| Default::default()).collect()
238 }
239
240 fn as_ptr(&self) -> *const T {
241 Vec::as_ptr(self)
242 }
243
244 unsafe fn as_mut_slice(&mut self, bytes: usize) -> &mut [T] {
245 debug_assert!(bytes <= self.len());
246 Vec::as_mut(self)
247 }
248
249 fn into_ptr(self) -> NonNull<T> {
250 let mut me = ManuallyDrop::new(self);
251 // SAFETY: a Vec is guaranteed to have a nonzero pointer.
252 unsafe { NonNull::new_unchecked(me.as_mut_ptr()) }
253 }
254
255 unsafe fn from_ptr(ptr: NonNull<T>, bytes: usize) -> Self {
256 Vec::from_raw_parts(ptr.as_ptr(), bytes, bytes)
257 }
258 }
259
260 /// The structure of the "binary message" payload for the `PAM_BINARY_PROMPT`
261 /// extension from Linux-PAM.
262 pub struct BinaryPayload {
263 /// The total byte size of the message, including this header,
264 /// as a u32 in network byte order (big endian).
265 pub total_bytes_u32be: [u8; 4],
266 /// A tag used to provide some kind of hint as to what the data is.
267 /// Its meaning is undefined.
268 pub data_type: u8,
269 /// Where the data itself would start, used as a marker to make this
270 /// not [`Unpin`] (since it is effectively an intrusive data structure
271 /// pointing to immediately after itself).
272 pub _marker: PhantomData<PhantomPinned>,
273 }
274
275 impl BinaryPayload {
276 /// The most data it's possible to put into a [`BinaryPayload`].
277 pub const MAX_SIZE: usize = (u32::MAX - 5) as usize;
278
279 /// Fills in the provided buffer with the given data.
280 ///
281 /// This uses [`copy_from_slice`](slice::copy_from_slice) internally,
282 /// so `buf` must be exactly 5 bytes longer than `data`, or this function
283 /// will panic.
284 pub fn fill(buf: &mut [u8], data_type: u8, data: &[u8]) {
285 let ptr: *mut Self = buf.as_mut_ptr().cast();
286 // SAFETY: We're given a slice, which always has a nonzero pointer.
287 let me = unsafe { ptr.as_mut().unwrap_unchecked() };
288 me.total_bytes_u32be = u32::to_be_bytes(buf.len() as u32);
289 me.data_type = data_type;
290 buf[5..].copy_from_slice(data)
291 }
292
293 /// The total storage needed for the message, including header.
294 pub fn total_bytes(&self) -> usize {
295 u32::from_be_bytes(self.total_bytes_u32be) as usize
296 }
297
298 /// Gets the total byte buffer of the BinaryMessage stored at the pointer.
299 ///
300 /// The returned data slice is borrowed from where the pointer points to.
301 ///
302 /// # Safety
303 ///
304 /// - The pointer must point to a valid `BinaryPayload`.
305 /// - The borrowed data must not outlive the pointer's validity.
306 pub unsafe fn buffer_of<'a>(ptr: *const Self) -> &'a [u8] {
307 let header: &Self = ptr.as_ref().unwrap_unchecked();
308 slice::from_raw_parts(ptr.cast(), header.total_bytes().max(5))
309 }
310
311 /// Gets the contents of the BinaryMessage stored at the given pointer.
312 ///
313 /// The returned data slice is borrowed from where the pointer points to.
314 /// This is a cheap operation and doesn't do *any* copying.
315 ///
316 /// We don't take a `&self` reference here because accessing beyond
317 /// the range of the `Self` data (i.e., beyond the 5 bytes of `self`)
318 /// is undefined behavior. Instead, you have to pass a raw pointer
319 /// directly to the data.
320 ///
321 /// # Safety
322 ///
323 /// - The pointer must point to a valid `BinaryPayload`.
324 /// - The borrowed data must not outlive the pointer's validity.
325 pub unsafe fn contents<'a>(ptr: *const Self) -> (u8, &'a [u8]) {
326 let header: &Self = ptr.as_ref().unwrap_unchecked();
327 (header.data_type, &Self::buffer_of(ptr)[5..])
328 }
329 }
330
331 /// A binary message owned by some storage.
332 ///
333 /// This is an owned, memory-managed version of [`BinaryPayload`].
334 /// The `O` type manages the memory where the payload lives.
335 /// [`Vec<u8>`] is one such manager and can be used when ownership
336 /// of the data does not need to transit through PAM.
337 #[derive(Debug)]
338 pub struct OwnedBinaryPayload<Owner: Buffer<u8>>(Owner);
339
340 impl<O: Buffer<u8>> OwnedBinaryPayload<O> {
341 /// Allocates a new OwnedBinaryPayload.
342 ///
343 /// This will return a [`TooBigError`] if you try to allocate too much
344 /// (more than [`BinaryPayload::MAX_SIZE`]).
345 pub fn new(data_type: u8, data: &[u8]) -> Result<Self, TooBigError> {
346 let total_len: u32 = (data.len() + 5).try_into().map_err(|_| TooBigError {
347 size: data.len(),
348 max: BinaryPayload::MAX_SIZE,
349 })?;
350 let total_len = total_len as usize;
351 let mut buf = O::allocate(total_len);
352 // SAFETY: We just allocated this exact size.
353 BinaryPayload::fill(unsafe { buf.as_mut_slice(total_len) }, data_type, data);
354 Ok(Self(buf))
355 }
356
357 /// The contents of the buffer.
358 pub fn contents(&self) -> (u8, &[u8]) {
359 unsafe { BinaryPayload::contents(self.as_ptr()) }
360 }
361
362 /// The total bytes needed to store this, including the header.
363 pub fn total_bytes(&self) -> usize {
364 unsafe { BinaryPayload::buffer_of(self.0.as_ptr().cast()).len() }
365 }
366
367 /// Unwraps this into the raw storage backing it.
368 pub fn into_inner(self) -> O {
369 self.0
370 }
371
372 /// Gets a const pointer to the start of the message's buffer.
373 pub fn as_ptr(&self) -> *const BinaryPayload {
374 self.0.as_ptr().cast()
375 }
376
377 /// Consumes ownership of this message and converts it to a raw pointer
378 /// to the start of the message.
379 ///
380 /// To clean this up, you should eventually pass it into [`Self::from_ptr`]
381 /// with the same `O` ownership type.
382 pub fn into_ptr(self) -> NonNull<BinaryPayload> {
383 self.0.into_ptr().cast()
384 }
385
386 /// Takes ownership of the given pointer.
387 ///
388 /// # Safety
389 ///
390 /// You must provide a valid pointer, allocated by (or equivalent to one
391 /// allocated by) [`Self::new`]. For instance, passing a pointer allocated
392 /// by `malloc` to `OwnedBinaryPayload::<Vec<u8>>::from_ptr` is not allowed.
393 pub unsafe fn from_ptr(ptr: NonNull<BinaryPayload>) -> Self {
394 Self(O::from_ptr(ptr.cast(), ptr.as_ref().total_bytes()))
395 }
396 }
397
398 #[cfg(test)]
399 mod tests {
400 use super::*;
401 use std::ptr;
402
403 type VecPayload = OwnedBinaryPayload<Vec<u8>>;
404
405 #[test]
406 fn test_binary_payload() {
407 let simple_message = &[0u8, 0, 0, 16, 0xff, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
408 let empty = &[0u8; 5];
409
410 assert_eq!((0xff, &[0u8, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10][..]), unsafe {
411 BinaryPayload::contents(simple_message.as_ptr().cast())
412 });
413 assert_eq!((0x00, &[][..]), unsafe {
414 BinaryPayload::contents(empty.as_ptr().cast())
415 });
416 }
417
418 #[test]
419 fn test_owned_binary_payload() {
420 let (typ, data) = (
421 112,
422 &[0, 1, 1, 8, 9, 9, 9, 8, 8, 1, 9, 9, 9, 1, 1, 9, 7, 2, 5, 3][..],
423 );
424 let payload = VecPayload::new(typ, data).unwrap();
425 assert_eq!((typ, data), payload.contents());
426 let ptr = payload.into_ptr();
427 let payload = unsafe { VecPayload::from_ptr(ptr) };
428 assert_eq!((typ, data), payload.contents());
429 }
430
431 #[test]
432 #[ignore]
433 fn test_owned_too_big() {
434 let data = vec![0xFFu8; 0x1_0000_0001];
435 assert_eq!(
436 TooBigError {
437 max: 0xffff_fffa,
438 size: 0x1_0000_0001
439 },
440 VecPayload::new(5, &data).unwrap_err()
441 )
442 }
443
444 #[cfg(debug_assertions)]
445 #[test]
446 #[should_panic]
447 fn test_new_wrong_size() {
448 let bad_vec = vec![0; 19];
449 let msg = PtrPtrVec::new(bad_vec);
450 let _ = msg.as_ptr::<u64>();
451 }
452
453 #[allow(deprecated)]
454 #[cfg(debug_assertions)]
455 #[test]
456 #[should_panic]
457 fn test_iter_xsso_wrong_size() {
458 unsafe {
459 let _ = PtrPtrVec::<u8>::iter_over_xsso::<f64>(ptr::null(), 1);
460 }
461 }
462
463 #[allow(deprecated)]
464 #[cfg(debug_assertions)]
465 #[test]
466 #[should_panic]
467 fn test_iter_linux_wrong_size() {
468 unsafe {
469 let _ = PtrPtrVec::<u128>::iter_over_linux::<()>(ptr::null(), 1);
470 }
471 }
472
473 #[allow(deprecated)]
474 #[test]
475 fn test_right_size() {
476 let good_vec = vec![(1u64, 2u64), (3, 4), (5, 6)];
477 let ptr = good_vec.as_ptr();
478 let msg = PtrPtrVec::new(good_vec);
479 let msg_ref: *const *const (i64, i64) = msg.as_ptr();
480 assert_eq!(unsafe { *msg_ref }, ptr.cast());
481
482 let linux_result: Vec<(i64, i64)> = unsafe { PtrPtrVec::iter_over_linux(msg_ref, 3) }
483 .cloned()
484 .collect();
485 let xsso_result: Vec<(i64, i64)> = unsafe { PtrPtrVec::iter_over_xsso(msg_ref, 3) }
486 .cloned()
487 .collect();
488 assert_eq!(vec![(1, 2), (3, 4), (5, 6)], linux_result);
489 assert_eq!(vec![(1, 2), (3, 4), (5, 6)], xsso_result);
490 drop(msg)
491 }
492
493 #[allow(deprecated)]
494 #[test]
495 fn test_iter_ptr_ptr() {
496 let strs = vec![Box::new("a"), Box::new("b"), Box::new("c"), Box::new("D")];
497 let ptr: *const *const &str = strs.as_ptr().cast();
498 let got: Vec<&str> = unsafe { PtrPtrVec::iter_over_linux(ptr, 4) }
499 .cloned()
500 .collect();
501 assert_eq!(vec!["a", "b", "c", "D"], got);
502
503 let nums = [-1i8, 2, 3];
504 let ptr = nums.as_ptr();
505 let got: Vec<u8> = unsafe { PtrPtrVec::iter_over_xsso(&ptr, 3) }
506 .cloned()
507 .collect();
508 assert_eq!(vec![255, 2, 3], got);
509 }
510 }