Struct bsd_auth::Session

pub struct Session { /* fields omitted */ }

BSD Authentication session

Implementations

impl Session

pub fn new() -> Result<Self, Error>

Open a new BSD Authentication session with the default service (which can be changed later).

pub fn from_raw(ptr: *mut auth_session_t) -> Result<Self, Error>

Create a Session from a raw auth_session_t pointer

pub fn into_raw(self) -> Result<*mut auth_session_t, Error>

Convert the Session into a raw auth_session_t pointer

Consumes the Session

pub fn auth_challenge(&self) -> Result<String, Error>

Request a challenge for the session

The name and style must have already been specified

Call is not thread-safe

pub fn auth_close(self) -> Result<(), Error>

Close the specified BSD Authentication session

Frees the ptr pointer to the session future calls with the Session will all return Error

Inner pointer can be reset with calls that open a new session

Consumes the Session

Call is not thread-safe

pub fn auth_getstate(&self) -> Result<i32, Error>

Get the BSD Authentication session state (0 = unauth, 1 = auth)

Call is not thread-safe

pub fn auth_setenv(&self) -> Result<(), Error>

Set/unset the requested environment variables. Mark the variables as set so they will not be set a second time.

Environment variables are requested via the spool of the auth_session_t struct

Call is not thread-safe

pub fn auth_clrenv(&self) -> Result<(), Error>

Clear out any of the requested environment variables.

Call is not thread-safe

pub fn auth_getitem(&self, item: AuthItem) -> Result<String, Error>

Get the item value

Call is not thread-safe

pub fn auth_setitem(&self, item: AuthItem, value: &str) -> Result<(), Error>

Set an item value

Value must be a valid UTF-8 string

Call is not thread-safe

pub fn auth_setoption(&self, name: &str, value: &str) -> Result<(), Error>

Set an option name and value

Returns error if:

• session is null
• option allocation fails
• name is too long

Call is not thread-safe

pub fn auth_clroptions(&self) -> Result<(), Error>

Clear all set options in the BSD Authentication session

Call is not thread-safe

pub fn auth_clroption(&self, option: &str) -> Result<(), Error>

Clear the option matching the specified name

Call is not thread-safe

pub fn auth_setdata(&self, data: &mut [u8]) -> Result<(), Error>

Set BSD Authentication session data to be read into the spool.

Data is not mutated, but needs to be a mutable reference to satisfy the borrow checker.

Call is not thread-safe

pub fn auth_usercheck(
    name: &str,
    style: Option<&str>,
    auth_type: Option<&str>,
    password: Option<&mut str>
) -> Result<Self, Error>

Single function interface to a BSD Authentication session

Functions similarly to a auth_userokay, but does not close the session.

Example:

let name = "nobody".to_string();
let mut passwd = "some_passwd".to_string();

let _session = Session::auth_usercheck(name.as_str(), None, None, Some(&mut passwd)).unwrap();

From man 3 auth_approval:

The auth_usercheck() function operates the same as the auth_userokay()
function except that it does not close the BSD Authentication session
created.  Rather than returning the status of the session, it returns a
pointer to the newly created BSD Authentication session.

If authentication fails, a null pointer is returned, which results in
an error in the Rust API.

For more details see man 3 auth_approval

pub fn auth_userokay(
    name: &str,
    style: Option<&str>,
    auth_type: Option<&str>,
    password: Option<&mut str>
) -> Result<bool, Error>

Single function call interface for a BSD Authentication session

Provide a name, and optional style, type and password.

If style or type are not provided, the default values will be used.

Supplying a password uses the non-interactive version of the authentication. Not supplying a password uses an interactive authentication mode.

Example:

let name = "nobody".to_string();
let mut passwd = "some_passwd".to_string();

assert!(!Session::auth_userokay(name.as_str(), None, None, Some(&mut passwd)).unwrap());

From man 3 auth_approval:

Provides a single function call interface.

Provided with a user's name in name, and an optional style, type, and password, the auth_userokay() function returns a simple yes/no response.

A return value of true implies failure; a false return value implies success.
Other error conditions result in Error.

If style is not NULL, it specifies the desired style of authentication to be used.
If it is NULL then the default style for the user is used.
In this case, name may include the desired style by appending it to the user's name with a single colon (`:') as a separator.
If type is not NULL then it is used as the authentication type (such as "auth-myservice").
If password is NULL then auth_userokay() operates in an interactive mode with the user on standard input, output, and error.
If password is specified, auth_userokay() operates in a non-interactive mode and only tests the specified passwords.
This non-interactive method does not work with challenge-response authentication styles.

For security reasons, when a password is specified, auth_userokay() will zero out its value before it returns. 

For more details see man 3 auth_approval

pub fn auth_userchallenge(
    name: &str,
    style: Option<&str>,
    auth_type: Option<&str>
) -> Result<(Self, String), Error>

Get an authentication challenge for the user, with optional style and type Example:

/* Create the session and get the challenge */
let (session, _chal) = Session::auth_userchallenge("nobody", Some("passwd"), Some("auth_doas")).unwrap();

/* Prompt the user for a response */
let mut response = String::from_utf8([1; 1024].to_vec()).unwrap();
session.auth_userresponse(&mut response, 0).unwrap();

From man 3 auth_approval:

The auth_userchallenge() function takes the same name, style, and type arguments as does auth_userokay().

However, rather than authenticating the user, it returns a possible challenge in the pointer pointed to by challengep.

To provide a safe Rust API the challenge pointer is converted to a string.

The memory pointed to by challengep is cleared for security.

The return value of the function is a pointer to a newly created BSD Authentication session.

This challenge, if not NULL, should be displayed to the user.

In any case, the user should provide a password which is the response in a call to auth_userresponse().

For more information, see man 3 auth_approval

pub fn auth_userresponse(
    self,
    response: &mut str,
    more: i32
) -> Result<bool, Error>

Provide a user response for a BSD Authentication session

Consumes the Session due to the FFI call closing the session

Example:

let name = "nobody".to_string();
let style = Some("passwd");
let mut passwd = "some_passwd".to_string();

let session = Session::auth_usercheck(name.as_str(), style, None, Some(&mut passwd)).unwrap();

let mut res = String::from_utf8([1u8; 1024].to_vec()).unwrap();
assert!(session.auth_userresponse(&mut res, 0).is_ok());

From man 3 auth_approval:

 In addition to the password, the pointer returned by auth_userchallenge()
 should be passed in as as and the value of more should be non-zero if the
 program wishes to allow more attempts.

 If more is zero then the session will be closed.

 The auth_userresponse() function closes the BSD Authentication session and has the same return value as auth_userokay().

 For security reasons, when a response is specified, auth_userresponse() will zero out its value before it returns.

Trait Implementations

impl Drop for Session

fn drop(&mut self)

Executes the destructor for this type.