Struct pam_client::Context
source · [−]pub struct Context<ConvT> where
ConvT: ConversationHandler, { /* private fields */ }
Expand description
Main struct for PAM interaction
Manages a PAM context holding the transaction state.
See the crate documentation for examples.
Implementations
sourceimpl<ConvT> Context<ConvT> where
ConvT: ConversationHandler,
impl<ConvT> Context<ConvT> where
ConvT: ConversationHandler,
sourcepub fn new(
service: &str,
username: Option<&str>,
conversation: ConvT
) -> Result<Self>
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. IfNone
, 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. Useconv_cli::Conversation
for a command line default implementation,conv_mock::Conversation
for fixed credentials or implement theConversationHandler
trait for custom behaviour.
Errors
Expected error codes include:
ErrorCode::ABORT
– General failureErrorCode::BUF_ERR
– Memory allocation failure or null byte in parameter.ErrorCode::SYSTEM_ERR
– Other system error
sourcepub fn from_boxed_conv(
service: &str,
username: Option<&str>,
boxed_conv: Box<ConvT>
) -> Result<Self>
pub fn from_boxed_conv(
service: &str,
username: Option<&str>,
boxed_conv: Box<ConvT>
) -> Result<Self>
Creates a PAM context and starts a PAM transaction taking a boxed conversation handler.
See new()
for details.
sourcepub fn conversation(&self) -> &ConvT
pub fn conversation(&self) -> &ConvT
Returns a reference to the conversation handler.
sourcepub fn conversation_mut(&mut self) -> &mut ConvT
pub fn conversation_mut(&mut self) -> &mut ConvT
Returns a mutable reference to the conversation handler.
sourcepub unsafe fn set_item(
&mut self,
item_type: c_int,
value: *const c_void
) -> Result<()>
pub unsafe fn set_item(
&mut self,
item_type: c_int,
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 itemBUF_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 PAM_SERVICE
or *const PamXAuthData
for
PAM_XAUTHDATA
.
sourcepub fn user(&self) -> Result<String>
pub fn user(&self) -> Result<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
.
sourcepub fn set_user(&mut self, value: Option<&str>) -> Result<()>
pub fn set_user(&mut self, value: Option<&str>) -> Result<()>
Sets the username of the entity under whose identity service will be given
sourcepub fn user_prompt(&self) -> Result<String>
pub fn user_prompt(&self) -> Result<String>
Returns the string used when prompting for a user’s name
sourcepub fn set_user_prompt(&mut self, value: Option<&str>) -> Result<()>
pub fn set_user_prompt(&mut self, value: Option<&str>) -> Result<()>
Sets the string used when prompting for a user’s name
sourcepub fn authtok_type(&self) -> Result<String>
pub fn authtok_type(&self) -> Result<String>
Returns the default password type in the prompt (Linux specific)
E.g. “UNIX” for “Enter UNIX password:”
sourcepub fn set_authtok_type(&mut self, value: Option<&str>) -> Result<()>
pub fn set_authtok_type(&mut self, value: Option<&str>) -> Result<()>
Sets the default password type in the prompt (Linux specific)
sourcepub fn set_xdisplay(&mut self, value: Option<&str>) -> Result<()>
pub fn set_xdisplay(&mut self, value: Option<&str>) -> Result<()>
Sets the name of the X display (Linux specific)
sourcepub fn xauthdata(&self) -> Result<(&CStr, &[u8])>
pub fn xauthdata(&self) -> Result<(&CStr, &[u8])>
Returns X authentication data as (name, value) pair (Linux specific).
sourcepub fn set_xauthdata(&mut self, value: Option<(&CStr, &[u8])>) -> Result<()>
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 itemBUF_ERR
– Memory buffer error
sourcepub fn getenv(&self, name: impl AsRef<OsStr>) -> Option<&str>
pub fn getenv(&self, name: impl AsRef<OsStr>) -> Option<&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.
sourcepub fn putenv(&mut self, name_value: impl AsRef<OsStr>) -> Result<()>
pub fn putenv(&mut self, name_value: impl AsRef<OsStr>) -> 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.
sourcepub fn envlist(&self) -> EnvList
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()
.
sourcepub fn authenticate(&mut self, flags: Flag) -> Result<()>
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 initial 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 returnedCONV_AGAIN
. Call again after the asynchronous conversation finished.
sourcepub fn acct_mgmt(&mut self, flags: Flag) -> Result<()>
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. Usechauthtok()
to let the user change their password or abort.PERM_DENIED
– Permission deniedUSER_UNKNOWN
– User not knownINCOMPLETE
– The conversation handler returnedCONV_AGAIN
. Call again after the asynchronous conversation finished.
sourcepub fn reinitialize_credentials(&mut self, flags: Flag) -> Result<()>
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.
Relevant flags
are Flag::NONE
and Flag::SILENT
.
Errors
Expected error codes include:
BUF_ERR
– Memory allocation errorCRED_ERR
– Setting credentials failedCRED_UNAVAIL
– Failed to retrieve credentialsSYSTEM_ERR
– Other system errorUSER_UNKNOWN
– User not known
sourcepub fn chauthtok(&mut self, flags: Flag) -> Result<()>
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 passwordAUTHTOK_RECOVERY_ERR
– Unable to obtain the old passwordAUTHTOK_LOCK_BUSY
– Authentication token is currently lockedAUTHTOK_DISABLE_AGING
– Password aging is disabled (password may be unchangeable in at least one module)PERM_DENIED
– Permission deniedTRY_AGAIN
– Not all modules were able to prepare an authentication token update. Nothing was changed.USER_UNKNOWN
– User not knownINCOMPLETE
– The conversation handler returnedCONV_AGAIN
. Call again after the asynchronous conversation finished.
sourcepub fn open_session(&mut self, flags: Flag) -> Result<Session<'_, ConvT>>
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 exitBUF_ERR
– Memory allocation errorSESSION_ERR
– Some session initialization failedCRED_ERR
– Setting credentials failedCRED_UNAVAIL
– Failed to retrieve credentialsSYSTEM_ERR
– Other system errorUSER_UNKNOWN
– User not knownINCOMPLETE
– The conversation handler returnedCONV_AGAIN
. Call again after the asynchronous conversation finished.
sourcepub fn open_pseudo_session(&mut self, flags: Flag) -> Result<Session<'_, ConvT>>
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.
Relevant flags
are Flag::NONE
and Flag::SILENT
.
Errors
Expected error codes include:
BUF_ERR
– Memory allocation errorCRED_ERR
– Setting credentials failedCRED_UNAVAIL
– Failed to retrieve credentialsSYSTEM_ERR
– Other system errorUSER_UNKNOWN
– User not known
sourcepub fn unleak_session(&mut self, token: SessionToken) -> Session<'_, ConvT>
pub fn unleak_session(&mut self, token: SessionToken) -> Session<'_, ConvT>
Resume a session from a SessionToken
.
sourceimpl<ConvT> Context<ConvT> where
ConvT: ConversationHandler + Default,
impl<ConvT> Context<ConvT> where
ConvT: ConversationHandler + Default,
sourcepub fn replace_conversation<T: ConversationHandler>(
self,
new_handler: T
) -> ExtResult<(Context<T>, ConvT), (Self, T)>
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 unsupportedBUF_ERR
– Memory buffer error
The error payload contains the old context and the new handler.
sourcepub fn replace_conversation_boxed<T: ConversationHandler>(
self,
new_handler: Box<T>
) -> ExtResult<(Context<T>, Box<ConvT>), (Self, Box<T>)>
pub fn replace_conversation_boxed<T: ConversationHandler>(
self,
new_handler: Box<T>
) -> ExtResult<(Context<T>, Box<ConvT>), (Self, Box<T>)>
Swap the conversation handler (boxed variant).
Trait Implementations
sourceimpl<ConvT> Drop for Context<ConvT> where
ConvT: ConversationHandler,
impl<ConvT> Drop for Context<ConvT> where
ConvT: ConversationHandler,
Destructor ending the PAM transaction and releasing the PAM context
impl<ConvT> Send for Context<ConvT> where
ConvT: ConversationHandler + Send,
Auto Trait Implementations
impl<ConvT> !RefUnwindSafe for Context<ConvT>
impl<ConvT> !Sync for Context<ConvT>
impl<ConvT> Unpin for Context<ConvT>
impl<ConvT> UnwindSafe for Context<ConvT> where
ConvT: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more