Struct pam_client::Context

pub struct Context<ConvT> where
    ConvT: ConversationHandler,  { /* fields omitted */ }

Main struct for PAM interaction

Manages a PAM context holding the transaction state.

See the crate documentation for examples.

Implementations

impl<ConvT> Context<ConvT> where
    ConvT: ConversationHandler, 

pub fn new(
    service: &str,
    username: Option<&str>,
    conversation: ConvT
) -> Result<Self>

Creates a PAM context and starts a PAM transaction.

Parameters

• service – Name of the service. The policy for the service will be read from the file /etc/pam.d/service_name, falling back to /etc/pam.conf.
• username – Name of the target user. If None, the user will be asked through the conversation handler if neccessary.
• conversation – A conversation handler through which the user can be asked for his username, password, etc. Use conv_cli::Conversation for a command line default implementation, conv_mock::Conversation for fixed credentials or implement the ConversationHandler trait for custom behaviour.

Errors

Expected error codes include:

• ReturnCode::ABORT – General failure
• ReturnCode::BUF_ERR – Memory allocation failure
• ReturnCode::SYSTEM_ERR – Other system error

pub fn from_boxed_conv(
    service: &str,
    username: Option<&str>,
    mut boxed_conv: Box<ConvT>
) -> Result<Self>

Creates a PAM context and starts a PAM transaction taking a boxed conversation handler.

See new() for details.

pub fn conversation(&self) -> &ConvT

Returns a reference to the conversation handler.

pub fn conversation_mut(&mut self) -> &mut ConvT

Returns a mutable reference to the conversation handler.

pub fn get_item(&self, item_type: PamItemType) -> Result<*const c_void>

Returns raw PAM information.

If possible, use the convenience wrappers service(), user(), … instead.

Errors

Expected error codes include:

• BAD_ITEM – Unsupported, undefined or inaccessible item
• BUF_ERR – Memory buffer error
• PERM_DENIED – The value was NULL

pub unsafe fn set_item(
    &mut self,
    item_type: PamItemType,
    value: *const c_void
) -> Result<()>

Updates raw PAM information.

If possible, use the convenience wrappers set_service(), set_user(), … instead.

Errors

Expected error codes include:

• BAD_ITEM – Unsupported, undefined or inaccessible item
• BUF_ERR – Memory buffer error

Safety

This method is unsafe. You must guarantee that the data pointed to by value matches the type the PAM library expects. E.g. a null terminated *const c_char for PamItemType::SERVICE or *const PamXAuthData for PamItemType::XAUTHDATA.

pub fn service(&self) -> Result<Option<String>>

Returns the service name

pub fn set_service(&mut self, value: Option<&str>) -> Result<()>

Sets the service name

pub fn user(&self) -> Result<Option<String>>

Returns the username of the entity under whose identity service will be given

This value can be mapped by any module in the PAM stack, so don't assume it stays unchanged after calling other methods on Self.

pub fn set_user(&mut self, value: Option<&str>) -> Result<()>

Sets the username of the entity under whose identity service will be given

pub fn user_prompt(&self) -> Result<Option<String>>

Returns the string used when prompting for a user's name

pub fn set_user_prompt(&mut self, value: Option<&str>) -> Result<()>

Sets the string used when prompting for a user's name

pub fn tty(&self) -> Result<Option<String>>

Returns the terminal name

pub fn set_tty(&mut self, value: Option<&str>) -> Result<()>

Sets the terminal name

pub fn ruser(&self) -> Result<Option<String>>

Returns the requesting user name

pub fn set_ruser(&mut self, value: Option<&str>) -> Result<()>

Sets the requesting user name

pub fn rhost(&self) -> Result<Option<String>>

Returns the requesting hostname

pub fn set_rhost(&mut self, value: Option<&str>) -> Result<()>

Sets the requesting hostname

pub fn authtok_type(&self) -> Result<Option<String>>

Returns the default password type in the prompt (Linux specific)

E.g. "UNIX" for "Enter UNIX password:"

pub fn set_authtok_type(&mut self, value: Option<&str>) -> Result<()>

