Mercurial > crates > nonstick

annotate src/libpam/pam_ffi.rs @ 103:dfcd96a74ac4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
write a truly prodigious amount of documentation adds a bunch of links to the OpenPAM man pages and the XSSO spec as well as just a bunch of prose and stuff.
author Paul Fisher <paul@pfish.zone>
date Wed, 25 Jun 2025 00:59:24 -0400
parents 94eb11cb1798
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
1 //! The types that are directly represented in PAM function signatures.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
2
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 90
diff changeset
3 #![allow(non_camel_case_types, non_upper_case_globals)]
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
4
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
5 use crate::libpam::memory::{CHeapBox, Immovable};
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
6 use std::ffi::{c_int, c_uint, c_void, CStr};
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
7 use std::marker::PhantomData;
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
8 use std::ptr;
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
9
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
10 /// An opaque structure that a PAM handle points to.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
11 #[repr(C)]
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
12 pub struct LibPamHandle {
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
13 _data: (),
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
14 _marker: Immovable,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
15 }
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
16
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
17 /// An opaque structure that is passed through PAM in a conversation.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
18 #[repr(C)]
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
19 pub struct AppData {
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
20 _data: (),
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
21 _marker: Immovable,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
22 }
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
23
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
24 /// Generic version of answer data.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
25 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
26 /// This has the same structure as [`BinaryAnswer`](crate::libpam::answer::BinaryAnswer)
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
27 /// and [`TextAnswer`](crate::libpam::answer::TextAnswer).
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
28 #[repr(C)]
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
29 #[derive(Debug, Default)]
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
30 pub struct Answer {
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
31 /// Owned pointer to the data returned in an answer.
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 102
diff changeset
32 /// For most answers, this will be a
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 102
diff changeset
33 /// [`CHeapString`](crate::libpam::memory::CHeapString),
102
94eb11cb1798 Improve documentation for pam_start.
Paul Fisher <paul@pfish.zone>
parents: 101
diff changeset
34 /// but for [`BinaryQAndA`](crate::conv::BinaryQAndA)s
94eb11cb1798 Improve documentation for pam_start.
Paul Fisher <paul@pfish.zone>
parents: 101
diff changeset
35 /// (a Linux-PAM extension), this will be a [`CHeapBox`] of
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
36 /// [`CBinaryData`](crate::libpam::memory::CBinaryData).
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
37 pub data: Option<CHeapBox<c_void>>,
89
dd3e9c4bcde3 Simplify memory management in Questions.
Paul Fisher <paul@pfish.zone>
parents: 87
diff changeset
38 /// Unused. Just here for the padding.
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
39 return_code: c_int,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
40 _marker: Immovable,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
41 }
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
42
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
43 /// A question sent by PAM or a module to an application.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
44 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
45 /// PAM refers to this as a "message", but we call it a question
89
dd3e9c4bcde3 Simplify memory management in Questions.
Paul Fisher <paul@pfish.zone>
parents: 87
diff changeset
46 /// to avoid confusion with [`Message`](crate::conv::Message).
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
47 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
48 /// This question, and its internal data, is owned by its creator
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
49 /// (either the module or PAM itself).
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
50 #[repr(C)]
89
dd3e9c4bcde3 Simplify memory management in Questions.
Paul Fisher <paul@pfish.zone>
parents: 87
diff changeset
51 #[derive(Debug)]
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
52 pub struct Question {
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
53 /// The style of message to request.
87
05291b601f0a Well and truly separate the Linux extensions.
Paul Fisher <paul@pfish.zone>
parents: 81
diff changeset
54 pub style: c_uint,
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
55 /// A description of the data requested.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
56 ///
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
57 /// For most requests, this will be an owned [`CStr`],
89
dd3e9c4bcde3 Simplify memory management in Questions.
Paul Fisher <paul@pfish.zone>
parents: 87
diff changeset
58 /// but for requests with style `PAM_BINARY_PROMPT`,
dd3e9c4bcde3 Simplify memory management in Questions.
Paul Fisher <paul@pfish.zone>
parents: 87
diff changeset
59 /// this will be `CBinaryData` (a Linux-PAM extension).
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
60 pub data: Option<CHeapBox<c_void>>,
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
61 }
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
62
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
63 /// The callback that PAM uses to get information in a conversation.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
64 ///
89
dd3e9c4bcde3 Simplify memory management in Questions.
Paul Fisher <paul@pfish.zone>
parents: 87
diff changeset
65 /// - `num_msg` is the number of messages in the `questions` array.
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
66 /// - `questions` is a pointer to the [`Question`]s being sent to the user.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
67 /// For information about its structure,
89
dd3e9c4bcde3 Simplify memory management in Questions.
Paul Fisher <paul@pfish.zone>
parents: 87
diff changeset
68 /// see [`QuestionsTrait`](super::question::QuestionsTrait).
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
69 /// - `answers` is a pointer to an array of [`Answer`]s,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
70 /// which PAM sets in response to a module's request.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
71 /// This is an array of structs, not an array of pointers to a struct.
89
dd3e9c4bcde3 Simplify memory management in Questions.
Paul Fisher <paul@pfish.zone>
parents: 87
diff changeset
72 /// There must always be exactly as many `answers` as `num_msg`.
dd3e9c4bcde3 Simplify memory management in Questions.
Paul Fisher <paul@pfish.zone>
parents: 87
diff changeset
73 /// - `appdata` is the `appdata` field of the [`LibPamConversation`].
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
74 pub type ConversationCallback = unsafe extern "C" fn(
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
75 num_msg: c_int,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
76 questions: *const *const Question,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
77 answers: *mut *mut Answer,
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
78 appdata: *const AppData,
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
79 ) -> c_int;
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
81 /// The type used by PAM to call back into a conversation.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
82 #[repr(C)]
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
83 pub struct LibPamConversation<'a> {
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
84 /// The function that is called to get information from the user.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
85 pub callback: ConversationCallback,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
86 /// The pointer that will be passed as the last parameter
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
87 /// to the conversation callback.
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
88 pub appdata: *const AppData,
101
94b51fa4f797 Fix memory soundness issues:
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
89 /// Marker to associate the lifetime of this with the conversation
94b51fa4f797 Fix memory soundness issues:
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
90 /// that was passed in.
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
91 pub life: PhantomData<&'a mut ()>,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
92 }
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
93
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
94 /// Gets a string version of an error message.
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
95 pub fn strerror(code: c_uint) -> Option<&'static str> {
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
96 // SAFETY: Every single PAM implementation I can find (Linux-PAM, OpenPAM,
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
97 // Solaris, etc.) returns a static string and ignores the handle value.
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
98 let strerror = unsafe { pam_strerror(ptr::null_mut(), code as c_int) };
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
99 if strerror.is_null() {
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
100 None
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
101 } else {
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
102 unsafe { CStr::from_ptr(strerror) }.to_str().ok()
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
103 }
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
104 }
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 89
diff changeset
105
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
106 type pam_handle = LibPamHandle;
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
107 type pam_conv = LibPamConversation<'static>;
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
108
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
109 include!(concat!(env!("OUT_DIR"), "/bindings.rs"));