cleaned up channel binding logic, cleaned up SaslCredentials, updated documentation

sasl/Cargo.toml

@@ -2,7 +2,7 @@
 name = "sasl"
 version = "0.1.1"
 authors = ["lumi <lumi@pew.im>"]
-description = "A crate for SASL authentication. Still needs a bunch of documenation."
+description = "A crate for SASL authentication."
 homepage = "https://gitlab.com/lumi/sasl-rs"
 repository = "https://gitlab.com/lumi/sasl-rs"
 documentation = "https://docs.rs/sasl"

sasl/README.md

@@ -6,6 +6,11 @@ What's this?
 
 A crate which handles SASL authentication.
 
+Can I see an example?
+---------------------
+
+Look at the documentation [here](https://docs.rs/sasl).
+
 What license is it under?
 -------------------------
 

sasl/src/lib.rs

@@ -5,14 +5,12 @@
 //! # Examples
 //!
 //! ```rust
-//! use sasl::{SaslCredentials, SaslSecret, SaslMechanism, Error};
+//! use sasl::{SaslCredentials, SaslMechanism, Error};
 //! use sasl::mechanisms::Plain;
 //!
-//! let creds = SaslCredentials {
-//!     username: "user".to_owned(),
-//!     secret: SaslSecret::Password("pencil".to_owned()),
-//!     channel_binding: None,
-//! };
+//! let creds = SaslCredentials::default()
+//!                             .with_username("user")
+//!                             .with_password("pencil");
 //!
 //! let mut mechanism = Plain::from_credentials(creds).unwrap();
 //!
@@ -39,16 +37,75 @@ mod error;
 pub use error::Error;
 
 /// A struct containing SASL credentials.
+#[derive(Clone, Debug)]
 pub struct SaslCredentials {
     /// The requested username.
-    pub username: String, // TODO: change this since some mechanisms do not use it
+    pub username: Option<String>,
     /// The secret used to authenticate.
     pub secret: SaslSecret,
-    /// Optionally, channel binding data, for *-PLUS mechanisms.
-    pub channel_binding: Option<Vec<u8>>,
+    /// Channel binding data, for *-PLUS mechanisms.
+    pub channel_binding: ChannelBinding,
+}
+
+impl Default for SaslCredentials {
+    fn default() -> SaslCredentials {
+        SaslCredentials {
+            username: None,
+            secret: SaslSecret::None,
+            channel_binding: ChannelBinding::None,
+        }
+    }
+}
+
+impl SaslCredentials {
+    /// Creates a new SaslCredentials with the specified username.
+    pub fn with_username<N: Into<String>>(mut self, username: N) -> SaslCredentials {
+        self.username = Some(username.into());
+        self
+    }
+
+    /// Creates a new SaslCredentials with the specified password.
+    pub fn with_password<P: Into<String>>(mut self, password: P) -> SaslCredentials {
+        self.secret = SaslSecret::Password(password.into());
+        self
+    }
+
+    /// Creates a new SaslCredentials with the specified chanel binding.
+    pub fn with_channel_binding(mut self, channel_binding: ChannelBinding) -> SaslCredentials {
+        self.channel_binding = channel_binding;
+        self
+    }
+}
+
+/// Channel binding configuration.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ChannelBinding {
+    /// No channel binding data.
+    None,
+    /// p=tls-unique channel binding data.
+    TlsUnique(Vec<u8>),
+}
+
+impl ChannelBinding {
+    /// Return the gs2 header for this channel binding mechanism.
+    pub fn header(&self) -> &[u8] {
+        match *self {
+            ChannelBinding::None => b"n,,",
+            ChannelBinding::TlsUnique(_) => b"p=tls-unique,,",
+        }
+    }
+
+    /// Return the channel binding data for this channel binding mechanism.
+    pub fn data(&self) -> &[u8] {
+        match *self {
+            ChannelBinding::None => &[],
+            ChannelBinding::TlsUnique(ref data) => data,
+        }
+    }
 }
 
 /// Represents a SASL secret, like a password.
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub enum SaslSecret {
     /// No extra data needed.
     None,

sasl/src/mechanisms/plain.rs

@@ -28,7 +28,12 @@ impl SaslMechanism for Plain {
 
     fn from_credentials(credentials: SaslCredentials) -> Result<Plain, String> {
         if let SaslSecret::Password(password) = credentials.secret {
-            Ok(Plain::new(credentials.username, password))
+            if let Some(username) = credentials.username {
+                Ok(Plain::new(username, password))
+            }
+            else {
+                Err("PLAIN requires a username".to_owned())
+            }
         }
         else {
             Err("PLAIN requires a password".to_owned())

sasl/src/mechanisms/scram.rs

@@ -5,6 +5,7 @@ use base64;
 use SaslMechanism;
 use SaslCredentials;
 use SaslSecret;
+use ChannelBinding;
 
 use error::Error;
 
@@ -138,33 +139,31 @@ pub struct Scram<S: ScramProvider> {
     password: String,
     client_nonce: String,
     state: ScramState,
-    channel_binding: Option<Vec<u8>>,
+    channel_binding: ChannelBinding,
     _marker: PhantomData<S>,
 }
 
 impl<S: ScramProvider> Scram<S> {
-    /// Constructs a new struct for authenticating using the SASL SCRAM-* mechanism.
+    /// Constructs a new struct for authenticating using the SASL SCRAM-* and SCRAM-*-PLUS
+    /// mechanisms, depending on the passed channel binding.
     ///
     /// It is recommended that instead you use a `SaslCredentials` struct and turn it into the
     /// requested mechanism using `from_credentials`.
-    pub fn new<N: Into<String>, P: Into<String>>(username: N, password: P) -> Result<Scram<S>, Error> {
+    pub fn new<N: Into<String>, P: Into<String>>(username: N, password: P, channel_binding: ChannelBinding) -> Result<Scram<S>, Error> {
         Ok(Scram {
             name: format!("SCRAM-{}", S::name()),
             username: username.into(),
             password: password.into(),
             client_nonce: generate_nonce()?,
             state: ScramState::Init,
-            channel_binding: None,
+            channel_binding: channel_binding,
             _marker: PhantomData,
         })
     }
 
-    /// Constructs a new struct for authenticating using the SASL SCRAM-* mechanism.
-    ///
-    /// This one takes a nonce instead of generating it.
-    ///
-    /// It is recommended that instead you use a `SaslCredentials` struct and turn it into the
-    /// requested mechanism using `from_credentials`.
+    // Used for testing.
+    #[doc(hidden)]
+    #[cfg(test)]
     pub fn new_with_nonce<N: Into<String>, P: Into<String>>(username: N, password: P, nonce: String) -> Scram<S> {
         Scram {
             name: format!("SCRAM-{}", S::name()),
@@ -172,29 +171,10 @@ impl<S: ScramProvider> Scram<S> {
             password: password.into(),
             client_nonce: nonce,
             state: ScramState::Init,
-            channel_binding: None,
+            channel_binding: ChannelBinding::None,
             _marker: PhantomData,
         }
     }
-
-    /// Constructs a new struct for authenticating using the SASL SCRAM-*-PLUS mechanism.
-    ///
-    /// This means that this function will also take the channel binding data.
-    ///
-    /// It is recommended that instead you use a `SaslCredentials` struct and turn it into the
-    /// requested mechanism using `from_credentials`.
-    pub fn new_with_channel_binding<N: Into<String>, P: Into<String>>(username: N, password: P, channel_binding: Vec<u8>) -> Result<Scram<S>, Error> {
-        // TODO: channel binding modes other than tls-unique
-        Ok(Scram {
-            name: format!("SCRAM-{}-PLUS", S::name()),
-            username: username.into(),
-            password: password.into(),
-            client_nonce: generate_nonce()?,
-            state: ScramState::Init,
-            channel_binding: Some(channel_binding),
-            _marker: PhantomData,
-        })
-    }
 }
 
 impl<S: ScramProvider> SaslMechanism for Scram<S> {
@@ -204,13 +184,12 @@ impl<S: ScramProvider> SaslMechanism for Scram<S> {
 
     fn from_credentials(credentials: SaslCredentials) -> Result<Scram<S>, String> {
         if let SaslSecret::Password(password) = credentials.secret {
-            if let Some(binding) = credentials.channel_binding {
-                Scram::new_with_channel_binding(credentials.username, password, binding)
+            if let Some(username) = credentials.username {
+                Scram::new(username, password, credentials.channel_binding)
                       .map_err(|_| "can't generate nonce".to_owned())
             }
             else {
-                Scram::new(credentials.username, password)
-                      .map_err(|_| "can't generate nonce".to_owned())
+                Err("SCRAM requires a username".to_owned())
             }
         }
         else {
@@ -220,12 +199,7 @@ impl<S: ScramProvider> SaslMechanism for Scram<S> {
 
     fn initial(&mut self) -> Result<Vec<u8>, String> {
         let mut gs2_header = Vec::new();
-        if let Some(_) = self.channel_binding {
-            gs2_header.extend(b"p=tls-unique,,");
-        }
-        else {
-            gs2_header.extend(b"n,,");
-        }
+        gs2_header.extend(self.channel_binding.header());
         let mut bare = Vec::new();
         bare.extend(b"n=");
         bare.extend(self.username.bytes());
@@ -255,9 +229,7 @@ impl<S: ScramProvider> SaslMechanism for Scram<S> {
                 client_final_message_bare.extend(b"c=");
                 let mut cb_data: Vec<u8> = Vec::new();
                 cb_data.extend(gs2_header);
-                if let Some(ref cb) = self.channel_binding {
-                    cb_data.extend(cb);
-                }
+                cb_data.extend(self.channel_binding.data());
                 client_final_message_bare.extend(base64::encode(&cb_data).bytes());
                 client_final_message_bare.extend(b",r=");
                 client_final_message_bare.extend(server_nonce.bytes());