Sets the default password type in the prompt (Linux specific)

pub fn xdisplay(&self) -> Result<Option<String>>

Returns the name of the X display (Linux specific)

pub fn set_xdisplay(&mut self, value: Option<&str>) -> Result<()>

Sets the name of the X display (Linux specific)

pub fn xauthdata(&self) -> Result<Option<(&CStr, &[u8])>>

Returns X authentication data as (name, value) pair (Linux specific).

pub fn set_xauthdata(&mut self, value: Option<(&CStr, &[u8])>) -> Result<()>

Sets X authentication data (Linux specific).

Errors

Expected error codes include:

• BAD_ITEM – Unsupported item
• BUF_ERR – Memory buffer error

pub fn getenv<'a>(&'a self, name: &str) -> Option<&'a str>

Returns the value of a PAM environment variable.

Searches the environment list in this PAM context for an item with key name and returns the value, if it exists.

pub fn putenv(&mut self, name_value: &str) -> Result<()>

Sets or unsets a PAM environment variable.

Modifies the environment list in this PAM context. The name_value argument can take one of the following forms:

• NAME=value – Set a variable to a given value. If it was already set it is overwritten.
• NAME= – Set a variable to the empty value. If it was already set it is overwritten.
• NAME – Delete a variable, if it exists.

pub fn envlist(&self) -> EnvList

Returns a copy of the PAM environment in this context.

The contained variables represent the contents of the regular environment variables of the authenticated user when service is granted.

The returned EnvList type is designed to ease handing the environment to std::process::Command::envs() and nix::unistd::execve.

pub fn authenticate(&mut self, flags: Flag) -> Result<()>

Authenticates a user.

The conversation handler may be called to ask the user for their name (especially if no default username was provided), their password and possibly other tokens if e.g. two-factor authentication is required. Conversely the conversation handler may not be called if authentication is handled by other means, e.g. a fingerprint scanner.

