Crate rsasl

Expand description

RSASL is a pure Rust SASL framework designed to make supporting SASL in protocols, doing SASL authentication in application code and adding new Mechanisms simple and safe.

Where to start

I’m implementing some network protocol and I need to add SASL authentication to it!
I’m an user of such a protocol crate and I need to configure my credentials!
I’m both/either/none of those but I have to implement a custom SASL mechanism!

Crates implementing a protocol should allow users to provide an SASL struct at run time. Users construct this struct configuring the supported Mechanisms, their priorities and providing all required information for the authentication exchange, such as username and password.

Protocol crates then call [SASL::suggest_client_mechanism()] or [SASL::suggest_server_mechanism()] to decide on a common Mechanism based on user preference and call SASL::client_start() or SASL::server_start() to actually start an authentication exchange, returning a Session struct. (See the documentation for Session on how to perform the steps of an authentication exchange)

In addition protocol implementations should depend on rsasl like this:

[dependencies]
rsasl = { version = "2", default-features = false, features = ["provider"]}

or, if they need base64 support:

[dependencies]
rsasl = { version = "2", default-features = false, features = ["provider_base64"]}

This makes use of feature unification to make rsasl a (nearly) zero-dependency crate and putting all decisions about compiled-in support and features into the hand of the final user. To this end a protocol crate should not re-export anything from the rsasl crate! Doing so may lead to a situation where users can’t use any mechanisms since they only depend on rsasl via a transient dependency that has no mechanism features enabled.

TODO: How to handle EXTERNAL? TODO: Bonus minus points: sasl.wrap(data) and sasl.unwrap(data) for security layers. Prefer to not and instead do TLS. Needs better explanation I fear.

Application Code

Application code needs to construct a SASL struct that can then be passed to the protocol handler to perform authentication exchanges. You need to provide this SASL struct with either all required information such as username and password beforehand (this is usually the best approach if you know all information beforehand) or by adding a Callback that can request information piece by piece (this is the best approach if you have an interactive client and want to be able to query your users or if you’re implementing a server that has to validate a provided password).

Applications can explicitly enable and disable mechanism support using features, with the default being to add all IANA-registered mechanisms. See the module documentation for mechanisms for details.

Custom Mechanisms

The system to add custom mechanisms is in flux and does not observe the same stability guarantees as the rest of the crate. Breaking changes in this system may happen even for minor changes of the crate version.