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