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:

EXTERNAL
ANONYMOUS
PLAIN
LOGIN
CRAM-MD5
DIGEST-MD5
SCRAM-SHA-1
NTLM
SECURID
GSSAPI
GS2-KRB5
SAML20
OPENID20
KERBEROS_V5

Usage

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.

Properties

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.

Callbacks

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"),
    }
}