Mercurial > crates > nonstick

comparison src/module.rs @ 45:ce47901aab7a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Rename to “nonstick”, move to root, update docs and license. - Renames the crate to “nonstick”. - Moves the main library to the root of the repository. - Removes the example PAM modules. - Updates copyright information in LICENSE file. - Updates the README.
author Paul Fisher <paul@pfish.zone>
date Tue, 15 Apr 2025 00:50:23 -0400
parents pam/src/module.rs@50371046c61a
children a921b72743e4
comparison
equal deleted inserted replaced
44:50371046c61a 45:ce47901aab7a
1 //! Functions for use in pam modules.
2
3 use libc::c_char;
4 use std::ffi::{CStr, CString};
5
6 use constants::{PamFlag, PamResultCode};
7 use items::ItemType;
8
9 /// Opaque type, used as a pointer when making pam API calls.
10 ///
11 /// A module is invoked via an external function such as `pam_sm_authenticate`.
12 /// Such a call provides a pam handle pointer. The same pointer should be given
13 /// as an argument when making API calls.
14 #[repr(C)]
15 pub struct PamHandle {
16 _data: [u8; 0],
17 }
18
19 #[link(name = "pam")]
20 extern "C" {
21 fn pam_get_data(
22 pamh: *const PamHandle,
23 module_data_name: *const c_char,
24 data: &mut *const libc::c_void,
25 ) -> PamResultCode;
26
27 fn pam_set_data(
28 pamh: *const PamHandle,
29 module_data_name: *const c_char,
30 data: *mut libc::c_void,
31 cleanup: extern "C" fn(
32 pamh: *const PamHandle,
33 data: *mut libc::c_void,
34 error_status: PamResultCode,
35 ),
36 ) -> PamResultCode;
37
38 fn pam_get_item(
39 pamh: *const PamHandle,
40 item_type: ItemType,
41 item: &mut *const libc::c_void,
42 ) -> PamResultCode;
43
44 fn pam_set_item(
45 pamh: *mut PamHandle,
46 item_type: ItemType,
47 item: *const libc::c_void,
48 ) -> PamResultCode;
49
50 fn pam_get_user(
51 pamh: *const PamHandle,
52 user: &*mut c_char,
53 prompt: *const c_char,
54 ) -> PamResultCode;
55
56 fn pam_get_authtok(
57 pamh: *const PamHandle,
58 item_type: ItemType,
59 data: &*mut c_char,
60 prompt: *const c_char,
61 ) -> PamResultCode;
62
63 }
64
65 pub extern "C" fn cleanup<T>(_: *const PamHandle, c_data: *mut libc::c_void, _: PamResultCode) {
66 unsafe {
67 let _data: Box<T> = Box::from_raw(c_data.cast::<T>());
68 }
69 }
70
71 pub type PamResult<T> = Result<T, PamResultCode>;
72
73 impl PamHandle {
74 /// Gets some value, identified by `key`, that has been set by the module
75 /// previously.
76 ///
77 /// See the [`pam_get_data` manual page](
78 /// https://www.man7.org/linux/man-pages/man3/pam_get_data.3.html).
79 ///
80 /// # Errors
81 ///
82 /// Returns an error if the underlying PAM function call fails.
83 ///
84 /// # Safety
85 ///
86 /// The data stored under the provided key must be of type `T` otherwise the
87 /// behaviour of this function is undefined.
88 pub unsafe fn get_data<T>(&self, key: &str) -> PamResult<&T> {
89 let c_key = CString::new(key).unwrap();
90 let mut ptr: *const libc::c_void = std::ptr::null();
91 let res = pam_get_data(self, c_key.as_ptr(), &mut ptr);
92 if PamResultCode::PAM_SUCCESS == res && !ptr.is_null() {
93 let typed_ptr = ptr.cast::<T>();
94 let data: &T = &*typed_ptr;
95 Ok(data)
96 } else {
97 Err(res)
98 }
99 }
100
101 /// Stores a value that can be retrieved later with `get_data`. The value lives
102 /// as long as the current pam cycle.
103 ///
104 /// See the [`pam_set_data` manual page](
105 /// https://www.man7.org/linux/man-pages/man3/pam_set_data.3.html).
106 ///
107 /// # Errors
108 ///
109 /// Returns an error if the underlying PAM function call fails.
110 pub fn set_data<T>(&self, key: &str, data: Box<T>) -> PamResult<()> {
111 let c_key = CString::new(key).unwrap();
112 let res = unsafe {
113 pam_set_data(
114 self,
115 c_key.as_ptr(),
116 Box::into_raw(data).cast::<libc::c_void>(),
117 cleanup::<T>,
118 )
119 };
120 to_result(res)
121 }
122
123 /// Retrieves a value that has been set, possibly by the pam client. This is
124 /// particularly useful for getting a `PamConv` reference.
125 ///
126 /// See the [`pam_get_item` manual page](
127 /// https://www.man7.org/linux/man-pages/man3/pam_get_item.3.html).
128 ///
129 /// # Errors
130 ///
131 /// Returns an error if the underlying PAM function call fails.
132 pub fn get_item<T: crate::items::Item>(&self) -> PamResult<Option<T>> {
133 let mut ptr: *const libc::c_void = std::ptr::null();
134 let (res, item) = unsafe {
135 let r = pam_get_item(self, T::type_id(), &mut ptr);
136 let typed_ptr = ptr.cast::<T::Raw>();
137 let t = if typed_ptr.is_null() {
138 None
139 } else {
140 Some(T::from_raw(typed_ptr))
141 };
142 (r, t)
143 };
144 match res {
145 PamResultCode::PAM_SUCCESS => Ok(item),
146 other => Err(other),
147 }
148 }
149
150 /// Sets a value in the pam context. The value can be retrieved using
151 /// `get_item`.
152 ///
153 /// Note that all items are strings, except `PAM_CONV` and `PAM_FAIL_DELAY`.
154 ///
155 /// See the [`pam_set_item` manual page](
156 /// https://www.man7.org/linux/man-pages/man3/pam_set_item.3.html).
157 ///
158 /// # Errors
159 ///
160 /// Returns an error if the underlying PAM function call fails.
161 ///
162 /// # Panics
163 ///
164 /// Panics if the provided item key contains a nul byte.
165 pub fn set_item_str<T: crate::items::Item>(&mut self, item: T) -> PamResult<()> {
166 let res =
167 unsafe { pam_set_item(self, T::type_id(), item.into_raw().cast::<libc::c_void>()) };
168 to_result(res)
169 }
170
171 /// Retrieves the name of the user who is authenticating or logging in.
172 ///
173 /// This is really a specialization of `get_item`.
174 ///
175 /// See the [`pam_get_user` manual page](
176 /// https://www.man7.org/linux/man-pages/man3/pam_get_user.3.html).
177 ///
178 /// # Errors
179 ///
180 /// Returns an error if the underlying PAM function call fails.
181 ///
182 /// # Panics
183 ///
184 /// Panics if the provided prompt string contains a nul byte.
185 pub fn get_user(&self, prompt: Option<&str>) -> PamResult<String> {
186 let prompt_string;
187 let c_prompt = match prompt {
188 Some(p) => {
189 prompt_string = CString::new(p).unwrap();
190 prompt_string.as_ptr()
191 }
192 None => std::ptr::null(),
193 };
194 let output: *mut c_char = std::ptr::null_mut();
195 let res = unsafe { pam_get_user(self, &output, c_prompt) };
196 match res {
197 PamResultCode::PAM_SUCCESS => copy_pam_string(output),
198 otherwise => Err(otherwise),
199 }
200 }
201
202 /// Retrieves the authentication token from the user.
203 ///
204 /// This is really a specialization of `get_item`.
205 ///
206 /// See the [`pam_get_authtok` manual page](
207 /// https://www.man7.org/linux/man-pages/man3/pam_get_authtok.3.html).
208 ///
209 /// # Errors
210 ///
211 /// Returns an error if the underlying PAM function call fails.
212 ///
213 /// # Panics
214 ///
215 /// Panics if the provided prompt string contains a nul byte.
216 pub fn get_authtok(&self, prompt: Option<&str>) -> PamResult<String> {
217 let prompt_string;
218 let c_prompt = match prompt {
219 Some(p) => {
220 prompt_string = CString::new(p).unwrap();
221 prompt_string.as_ptr()
222 }
223 None => std::ptr::null(),
224 };
225 let output: *mut c_char = std::ptr::null_mut();
226 let res = unsafe { pam_get_authtok(self, ItemType::AuthTok, &output, c_prompt) };
227 match res {
228 PamResultCode::PAM_SUCCESS => copy_pam_string(output),
229 otherwise => Err(otherwise),
230 }
231 }
232 }
233
234 /// Creates an owned copy of a string that is returned from a
235 /// <code>pam_get_<var>whatever</var></code> function.
236 fn copy_pam_string(result_ptr: *const c_char) -> PamResult<String> {
237 // We really shouldn't get a null pointer back here, but if we do, return nothing.
238 if result_ptr.is_null() {
239 return Ok(String::from(""));
240 }
241 let bytes = unsafe { CStr::from_ptr(result_ptr).to_bytes() };
242 String::from_utf8(bytes.to_vec()).map_err(|_| PamResultCode::PAM_CONV_ERR)
243 }
244
245 /// Convenience to transform a `PamResultCode` into a unit `PamResult`.
246 fn to_result(result: PamResultCode) -> PamResult<()> {
247 match result {
248 PamResultCode::PAM_SUCCESS => Ok(()),
249 otherwise => Err(otherwise),
250 }
251 }
252
253 /// Provides functions that are invoked by the entrypoints generated by the
254 /// [`pam_hooks!` macro](../macro.pam_hooks.html).
255 ///
256 /// All hooks are ignored by PAM dispatch by default given the default return value of `PAM_IGNORE`.
257 /// Override any functions that you want to handle with your module. See [PAM’s root manual page](
258 /// https://www.man7.org/linux/man-pages/man3/pam.3.html).
259 #[allow(unused_variables)]
260 pub trait PamHooks {
261 /// This function performs the task of establishing whether the user is permitted to gain access at
262 /// this time. It should be understood that the user has previously been validated by an
263 /// authentication module. This function checks for other things. Such things might be: the time of
264 /// day or the date, the terminal line, remote hostname, etc. This function may also determine
265 /// things like the expiration on passwords, and respond that the user change it before continuing.
266 fn acct_mgmt(pamh: &mut PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
267 PamResultCode::PAM_IGNORE
268 }
269
270 /// This function performs the task of authenticating the user.
271 fn sm_authenticate(pamh: &mut PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
272 PamResultCode::PAM_IGNORE
273 }
274
275 /// This function is used to (re-)set the authentication token of the user.
276 ///
277 /// The PAM library calls this function twice in succession. The first time with
278 /// `PAM_PRELIM_CHECK` and then, if the module does not return `PAM_TRY_AGAIN`, subsequently with
279 /// `PAM_UPDATE_AUTHTOK`. It is only on the second call that the authorization token is
280 /// (possibly) changed.
281 fn sm_chauthtok(pamh: &mut PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
282 PamResultCode::PAM_IGNORE
283 }
284
285 /// This function is called to terminate a session.
286 fn sm_close_session(pamh: &mut PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
287 PamResultCode::PAM_IGNORE
288 }
289
290 /// This function is called to commence a session.
291 fn sm_open_session(pamh: &mut PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
292 PamResultCode::PAM_IGNORE
293 }
294
295 /// This function performs the task of altering the credentials of the user with respect to the
296 /// corresponding authorization scheme. Generally, an authentication module may have access to more
297 /// information about a user than their authentication token. This function is used to make such
298 /// information available to the application. It should only be called after the user has been
299 /// authenticated but before a session has been established.
300 fn sm_setcred(pamh: &mut PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
301 PamResultCode::PAM_IGNORE
302 }
303 }