limes-common 0.3.0

Shared authentication, config, events, and errors for limes crates.
Documentation
use std::cell::UnsafeCell;
use std::ffi::CStr;
use std::ptr;

use limes_proto::AuthFailure;

use crate::auth::AuthSession;
use crate::auth::pam::conversation::PamConversation;
use crate::auth::pam::raw as pam;
use crate::auth::pam::status::{map_auth_status, pam_error};
use crate::{LimesError, Result};

type PamCall = unsafe extern "C" fn(*mut pam::PamHandle, libc::c_int) -> libc::c_int;

#[derive(Clone, Copy)]
struct CleanupCalls {
    close: PamCall,
    credentials: PamCall,
    end: PamCall,
}

pub(super) struct PamSession {
    handle: *mut pam::PamHandle,
    // PAM owns a callback pointer into this stable allocation. Interior
    // mutability permits callback access while Rust owns the surrounding box.
    conversation: Box<UnsafeCell<PamConversation>>,
    opened: bool,
    credentials_established: bool,
    last_status: i32,
    cleanup: CleanupCalls,
}

// The handle and callback state have one owner and are never accessed concurrently.
unsafe impl Send for PamSession {}

impl PamSession {
    pub(super) fn new(
        handle: *mut pam::PamHandle,
        conversation: Box<UnsafeCell<PamConversation>>,
    ) -> Self {
        Self {
            handle,
            conversation,
            opened: false,
            credentials_established: false,
            last_status: pam::PAM_SUCCESS,
            cleanup: CleanupCalls {
                close: pam::pam_close_session,
                credentials: pam::pam_setcred,
                end: pam::pam_end,
            },
        }
    }

    pub(super) fn handle(&self) -> *mut pam::PamHandle {
        self.handle
    }

    /// Called after returning from PAM, never from a C callback.
    pub(super) fn record_status(&mut self, status: i32) {
        self.last_status = status;
        // No PAM call is active now; the callback cannot concurrently borrow it.
        unsafe { &mut *self.conversation.get() }.dispatch_messages();
    }

    pub(super) fn establish_credentials(&mut self) -> std::result::Result<(), AuthFailure> {
        let status = unsafe { pam::pam_setcred(self.handle, pam::PAM_ESTABLISH_CRED) };
        self.credentials_established = status == pam::PAM_SUCCESS;
        self.record_status(status);
        if status != pam::PAM_SUCCESS {
            return Err(map_auth_status(status, self.handle));
        }
        unsafe { &mut *self.conversation.get() }.clear_password();
        Ok(())
    }

    fn env(&self) -> Vec<(String, String)> {
        let mut out = Vec::new();
        let envp = unsafe { pam::pam_getenvlist(self.handle) };
        if envp.is_null() {
            return out;
        }
        let mut cursor = envp;
        loop {
            let item = unsafe { *cursor };
            if item.is_null() {
                break;
            }
            let value = unsafe { CStr::from_ptr(item) }.to_string_lossy();
            if let Some((key, value)) = value.split_once('=') {
                out.push((key.to_owned(), value.to_owned()));
            }
            unsafe { libc::free(item.cast()) };
            cursor = unsafe { cursor.add(1) };
        }
        unsafe { libc::free(envp.cast()) };
        out
    }
}

impl AuthSession for PamSession {
    fn open(&mut self) -> Result<Vec<(String, String)>> {
        if self.handle.is_null() || self.opened {
            return Err(LimesError::Auth(
                "PAM transaction is closed or already opened".to_owned(),
            ));
        }
        let status = unsafe { pam::pam_open_session(self.handle, 0) };
        self.opened = status == pam::PAM_SUCCESS;
        self.record_status(status);
        if status != pam::PAM_SUCCESS {
            return Err(LimesError::Auth(pam_error(self.handle, status)));
        }
        Ok(self.env())
    }

