sasl/
lib.rs

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;
sasl/lib.rs

sasl/
lib.rs
