Rename client entry point and reexport them

The entry point for the client implementation `client::ClientFirst` is
now called `client::ScramClient`, similar to the `server` module.

The entry points `client::ScramClient` and `server::ScramServer` are now
reexported at the crate root, as well as other often used structs.

Author: Thomas Bahn

README.md

@@ -1,16 +1,20 @@
 # Salted Challenge Response Authentication Mechanism (SCRAM)
 
-This implementation currently provides a client for the SCRAM-SHA-256 mechanism according to
+This implementation provides a client and a server for the SCRAM-SHA-256 mechanism according to
 RFC5802 and RFC7677. It doesn't support channel-binding.
 
 [Read the documentation.](https://tomprogrammer.github.io/scram/scram/index.html)
 
 # Limitations
 
-There is no server-side implementation of the SCRAM mechanism and no SHA-1 support. If you like to contribute or maintain them I appreciate that.
+The mandatory SCRAM-SHA-1 authentication mechanism is currently not implemented. This is also true
+for the *-PLUS variants, because channel-binding is not supported by this library. If you like to
+contribute or maintain them I appreciate that.
 
 # Usage
 
+## Client
+
 A typical usage scenario is shown below. For a detailed explanation of the methods please
 consider their documentation. In productive code you should replace the unwrapping by proper
 error handling.
@@ -25,15 +29,15 @@ and `handle_server_final` on the different types advances the SCRAM handshake st
 Computing client messages never fails but processing server messages can result in failure.
 
 ```rust
-use scram::ClientFirst;
+use scram::ScramClient;
 
 // This function represents your I/O implementation.
 fn send_and_receive(message: &str) -> String {
     unimplemented!()
 }
 
 // Create a SCRAM state from the credentials.
-let scram = ClientFirst::new("user", "password", None).unwrap();
+let scram = ScramClient::new("user", "password", None).unwrap();
 
 // Get the client message and reassign the SCRAM state.
 let (scram, client_first) = scram.client_first();
@@ -55,3 +59,68 @@ let server_final = send_and_receive(&client_final);
 // wasn't successful.
 let () = scram.handle_server_final(&server_final).unwrap();
 ```
+
+## Server
+
+The server is created to respond to incoming challenges from a client.  A typical usage pattern,
+with a default provider is shown below.  In production, you would implement an AuthenticationProvider
+that could look up user credentials based on a username
+
+The server and the client exchange four messages using the SCRAM mechanism. There is a rust type for
+each one of them. Calling the methods `handle_client_first()`, `server_first()`,
+`handle_client_final()` and `server_final()` on the different types advances the SCRAM handshake
+step by step. Computing server messages never fails (unless the source of randomness for the nonce
+fails), but processing client messages can result in failure.
+
+The final step will not return an error if authentication failed, but will return an
+`AuthenticationStatus` which you can use to determine if authentication was successful or not.
+
+```rust
+use scram::{ScramServer, AuthenticationStatus, AuthenticationProvider, PasswordInfo};
+
+// Create a dummy authentication provider
+struct ExampleProvider;
+impl AuthenticationProvider for ExampleProvider {
+    // Here you would look up password information for the the given username
+    fn get_password_for(&self, username: &str) -> Option<PasswordInfo> {
+       unimplemented!()
+    }
+
+}
+// These functions represent your I/O implementation.
+# #[allow(unused_variables)]
+fn receive() -> String {
+    unimplemented!()
+}
+# #[allow(unused_variables)]
+fn send(message: &str) {
+    unimplemented!()
+}
+
+// Create a new ScramServer using the example authenication provider
+let scram_server = ScramServer::new(ExampleProvider{});
+
+// Receive a message from the client
+let client_first = receive();
+
+// Create a SCRAM state from the client's first message
+let scram_server = scram_server.handle_client_first(&client_first).unwrap();
+// Craft a response to the client's message and advance the SCRAM state
+// We could use our own source of randomness here, with `server_first_with_rng()`
+let (scram_server, server_first) = scram_server.server_first().unwrap();
+// Send our message to the client and read the response
+send(&server_first);
+let client_final = receive();
+
+// Process the client's challenge and re-assign the SCRAM state.  This could fail if the
+// message was poorly formatted
+let scram_server = scram_server.handle_client_final(&client_final).unwrap();
+
+// Prepare the final message and get the authentication status
+let(status, server_final) = scram_server.server_final();
+// Send our final message to the client
+send(&server_final);
+
+// Check if the client successfully authenticated
+assert_eq!(status, AuthenticationStatus::Authenticated);
+```

src/client.rs

@@ -12,6 +12,9 @@ use utils::{hash_password, find_proofs};
 use error::{Error, Kind, Field};
 use NONCE_LENGTH;
 
+#[deprecated(since = "0.2.0", note = "Please use `ScramClient` instead. (exported at crate root)")]
+pub type ClientFirst<'a> = ScramClient<'a>;
+
 /// Parses a `server_first_message` returning a (none, salt, iterations) tuple if successful.
 fn parse_server_first(data: &str) -> Result<(&str, Vec<u8>, u16), Error> {
     if data.len() < 2 {
@@ -72,14 +75,14 @@ fn parse_server_final(data: &str) -> Result<Vec<u8>, Error> {
 
 /// The initial state of the SCRAM mechanism. It's the entry point for a SCRAM handshake.
 #[derive(Debug)]
-pub struct ClientFirst<'a> {
+pub struct ScramClient<'a> {
     gs2header: Cow<'static, str>,
     password: &'a str,
     nonce: String,
     authcid: &'a str,
 }
 
-impl<'a> ClientFirst<'a> {
+impl<'a> ScramClient<'a> {
     /// Constructs an initial state for the SCRAM mechanism using the provided credentials.
     ///
     /// # Arguments
@@ -127,7 +130,7 @@ impl<'a> ClientFirst<'a> {
             })
             .collect();
 
-        ClientFirst {
+        ScramClient {
             gs2header: gs2header,
             password: password,
             authcid: authcid,

src/lib.rs

@@ -1,7 +1,7 @@
 //! # Salted Challenge Response Authentication Mechanism (SCRAM)
 //!
-//! This implementation currently provides a client for the SCRAM-SHA-256 mechanism according to
-//! RFC5802 and RFC7677. It doesn't support channel-binding.
+//! This implementation currently provides a client and a server for the SCRAM-SHA-256 mechanism
+//! according to RFC5802 and RFC7677. It doesn't support channel-binding.
 //!
 //! # Usage
 //!
@@ -25,7 +25,7 @@
 //! processing server messages can result in failure.
 //!
 //! ``` rust,no_run
-//! use scram::client::ClientFirst;
+//! use scram::ScramClient;
 //!
 //! // This function represents your I/O implementation.
 //! # #[allow(unused_variables)]
@@ -34,7 +34,7 @@
 //! }
 //!
 //! // Create a SCRAM state from the credentials.
-//! let scram = ClientFirst::new("user", "password", None).unwrap();
+//! let scram = ScramClient::new("user", "password", None).unwrap();
 //!
 //! // Get the client message and reassign the SCRAM state.
 //! let (scram, client_first) = scram.client_first();
@@ -78,7 +78,7 @@
 //! if authentication was successful or not.
 //!
 //! ```rust,no_run
-//! use scram::server::{ScramServer, AuthenticationStatus, AuthenticationProvider, PasswordInfo};
+//! use scram::{ScramServer, AuthenticationStatus, AuthenticationProvider, PasswordInfo};
 //!
 //! // Create a dummy authentication provider
 //! struct ExampleProvider;
@@ -139,5 +139,7 @@ mod error;
 pub mod client;
 pub mod server;
 
+pub use client::ScramClient;
 pub use error::{Error, Kind, Field};
+pub use server::{ScramServer, AuthenticationProvider, PasswordInfo, AuthenticationStatus};
 pub use utils::hash_password;

src/server.rs

@@ -28,7 +28,7 @@ pub struct PasswordInfo {
     iterations: u16,
 }
 
-/// The status of authenication after the final client message has been received by the server.
+/// The status of authentication after the final client message has been received by the server.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub enum AuthenticationStatus {
     /// The client has correctly authenticated, and has been authorized.
@@ -308,7 +308,6 @@ impl<'a, P: AuthenticationProvider> ClientFinal<'a, P> {
 
         let server_signature_string = format!("v={}", base64::encode(server_signature.as_ref()));
         Ok(Some(server_signature_string))
-
     }
 }
 

tests/client_server.rs

@@ -46,8 +46,8 @@ impl server::AuthenticationProvider for TestProvider {
 
 #[test]
 fn test_simple_success() {
-    let scram_client = client::ClientFirst::new("user", "password", None).unwrap();
-    let scram_server = server::ScramServer::new(TestProvider::new());
+    let scram_client = ScramClient::new("user", "password", None).unwrap();
+    let scram_server = ScramServer::new(TestProvider::new());
 
     let (scram_client, client_first) = scram_client.client_first();
 
@@ -62,13 +62,13 @@ fn test_simple_success() {
 
     scram_client.handle_server_final(&server_final).unwrap();
 
-    assert_eq!(status, server::AuthenticationStatus::Authenticated);
+    assert_eq!(status, AuthenticationStatus::Authenticated);
 }
 
 #[test]
 fn test_bad_password() {
-    let scram_client = client::ClientFirst::new("user", "badpassword", None).unwrap();
-    let scram_server = server::ScramServer::new(TestProvider::new());
+    let scram_client = ScramClient::new("user", "badpassword", None).unwrap();
+    let scram_server = ScramServer::new(TestProvider::new());
 
     let (scram_client, client_first) = scram_client.client_first();
 
@@ -81,14 +81,14 @@ fn test_bad_password() {
     let scram_server = scram_server.handle_client_final(&client_final).unwrap();
     let (status, server_final) = scram_server.server_final();
 
-    assert_eq!(status, server::AuthenticationStatus::NotAuthenticated);
+    assert_eq!(status, AuthenticationStatus::NotAuthenticated);
     assert!(scram_client.handle_server_final(&server_final).is_err());
 }
 
 #[test]
 fn test_authorize_different() {
-    let scram_client = client::ClientFirst::new("admin", "admin_password", Some("user")).unwrap();
-    let scram_server = server::ScramServer::new(TestProvider::new());
+    let scram_client = ScramClient::new("admin", "admin_password", Some("user")).unwrap();
+    let scram_server = ScramServer::new(TestProvider::new());
 
     let (scram_client, client_first) = scram_client.client_first();
 
@@ -103,13 +103,13 @@ fn test_authorize_different() {
 
     scram_client.handle_server_final(&server_final).unwrap();
 
-    assert_eq!(status, server::AuthenticationStatus::Authenticated);
+    assert_eq!(status, AuthenticationStatus::Authenticated);
 }
 
 #[test]
 fn test_authorize_fail() {
-    let scram_client = client::ClientFirst::new("user", "password", Some("admin")).unwrap();
-    let scram_server = server::ScramServer::new(TestProvider::new());
+    let scram_client = ScramClient::new("user", "password", Some("admin")).unwrap();
+    let scram_server = ScramServer::new(TestProvider::new());
 
     let (scram_client, client_first) = scram_client.client_first();
 
@@ -122,15 +122,15 @@ fn test_authorize_fail() {
     let scram_server = scram_server.handle_client_final(&client_final).unwrap();
     let (status, server_final) = scram_server.server_final();
 
-    assert_eq!(status, server::AuthenticationStatus::NotAuthorized);
+    assert_eq!(status, AuthenticationStatus::NotAuthorized);
     assert!(scram_client.handle_server_final(&server_final).is_err());
 }
 
 #[test]
 fn test_authorize_non_existent() {
-    let scram_client = client::ClientFirst::new("admin", "admin_password", Some("nonexistent"))
+    let scram_client = ScramClient::new("admin", "admin_password", Some("nonexistent"))
         .unwrap();
-    let scram_server = server::ScramServer::new(TestProvider::new());
+    let scram_server = ScramServer::new(TestProvider::new());
 
     let (scram_client, client_first) = scram_client.client_first();
 
@@ -143,14 +143,14 @@ fn test_authorize_non_existent() {
     let scram_server = scram_server.handle_client_final(&client_final).unwrap();
     let (status, server_final) = scram_server.server_final();
 
-    assert_eq!(status, server::AuthenticationStatus::NotAuthorized);
+    assert_eq!(status, AuthenticationStatus::NotAuthorized);
     assert!(scram_client.handle_server_final(&server_final).is_err());
 }
 
 #[test]
 fn test_invalid_user() {
-    let scram_client = client::ClientFirst::new("nobody", "password", None).unwrap();
-    let scram_server = server::ScramServer::new(TestProvider::new());
+    let scram_client = ScramClient::new("nobody", "password", None).unwrap();
+    let scram_server = ScramServer::new(TestProvider::new());
 
     let (_, client_first) = scram_client.client_first();
 
@@ -159,8 +159,8 @@ fn test_invalid_user() {
 
 #[test]
 fn test_empty_username() {
-    let scram_client = client::ClientFirst::new("", "password", None).unwrap();
-    let scram_server = server::ScramServer::new(TestProvider::new());
+    let scram_client = ScramClient::new("", "password", None).unwrap();
+    let scram_server = ScramServer::new(TestProvider::new());
 
     let (_, client_first) = scram_client.client_first();
 
@@ -169,8 +169,8 @@ fn test_empty_username() {
 
 #[test]
 fn test_empty_password() {
-    let scram_client = client::ClientFirst::new("user", "", None).unwrap();
-    let scram_server = server::ScramServer::new(TestProvider::new());
+    let scram_client = ScramClient::new("user", "", None).unwrap();
+    let scram_server = ScramServer::new(TestProvider::new());
 
     let (scram_client, client_first) = scram_client.client_first();
 
@@ -183,6 +183,6 @@ fn test_empty_password() {
     let scram_server = scram_server.handle_client_final(&client_final).unwrap();
     let (status, server_final) = scram_server.server_final();
 
-    assert_eq!(status, server::AuthenticationStatus::NotAuthenticated);
+    assert_eq!(status, AuthenticationStatus::NotAuthenticated);
     assert!(scram_client.handle_server_final(&server_final).is_err());
 }