    fn close(&mut self) -> Result<()> {
        // Invalidate first: pam_end consumes the handle even when it reports failure.
        let handle = std::mem::replace(&mut self.handle, ptr::null_mut());
        if handle.is_null() {
            return Ok(());
        }
        // pam_end reports the transaction outcome to module cleanup callbacks;
        // successful credential deletion must not erase an earlier PAM failure.
        let transaction_status = self.last_status;
        let mut failures = Vec::new();
        if std::mem::take(&mut self.opened) {
            let status = unsafe { (self.cleanup.close)(handle, 0) };
            self.record_status(status);
            if status != pam::PAM_SUCCESS {
                failures.push(format!("pam_close_session failed (PAM status {status})"));
            }
        }
        if std::mem::take(&mut self.credentials_established) {
            let status = unsafe { (self.cleanup.credentials)(handle, pam::PAM_DELETE_CRED) };
            self.record_status(status);
            if status != pam::PAM_SUCCESS {
                failures.push(format!(
                    "pam_setcred(PAM_DELETE_CRED) failed (PAM status {status})"
                ));
            }
        }
        let status = unsafe { (self.cleanup.end)(handle, transaction_status) };
        self.record_status(status);
        unsafe { &mut *self.conversation.get() }.clear_password();
        if status != pam::PAM_SUCCESS {
            failures.push(format!("pam_end failed (PAM status {status})"));
        }
        if failures.is_empty() {
            Ok(())
        } else {
            Err(LimesError::Auth(failures.join("; ")))
        }
    }
}

impl Drop for PamSession {
    fn drop(&mut self) {
        let _ = self.close();
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::ffi::CString;

    #[derive(Default)]
    struct Calls {
        calls: Vec<&'static str>,
        fail: bool,
        end_status: Option<i32>,
    }
    unsafe extern "C" fn close(handle: *mut pam::PamHandle, _: i32) -> i32 {
        let state = unsafe { &mut *handle.cast::<Calls>() };
        state.calls.push("close");
        if state.fail {
            pam::PAM_PERM_DENIED
        } else {
            pam::PAM_SUCCESS
        }
    }
    unsafe extern "C" fn credentials(handle: *mut pam::PamHandle, flags: i32) -> i32 {
        let state = unsafe { &mut *handle.cast::<Calls>() };
        assert_eq!(flags, pam::PAM_DELETE_CRED);
        state.calls.push("deletecred");
        if state.fail {
            pam::PAM_PERM_DENIED
        } else {
            pam::PAM_SUCCESS
        }
    }
    unsafe extern "C" fn end(handle: *mut pam::PamHandle, status: i32) -> i32 {
        let state = unsafe { &mut *handle.cast::<Calls>() };
        state.calls.push("end");
        state.end_status = Some(status);
        if state.fail {
            pam::PAM_PERM_DENIED
        } else {
            pam::PAM_SUCCESS
        }
    }
    fn session(state: &mut Calls) -> PamSession {
        let conversation = Box::new(UnsafeCell::new(PamConversation::new(
            CString::new("alice").unwrap(),
            "alice".into(),
            None,
            None,
        )));
        let mut session = PamSession::new((state as *mut Calls).cast(), conversation);
        session.cleanup = CleanupCalls {
            close,
            credentials,
            end,
        };
        session
    }
    #[test]
    fn cleanup_attempts_every_step_once_in_order_despite_failures() {
        let mut calls = Calls {
            fail: true,
            ..Calls::default()
        };
        let mut session = session(&mut calls);
        session.opened = true;
        session.credentials_established = true;
        let error = session.close().unwrap_err().to_string();
        assert!(error.contains("pam_close_session"));
        assert!(error.contains("PAM_DELETE_CRED"));
        assert!(error.contains("pam_end"));
        assert!(session.handle.is_null());
        session.close().unwrap();
        drop(session);
        assert_eq!(calls.calls, vec!["close", "deletecred", "end"]);
    }
    #[test]
    fn cleanup_preserves_transaction_failure_for_pam_end() {
        let mut calls = Calls::default();
        let mut session = session(&mut calls);
        session.credentials_established = true;
        session.last_status = pam::PAM_AUTH_ERR;
        session.close().unwrap();
        drop(session);
        assert_eq!(calls.calls, vec!["deletecred", "end"]);
        assert_eq!(calls.end_status, Some(pam::PAM_AUTH_ERR));
    }

    #[test]
    fn pending_transaction_drop_only_ends_transaction() {
        let mut calls = Calls::default();
        drop(session(&mut calls));
        assert_eq!(calls.calls, vec!["end"]);
    }
    #[test]
    fn established_pending_transaction_deletes_credentials_before_end() {
        let mut calls = Calls::default();
        let mut session = session(&mut calls);
        session.credentials_established = true;
        session.close().unwrap();
        drop(session);
        assert_eq!(calls.calls, vec!["deletecred", "end"]);
    }
}