Crate rsasl[][src]

Expand description

rSASL — Rustic bindings to GNU libgsasl

libgsasl is a pure C, LGPL-2.1 (or later) licensed SASL library. This crate provides safe bindings to that library, providing access to a large number of authentication mechanisms:

  • CRAM-MD5
  • NTLM
  • GS2-KRB5
  • SAML20
  • OPENID20

To use this library a SASL struct has to be constructed first. Using this struct the list of supported mechanisms for authentication can be accessed via SASL::client_mech_list and SASL::server_mech_list.

For each authentication exchange a Session need to be created using SASL::client_start or SASL::server_start, depending on if the application is acting as the client or server role respectively.

The returned Session can be preloaded with required data for authentication, see Session::set_property.


gsasl uses what it calls ‘Properties’ to send authentication data to and from an application. These properties can either be “logic properties” indicating that the application need to make a decision and “data properties” storing a value such as an username or password. A detailed explanation of the available properties and their use in mechanism can be found at the gsasl website.


rSASL uses callbacks to retrieve properties from an application and to allow the application to make decisions.

An explanation on how to implement decision logic and callbacks in Rust can be found in the Callback documentation.

While Server applications will usually need to implement callbacks Client applications can forgo this and preemptively set properties via Session::set_property:

use rsasl::{SASL, Property, Step::{Done, NeedsMore}};
pub fn main() {
    // Create an untyped SASL because we won't store/retrieve information in the context since
    // we don't use callbacks.
    let mut sasl = SASL::new_untyped().unwrap();

    // Usually you would first agree on a mechanism with the server, for demostration purposes
    // we directly start a PLAIN "exchange"
    let mut session = sasl.client_start("PLAIN").unwrap();

    // Set the username that will be used in the PLAIN authentication
    session.set_property(Property::GSASL_AUTHID, "username".as_bytes());

    // Now set the password that will be used in the PLAIN authentication
    session.set_property(Property::GSASL_PASSWORD, "secret".as_bytes());

    // Do an authentication step. In a PLAIN exchange there is only one step, with no data.
    let step_result = session.step(&[]).unwrap();

    match step_result {
        Done(buffer) => assert_eq!(buffer.as_ref(), "\0username\0secret".as_bytes()),
        NeedsMore(_) => assert!(false, "PLAIN exchange took more than one step"),


pub use gsasl_sys::Gsasl_rc::*;
pub use session::Session;
pub use buffer::SaslString;
pub use gsasl_sys as sys;
pub use session::Step;
pub use error::SaslError;
pub use error::rsasl_err_to_str;
pub use error::gsasl_err_to_str;
pub use error::rsasl_errname_to_str;
pub use error::gsasl_errname_to_str;



If you have a value which implements Discard, you can use DiscardOnDrop::new(value) which will wrap the value. When the wrapper is dropped it will automatically call value.discard().

A String representing a list of Mechanisms

Global SASL Context wrapper implementing housekeeping functionality



Typesafe Callbacks via trait implementations

This trait is very similar to Drop: it allows for cleaning up memory and resources when they are no longer needed.

Type Definitions

Utility type definition to make the outer SASL type spellable without manually importing the discard crate.