limes-common 0.3.0

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

use limes_proto::{AuthFailure, AuthOutcome, AuthRequest, AuthSuccess};

use crate::auth::pam::conversation::{PamConversation, SecretCString, pam_conversation};
use crate::auth::pam::raw as pam;
use crate::auth::pam::session::PamSession;
use crate::auth::pam::status::{internal_failure, map_auth_status};
use crate::auth::pam::user::{UserRecord, lookup_user};
use crate::auth::traits::{AuthBackend, AuthSession, AuthenticatedLogin, LockAuthBackend};
use crate::events::EventBus;

pub const PAM_SERVICE: &str = "limes";

pub struct PamAuth {
    service: &'static str,
    events: Option<EventBus>,
}

pub struct PamLockAuth {
    service: &'static str,
    events: Option<EventBus>,
}

impl std::fmt::Debug for PamAuth {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PamAuth")
            .field("service", &self.service)
            .field("events", &self.events.as_ref().map(|_| "<event-bus>"))
            .finish()
    }
}

impl std::fmt::Debug for PamLockAuth {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PamLockAuth")
            .field("service", &self.service)
            .field("events", &self.events.as_ref().map(|_| "<event-bus>"))
            .finish()
    }
}

impl Default for PamAuth {
    fn default() -> Self {
        Self::new()
    }
}
impl Default for PamLockAuth {
    fn default() -> Self {
        Self::new()
    }
}

impl PamAuth {
    #[must_use]
    pub fn new() -> Self {
        Self::with_events(None)
    }

    #[must_use]
    pub fn with_events(events: Option<EventBus>) -> Self {
        Self {
            service: PAM_SERVICE,
            events,
        }
    }
}

impl PamLockAuth {
    #[must_use]
    pub fn new() -> Self {
        Self::with_events(None)
    }

    #[must_use]
    pub fn with_events(events: Option<EventBus>) -> Self {
        Self {
            service: PAM_SERVICE,
            events,
        }
    }
}

impl AuthBackend for PamAuth {
    fn authenticate(
        &self,
        request: &AuthRequest,
    ) -> std::result::Result<AuthenticatedLogin, AuthFailure> {
        let (mut session, user) = authenticate_pam(self.service, request, self.events.clone())?;
        if let Err(failure) = session.establish_credentials() {
            return Err(close_failed_auth(&mut session, failure));
        }
        Ok(AuthenticatedLogin::new(identity(user), Box::new(session)))
    }
}

impl LockAuthBackend for PamLockAuth {
    fn authenticate(&self, request: &AuthRequest) -> AuthOutcome {
        let (mut session, user) = authenticate_pam(self.service, request, self.events.clone())?;
        session.close().map_err(internal_failure)?;
        Ok(identity(user))
    }
}

fn identity(user: UserRecord) -> AuthSuccess {
    AuthSuccess {
        username: user.username,
        uid: user.uid,
        gid: user.gid,
        home: user.home,
        shell: user.shell,
    }
}

fn close_failed_auth(session: &mut PamSession, failure: AuthFailure) -> AuthFailure {
    match session.close() {
        Ok(()) => failure,
        Err(error) => AuthFailure::Internal(format!("{failure}; PAM cleanup failed: {error}")),
    }
}

