Struct rsasl::SASL

pub struct SASL<D, E> { /* fields omitted */ }

Global SASL Context wrapper implementing housekeeping functionality

This struct contains the global gsasl context allowing you to start authentication exchanges.

It implements housekeeping functionality, calling gsasl_init and gsasl_done as required.

The type parameters D and E define the types you can store / retrieve in callbacks; gsasl allows to store one object in both the context and session allowing callbacks to access values from the application despite going through a FFI layer.

Values stored in the global context using store are available to all callbacks via retrieve_mut. Values stored with Session::store are only available in that session via Session::retrieve_mut.

The stored value can be extracted again using retrieve and it’s Session requivalent.

Implementations

impl<D, E> SASL<D, E>

pub fn new() -> Result<DiscardOnDrop<Self>>

Create a fresh GSASL context from scratch.

The context retrieved from this is wrapped in a DiscardOnDrop. The purpose of this wrapping is to ensure that finalizer functions are called when the context is dropped. DiscardOnDrop implements both Deref and DerefMut, making the wrapping transparent to you. If you want to intentionally remove the Context from the wrapping you can call DiscardOnDrop::leak, allowing you to manually handle finalizing the context.

pub fn client_mech_list(&self) -> Result<Mechanisms>

Returns the list of Client Mechanisms supported by this library.

Important note: This will make no attempt to check if the application has provided the required data for the listed mechanisms. For example this will return the GSSAPI and KERBEROS_V5 mechanism if the system gsasl was linked with a libkrb5, independent of if the application has a valid ticket.

pub fn server_mech_list(&self) -> Result<Mechanisms>

Returns the list of Server Mechanisms supported by this library.

Important note: This will make no attempt to check if the application has provided the required data for the listed mechanisms. For example this will return the GSSAPI and KERBEROS_V5 mechanism if the system gsasl was linked with a libkrb5, independent of if the application has a valid keytab.

pub fn suggest_client_mechanism(
    &self,
    mechs: Mechanisms
) -> Result<&str, SaslError>

Suggests a mechanism to use from a given list of Mechanisms. Returns Err(GSASL_UNKNOWN_MECHANISM) if there was no supported mechanism found in the given list, and Err(GSASL_MECHANISM_PARSE_ERROR) if the returned mechanism name is invalid.

pub fn client_supports(&self, mech: &CStr) -> bool

Returns wheter there is client-side support for the specified mechanism

pub fn server_supports(&self, mech: &CStr) -> bool

Returns wheter there is server-side support for the specified mechanism

pub fn install_callback<C: Callback<D, E>>(&mut self)

Install a callback.

Callbacks are used to retrieve information, such as username and password, from the application. In a server, the callback is additionally used make decisions such as whether a user is permitted to log in or not.

See the callback documentation for details on how to use this function

Do note that the generic types D and E need to match between SASL, Session and Callback to ensure typesafety. More information

pub fn client_start(&mut self, mech: &str) -> Result<DiscardOnDrop<Session<E>>>

Starts a authentication exchange as the client role

Depending on the mechanism chosen this may need additional data from the application, such as an authcid, optional authzid and password for PLAIN. To provide that data an application has to either call set_property before running the step that requires the data, or install a callback.

See the gsasl documentation for what mechanism uses what properties.

pub fn server_start(&mut self, mech: &str) -> Result<DiscardOnDrop<Session<E>>>

Starts a authentication exchange as the server role

An application acting as server will most likely need to implement a callback to check the authentication data provided by the user.

See Callback on how to implement callbacks.

See the gsasl documentation for how gsasl uses properties and callbacks.

pub fn store(&mut self, data: Box<D>)

Store some data in the SASL context

This allows a callback to later access that data using retrieve or retrieve_mut

pub unsafe fn retrieve(&mut self) -> Option<Box<D>>

Retrieve the data stored with store, leaving nothing in its place

This function will return None if no data was stored. This function is unsafe because we can not guarantee that there is currently nothing else that has a reference to the data which will turn into a dangling pointer if the returned Box is dropped

pub fn retrieve_mut(&mut self) -> Option<&mut D>

Retrieve a mutable reference to the data stored with store

This function does not take ownership of the stored data, thus also not dropping it after it has left the current scope.

The function tries to return None if no data was stored.

pub fn callback(&mut self, session: &mut Session<E>, prop: Property) -> c_int

Run the configured callback.

impl SASL<(), ()>

pub fn new_untyped() -> Result<DiscardOnDrop<Self>>

Construct an untyped SASL

This is mostly useful for client applications when no callback will be installed and no information stored or retrieved in either the global or session context.

Trait Implementations

impl<D: Debug, E: Debug> Debug for SASL<D, E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<D, E> Discard for SASL<D, E>

fn discard(self)

This consumes the value and cleans up any memory / resources / etc. that the value was using.