Crate rsasl

Expand description

RSASL is a pure Rust SASL framework designed to make crates implementing SASL-authenticated protocol not have to worry about SASL.

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 actual authentication exchange)

In addition protocol implementations should add a dependency 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.

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.

TODO: - Static vs Dynamic Registry - Explicit dependency because feature unification

Custom Mechanisms

TODO: - Explain Upstream or separate crate - Explain registry_static / registry_dynamic features => what must mech crates export? - Steps to mechanism: 0. Depend on rsasl with custom_mechanism feature 1. Write impl MechanismBuilder & impl Mechanism 2. Add to Registry 3. Done?