Crate pam_client

Client application interface for Pluggable Authentication Modules (PAM)

PAM is the user authentication system used in many Unix-like operating systems (Linux, NetBSD, MacOS, Solaris, etc.) and handles authentication, account management, session management and passwort changing via pluggable modules. This allows programs (such as login(1) and su(1)) to authenticate users e.g. in a Kerberos domain as well as locally in /etc/passwd.

This library provides a safe API to the application-faced parts of PAM, covering multiple use-cases with a high grade of flexibility.

It is currently only tested on Linux, but should also support OpenPAM-based platforms like NetBSD. Solaris should also be supported, but the support is untested.

Examples

Sample workflow for command line interaction like su -c, running a single program as the user after they successfully authenticated:

use pam_client::{Context, Flag};
use pam_client::conv_cli::Conversation; // CLI implementation
use std::process::Command;
use std::os::unix::process::CommandExt;

let mut context = Context::new(
   "my-service",       // Service name, decides which policy is used (see `/etc/pam.d`)
   None,               // Optional preset user name
   Conversation::new() // Handler for user interaction
).expect("Failed to initialize PAM context");

// Optionally set some settings
context.set_user_prompt(Some("Who art thou? "));

// Authenticate the user (ask for password, 2nd-factor token, fingerprint, etc.)
context.authenticate(Flag::NONE).expect("Authentication failed");

// Validate the account (is not locked, expired, etc.)
context.acct_mgmt(Flag::NONE).expect("Account validation failed");

// Get resulting user name and map to a user id
let username = context.user();
let uid = 65535; // Left as an exercise to the reader

// Open session and initialize credentials
let mut session = context.open_session(Flag::NONE).expect("Session opening failed");

// Run a process in the PAM environment
let result = Command::new("/usr/bin/some_program")
                     .env_clear()
                     .envs(session.envlist().iter_tuples())
                     .uid(uid)
                  // .gid(...)
                     .status();

// The session is automatically closed when it goes out of scope.

Sample workflow for non-interactive authentication

use pam_client::{Context, Flag};
use pam_client::conv_mock::Conversation; // Non-interactive implementation

let mut context = Context::new(
   "my-service",  // Service name
   None,
   Conversation::with_credentials("username", "password")
).expect("Failed to initialize PAM context");

// Authenticate the user
context.authenticate(Flag::NONE).expect("Authentication failed");

// Validate the account
context.acct_mgmt(Flag::NONE).expect("Account validation failed");

// ...

Sample workflow for session management without PAM authentication:

use pam_client::{Context, Flag};
use pam_client::conv_null::Conversation; // Null implementation

let mut context = Context::new(
   "my-service",     // Service name
   Some("username"), // Preset username
   Conversation::new()
).expect("Failed to initialize PAM context");

// We already authenticated the user by other means (e.g. SSH key) so we
// skip `context.authenticate()`.

// Validate the account
context.acct_mgmt(Flag::NONE).expect("Account validation failed");

// Open session and initialize credentials
let mut session = context.open_session(Flag::NONE).expect("Session opening failed");

// ...

// The session is automatically closed when it goes out of scope.

Modules

conv_cli

Interactive command line conversation handler

conv_mock

Simple non-interactive conversation handler

conv_null

Null conversation handler

env_list

PAM environment list

Structs

Context

Main struct for PAM interaction

ErrorWith

Base error type for PAM operations (possibly with a payload)

Flag

Flags for most PAM functions

Session

An active PAM session or pseudo session

Enums

ErrorCode

PAM error codes

SessionToken

Token type to resume RAII handling of a session that was released with Session::leak().

Traits

ConversationHandler

Trait for PAM conversation functions

Type Aliases

Error

Error type for PAM operations without error payload.

ExtResult

Type alias for the result of PAM methods that pass back a consumed struct on error.

Result

Type alias for the result of most PAM methods.