Mercurial > crates > nonstick

annotate libpam-sys/src/structs.rs @ 117:20f7712a6857

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Neaten up libpam-sys BinaryPayload buffer management.
author Paul Fisher <paul@pfish.zone>
date Sun, 29 Jun 2025 18:48:14 -0400
parents bb465393621f
children 39760dfc9b3b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
1 use core::marker::{PhantomData, PhantomPinned};
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
2 use core::slice;
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
3
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
4 /// The structure of the "binary message" payload for the `PAM_BINARY_PROMPT`
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
5 /// extension from Linux-PAM.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
6 pub struct BinaryPayload {
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
7 /// The total byte size of the message, including this header,
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
8 /// as a u32 in network byte order (big endian).
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
9 pub total_bytes_u32be: [u8; 4],
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
10 /// A tag used to provide some kind of hint as to what the data is.
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
11 /// Its meaning is undefined.
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
12 pub data_type: u8,
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
13 /// Where the data itself would start, used as a marker to make this
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
14 /// not [`Unpin`] (since it is effectively an intrusive data structure
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
15 /// pointing to immediately after itself).
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
16 pub _marker: PhantomData<PhantomPinned>,
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
17 }
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
18
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
19 impl BinaryPayload {
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
20 /// The most data it's possible to put into a [`BinaryPayload`].
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
21 pub const MAX_SIZE: usize = (u32::MAX - 5) as usize;
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
22
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
23 /// Fills in the provided buffer with the given data.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
24 ///
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
25 /// This uses [`copy_from_slice`](slice::copy_from_slice) internally,
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
26 /// so `buf` must be exactly 5 bytes longer than `data`, or this function
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
27 /// will panic.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
28 pub fn fill(buf: &mut [u8], data_type: u8, data: &[u8]) {
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
29 let ptr: *mut Self = buf.as_mut_ptr().cast();
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
30 // SAFETY: We're given a slice, which always has a nonzero pointer.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
31 let me = unsafe { ptr.as_mut().unwrap_unchecked() };
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
32 me.total_bytes_u32be = u32::to_be_bytes(buf.len() as u32);
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
33 me.data_type = data_type;
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
34 buf[5..].copy_from_slice(data)
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
35 }
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
36
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
37 /// The total storage needed for the message, including header.
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
38 pub fn total_bytes(&self) -> usize {
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
39 u32::from_be_bytes(self.total_bytes_u32be) as usize
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
40 }
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
41
117
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
42 /// Gets the total byte buffer of the BinaryMessage stored at the pointer.
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
43 ///
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
44 /// The returned data slice is borrowed from where the pointer points to.
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
45 ///
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
46 /// # Safety
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
47 ///
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
48 /// - The pointer must point to a valid `BinaryPayload`.
117
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
49 /// - The borrowed data must not outlive the pointer's validity.
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
50 pub unsafe fn buffer_of<'a>(ptr: *const Self) -> &'a [u8] {
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
51 let header: &Self = ptr.as_ref().unwrap_unchecked();
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
52 slice::from_raw_parts(ptr.cast(), header.total_bytes().max(5))
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
53 }
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
54
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
55 /// Gets the contents of the BinaryMessage stored at the given pointer.
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
56 ///
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
57 /// The returned data slice is borrowed from where the pointer points to.
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
58 /// This is a cheap operation and doesn't do *any* copying.
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
59 ///
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
60 /// We don't take a `&self` reference here because accessing beyond
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
61 /// the range of the `Self` data (i.e., beyond the 5 bytes of `self`)
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
62 /// is undefined behavior. Instead, you have to pass a raw pointer
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
63 /// directly to the data.
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
64 ///
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
65 /// # Safety
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
66 ///
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
67 /// - The pointer must point to a valid `BinaryPayload`.
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
68 /// - The borrowed data must not outlive the pointer's validity.
109
bb465393621f Minor cleanup and reorg.
Paul Fisher <paul@pfish.zone>
parents: 106
diff changeset
69 pub unsafe fn contents<'a>(ptr: *const Self) -> (u8, &'a [u8]) {
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
70 let header: &Self = ptr.as_ref().unwrap_unchecked();
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
71 (
117
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
72 header.data_type,
20f7712a6857 Neaten up libpam-sys BinaryPayload buffer management.
Paul Fisher <paul@pfish.zone>
parents: 109
diff changeset
73 &Self::buffer_of(ptr)[5..]
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
74 )
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
75 }
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
76 }