1//#![deny(missing_docs)]
2#![no_std]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4#![cfg_attr(docsrs, doc(auto_cfg))]
5
6//! This crate provides a framework for SASL authentication and a few authentication mechanisms.
7//!
8//! It can be used in `no_std` environments.
9//!
10//! # Examples
11//!
12//! ## Simple client-sided usage
13//!
14//! ```rust
15//! use sasl::client::Mechanism;
16//! use sasl::common::Credentials;
17//! use sasl::client::mechanisms::Plain;
18//!
19//! let creds = Credentials::default()
20//! .with_username("user")
21//! .with_password("pencil");
22//!
23//! let mut mechanism = Plain::from_credentials(creds).unwrap();
24//!
25//! let initial_data = mechanism.initial();
26//!
27//! assert_eq!(initial_data, b"\0user\0pencil");
28//! ```
29//!
30//! ## More complex usage
31//!
32#![cfg_attr(feature = "scram", doc = "```rust\n")]
33#![cfg_attr(not(feature = "scram"), doc = "```rust,ignore\n")]
34//! #[macro_use] extern crate sasl;
35//!
36//! use sasl::server::{Validator, Provider, Mechanism as ServerMechanism, Response};
37//! use sasl::server::{ValidatorError, ProviderError, MechanismError as ServerMechanismError};
38//! use sasl::server::mechanisms::{Plain as ServerPlain, Scram as ServerScram};
39//! use sasl::client::{Mechanism as ClientMechanism, MechanismError as ClientMechanismError};
40//! use sasl::client::mechanisms::{Plain as ClientPlain, Scram as ClientScram};
41//! use sasl::common::{Identity, Credentials, Password, ChannelBinding};
42//! use sasl::common::scram::{ScramProvider, Sha1, Sha256};
43//! use sasl::secret;
44//!
45//! const USERNAME: &'static str = "user";
46//! const PASSWORD: &'static str = "pencil";
47//! const SALT: [u8; 8] = [35, 71, 92, 105, 212, 219, 114, 93];
48//! const ITERATIONS: u32 = 4096;
49//!
50//! struct MyValidator;
51//!
52//! impl Validator<secret::Plain> for MyValidator {
53//! fn validate(&self, identity: &Identity, value: &secret::Plain) -> Result<(), ValidatorError> {
54//! let &secret::Plain(ref password) = value;
55//! if identity != &Identity::Username(USERNAME.to_owned()) {
56//! Err(ValidatorError::AuthenticationFailed)
57//! }
58//! else if password != PASSWORD {
59//! Err(ValidatorError::AuthenticationFailed)
60//! }
61//! else {
62//! Ok(())
63//! }
64//! }
65//! }
66//!
67//! impl Provider<secret::Pbkdf2Sha1> for MyValidator {
68//! fn provide(&self, identity: &Identity) -> Result<secret::Pbkdf2Sha1, ProviderError> {
69//! if identity != &Identity::Username(USERNAME.to_owned()) {
70//! Err(ProviderError::AuthenticationFailed)
71//! }
72//! else {
73//! let digest = sasl::common::scram::Sha1::derive
74//! ( &Password::Plain((PASSWORD.to_owned()))
75//! , &SALT[..]
76//! , ITERATIONS )?;
77//! Ok(secret::Pbkdf2Sha1 {
78//! salt: SALT.to_vec(),
79//! iterations: ITERATIONS,
80//! digest: digest,
81//! })
82//! }
83//! }
84//! }
85//!
86//! impl_validator_using_provider!(MyValidator, secret::Pbkdf2Sha1);
87//!
88//! impl Provider<secret::Pbkdf2Sha256> for MyValidator {
89//! fn provide(&self, identity: &Identity) -> Result<secret::Pbkdf2Sha256, ProviderError> {
90//! if identity != &Identity::Username(USERNAME.to_owned()) {
91//! Err(ProviderError::AuthenticationFailed)
92//! }
93//! else {
94//! let digest = sasl::common::scram::Sha256::derive
95//! ( &Password::Plain((PASSWORD.to_owned()))
96//! , &SALT[..]
97//! , ITERATIONS )?;
98//! Ok(secret::Pbkdf2Sha256 {
99//! salt: SALT.to_vec(),
100//! iterations: ITERATIONS,
101//! digest: digest,
102//! })
103//! }
104//! }
105//! }
106//!
107//! impl_validator_using_provider!(MyValidator, secret::Pbkdf2Sha256);
108//!
109//! #[derive(Debug, PartialEq)]
110//! enum MechanismError {
111//! Client(ClientMechanismError),
112//! Server(ServerMechanismError),
113//! }
114//!
115//! impl From<ClientMechanismError> for MechanismError {
116//! fn from(err: ClientMechanismError) -> MechanismError {
117//! MechanismError::Client(err)
118//! }
119//! }
120//!
121//! impl From<ServerMechanismError> for MechanismError {
122//! fn from(err: ServerMechanismError) -> MechanismError {
123//! MechanismError::Server(err)
124//! }
125//! }
126//!
127//! fn finish<CM, SM>(cm: &mut CM, sm: &mut SM) -> Result<Identity, MechanismError>
128//! where CM: ClientMechanism,
129//! SM: ServerMechanism {
130//! let init = cm.initial();
131//! println!("C: {}", String::from_utf8_lossy(&init));
132//! let mut resp = sm.respond(&init)?;
133//! loop {
134//! let msg;
135//! match resp {
136//! Response::Proceed(ref data) => {
137//! println!("S: {}", String::from_utf8_lossy(&data));
138//! msg = cm.response(data)?;
139//! println!("C: {}", String::from_utf8_lossy(&msg));
140//! },
141//! _ => break,
142//! }
143//! resp = sm.respond(&msg)?;
144//! }
145//! if let Response::Success(ret, fin) = resp {
146//! println!("S: {}", String::from_utf8_lossy(&fin));
147//! cm.success(&fin)?;
148//! Ok(ret)
149//! }
150//! else {
151//! unreachable!();
152//! }
153//! }
154//!
155//! fn main() {
156//! let mut mech = ServerPlain::new(MyValidator);
157//! let expected_response = Response::Success(Identity::Username("user".to_owned()), Vec::new());
158//! assert_eq!(mech.respond(b"\0user\0pencil"), Ok(expected_response));
159//!
160//! let mut mech = ServerPlain::new(MyValidator);
161//! assert_eq!(mech.respond(b"\0user\0marker"), Err(ServerMechanismError::ValidatorError(ValidatorError::AuthenticationFailed)));
162//!
163//! let creds = Credentials::default()
164//! .with_username(USERNAME)
165//! .with_password(PASSWORD);
166//! let mut client_mech = ClientPlain::from_credentials(creds.clone()).unwrap();
167//! let mut server_mech = ServerPlain::new(MyValidator);
168//!
169//! assert_eq!(finish(&mut client_mech, &mut server_mech), Ok(Identity::Username(USERNAME.to_owned())));
170//!
171//! let mut client_mech = ClientScram::<Sha1>::from_credentials(creds.clone()).unwrap();
172//! let mut server_mech = ServerScram::<Sha1, _>::new(MyValidator, ChannelBinding::Unsupported);
173//!
174//! assert_eq!(finish(&mut client_mech, &mut server_mech), Ok(Identity::Username(USERNAME.to_owned())));
175//!
176//! let mut client_mech = ClientScram::<Sha256>::from_credentials(creds.clone()).unwrap();
177//! let mut server_mech = ServerScram::<Sha256, _>::new(MyValidator, ChannelBinding::Unsupported);
178//!
179//! assert_eq!(finish(&mut client_mech, &mut server_mech), Ok(Identity::Username(USERNAME.to_owned())));
180//! }
181//! ```
182//!
183//! # Usage
184//!
185//! You can use this in your crate by adding this under `dependencies` in your `Cargo.toml`:
186//!
187//! ```toml
188//! sasl = "*"
189//! ```
190
191extern crate alloc;
192
193mod error;
194
195pub mod client;
196#[macro_use]
197pub mod server;
198pub mod common;
199pub mod secret;
200
201pub use crate::error::Error;