Relevant flags are Flag::NONE, Flag::SILENT and Flag::DISALLOW_NULL_AUTHTOK (don't authenticate empty passwords).

Errors

Expected error codes include:

• ABORT – Serious failure; the application should exit.
• AUTH_ERR – The user was not authenticated.
• CRED_INSUFFICIENT – The application does not have sufficient credentials to authenticate the user.
• AUTHINFO_UNAVAIL – Could not retrieve authentication information due to e.g. network failure.
• MAXTRIES – At least one module reached its retry limit. Do not
• try again.
• USER_UNKNOWN – User not known.
• INCOMPLETE – The conversation handler returned CONV_AGAIN. Call again after the asynchronous conversation finished.

pub fn acct_mgmt(&mut self, flags: Flag) -> Result<()>

Validates user account authorization.

Determines if the account is valid, not expired, and verifies other access restrictions. Usually used directly after authentication. The conversation handler may be called by some PAM module.

Relevant flags are Flag::NONE, Flag::SILENT and Flag::DISALLOW_NULL_AUTHTOK (demand password change on empty passwords).

Errors

Expected error codes include:

• ACCT_EXPIRED – Account has expired.
• AUTH_ERR – Authentication failure.
• NEW_AUTHTOK_REQD – Password has expired. Use chauthtok() to let the user change their password or abort.
• PERM_DENIED – Permission denied
• USER_UNKNOWN – User not known
• INCOMPLETE – The conversation handler returned CONV_AGAIN. Call again after the asynchronous conversation finished.

pub fn reinitialize_credentials(&mut self, _flags: Flag) -> Result<()>

Fully reinitializes the user's credentials (if established).

Reinitializes credentials like Kerberos tokens for when a session is already managed by another process. This is e.g. used in lockscreen applications to refresh the credentials of the desktop session.

Because of limitations in pam_sys the flags are currently ignored. Use Flag::NONE or Flag::SILENT.

Errors

Expected error codes include:

• BUF_ERR – Memory allocation error
• CRED_ERR – Setting credentials failed
• CRED_UNAVAIL – Failed to retrieve credentials
• SYSTEM_ERR – Other system error
• USER_UNKNOWN – User not known

pub fn chauthtok(&mut self, flags: Flag) -> Result<()>

Changes a users password.

The conversation handler will be used to request the new password and might query for the old one.

Relevant flags are Flag::NONE, Flag::SILENT and Flag::CHANGE_EXPIRED_AUTHTOK (only initiate change for expired passwords).

Errors

Expected error codes include:

• AUTHTOK_ERR – Unable to obtain the new password
• AUTHTOK_RECOVERY_ERR – Unable to obtain the old password
• AUTHTOK_LOCK_BUSY – Authentication token is currently locked
• AUTHTOK_DISABLE_AGING – Password aging is disabled (password may be unchangeable in at least one module)
• PERM_DENIED – Permission denied
• TRY_AGAIN – Not all modules were able to prepare an authentication token update. Nothing was changed.
• USER_UNKNOWN – User not known
• INCOMPLETE – The conversation handler returned CONV_AGAIN. Call again after the asynchronous conversation finished.

pub fn open_session(&mut self, flags: Flag) -> Result<Session<'_, ConvT>>

Sets up a user session.

Establishes user credentials and performs various tasks to prepare a login session, may create the home directory on first login, mount user-specific directories, log access times, etc. The application must usually have sufficient privileges to perform this task (e.g. have EUID 0). The returned Session object closes the session and deletes the established credentials on drop.

The user should already be authenticated and authorized at this point, but this isn't enforced or strictly neccessary if the user was authenticated by other means. In that case the conversation handler might be called by e.g. crypt-mount modules to get a password.

Relevant flags are Flag::NONE and Flag::SILENT.

Errors

Expected error codes include:

• ABORT – Serious failure; the application should exit
• BUF_ERR – Memory allocation error
• SESSION_ERR – Some session initialization failed
• CRED_ERR – Setting credentials failed
• CRED_UNAVAIL – Failed to retrieve credentials
• SYSTEM_ERR – Other system error
• USER_UNKNOWN – User not known
• INCOMPLETE – The conversation handler returned CONV_AGAIN. Call again after the asynchronous conversation finished.

pub fn open_pseudo_session(
    &mut self,
    _flags: Flag
) -> Result<Session<'_, ConvT>>

Maintains user credentials but don't set up a full user session.

Establishes user credentials and returns a Session object that deletes the credentials on drop. It doesn't open a PAM session.

The user should already be authenticated and authorized at this point, but this isn't enforced or strictly neccessary.

Depending on the platform this use case may not be fully supported.

Because of limitations in pam_sys the flags are currently ignored. Use Flag::NONE or Flag::SILENT.

Errors

Expected error codes include:

• BUF_ERR – Memory allocation error
• CRED_ERR – Setting credentials failed
• CRED_UNAVAIL – Failed to retrieve credentials
• SYSTEM_ERR – Other system error
• USER_UNKNOWN – User not known

pub fn unleak_session(&mut self, token: SessionToken) -> Session<'_, ConvT>

Resume a session from a SessionToken.

impl<ConvT> Context<ConvT> where
    ConvT: ConversationHandler + Default, 

pub fn replace_conversation<T: ConversationHandler>(
    self,
    new_handler: T
) -> ExtResult<(Context<T>, ConvT), (Self, T)>

Swap the conversation handler.

Consumes the context, returns the new context and the old conversation handler.

Errors

Expected error codes include:

• BAD_ITEM – Swapping the conversation handler is unsupported
• BUF_ERR – Memory buffer error

The error payload contains the old context and the new handler.

pub fn replace_conversation_boxed<T: ConversationHandler>(
    mut self: Self,
    mut new_handler: Box<T>
) -> ExtResult<(Context<T>, Box<ConvT>), (Self, Box<T>)>

Swap the conversation handler (boxed variant).

See replace_conversation().

Trait Implementations

impl<ConvT> Drop for Context<ConvT> where
    ConvT: ConversationHandler, 

Destructor ending the PAM transaction and releasing the PAM context

fn drop(&mut self)

Executes the destructor for this type.

impl<ConvT> Send for Context<ConvT> where
    ConvT: ConversationHandler + Send,