fn authenticate_pam(
    service: &'static str,
    request: &AuthRequest,
    events: Option<EventBus>,
) -> std::result::Result<(PamSession, UserRecord), AuthFailure> {
    let service = CString::new(service).map_err(internal_failure)?;
    let username = CString::new(request.username.as_str()).map_err(internal_failure)?;
    let password = SecretCString::new(request.password.as_str()).map_err(internal_failure)?;
    let tty = request
        .tty
        .as_deref()
        .filter(|tty| !tty.trim().is_empty())
        .map(CString::new)
        .transpose()
        .map_err(internal_failure)?;
    let conversation = Box::new(UnsafeCell::new(PamConversation::new(
        username,
        request.username.clone(),
        Some(password),
        events,
    )));
    let conv = pam::PamConv {
        conv: Some(pam_conversation),
        appdata_ptr: conversation.get().cast(),
    };
    // End the temporary Rust borrow before PAM may invoke its callback.
    let username_ptr = unsafe { &*conversation.get() }.username_ptr();
    let mut handle = ptr::null_mut();
    let status = unsafe { pam::pam_start(service.as_ptr(), username_ptr, &conv, &mut handle) };
    // Own any returned handle immediately, including a partially initialized one.
    let mut session = PamSession::new(handle, conversation);
    session.record_status(status);
    if status != pam::PAM_SUCCESS {
        let failure = map_auth_status(status, handle);
        return Err(close_failed_auth(&mut session, failure));
    }
    if handle.is_null() {
        return Err(AuthFailure::Internal(
            "PAM returned no transaction handle".to_owned(),
        ));
    }
    if let Some(tty) = &tty {
        let status =
            unsafe { pam::pam_set_item(session.handle(), pam::PAM_TTY, tty.as_ptr().cast()) };
        session.record_status(status);
        if status != pam::PAM_SUCCESS {
            let failure = map_auth_status(status, session.handle());
            return Err(close_failed_auth(&mut session, failure));
        }
    }
    for call in [pam::pam_authenticate, pam::pam_acct_mgmt] {
        let status = unsafe { call(session.handle(), 0) };
        session.record_status(status);
        if status != pam::PAM_SUCCESS {
            let failure = map_auth_status(status, session.handle());
            return Err(close_failed_auth(&mut session, failure));
        }
    }
    let mut item = ptr::null();
    let status = unsafe { pam::pam_get_item(session.handle(), pam::PAM_USER, &mut item) };
    session.record_status(status);
    let authenticated_username = match pam_username(status, item) {
        Ok(username) => username,
        Err(failure) => return Err(close_failed_auth(&mut session, failure)),
    };
    let Some(user) = lookup_user(&authenticated_username) else {
        return Err(close_failed_auth(
            &mut session,
            AuthFailure::InvalidCredentials,
        ));
    };
    Ok((session, user))
}
/// Copies PAM's final identity before the transaction can be ended. Never use
/// the submitted username as a fallback: modules may have changed PAM_USER.
fn pam_username(
    status: libc::c_int,
    item: *const c_void,
) -> std::result::Result<String, AuthFailure> {
    if status != pam::PAM_SUCCESS {
        return Err(AuthFailure::Internal(format!(
            "failed to read authenticated PAM user (PAM status {status})"
        )));
    }
    if item.is_null() {
        return Err(AuthFailure::Internal(
            "authenticated PAM user is missing".to_owned(),
        ));
    }
    // A successful PAM_USER item is a NUL-terminated string owned by PAM.
    let username = unsafe { CStr::from_ptr(item.cast()) }
        .to_str()
        .map_err(|_| AuthFailure::Internal("authenticated PAM user is not UTF-8".to_owned()))?;
    if username.is_empty() {
        return Err(AuthFailure::Internal(
            "authenticated PAM user is empty".to_owned(),
        ));
    }
    Ok(username.to_owned())
}

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

    #[test]
    fn authenticated_identity_uses_final_pam_user() {
        let submitted = CString::new("submitted-user").unwrap();
        let final_user = CString::new("canonical-user").unwrap();

        let username = pam_username(pam::PAM_SUCCESS, final_user.as_ptr().cast()).unwrap();

        assert_eq!(username, "canonical-user");
        assert_ne!(username, submitted.to_str().unwrap());
    }

    #[test]
    fn authenticated_identity_fails_closed_on_item_read_error() {
        // The pointer must not even be inspected when PAM reports failure.
        assert!(pam_username(pam::PAM_PERM_DENIED, ptr::null()).is_err());
    }

    #[test]
    fn authenticated_identity_rejects_missing_empty_and_non_utf8_user() {
        assert!(pam_username(pam::PAM_SUCCESS, ptr::null()).is_err());
        let empty = CString::new("").unwrap();
        assert!(pam_username(pam::PAM_SUCCESS, empty.as_ptr().cast()).is_err());
        let invalid_utf8 = CString::new(vec![0xff]).unwrap();
        assert!(pam_username(pam::PAM_SUCCESS, invalid_utf8.as_ptr().cast()).is_err());
    }
}