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