account: add documentation.

- add documentation for hash_pwd_server()
- add documentation for hash_pwd_client()

src/bin/sandbox/sandbox.rs

@@ -10,6 +10,8 @@ use libtrader::ds::server::global_state::GlobalState;
 use libtrader::account::hash_pwd::{hash_pwd_client, hash_pwd_server};
 
 use data_encoding::HEXUPPER;
+use ring::rand::SecureRandom;
+use ring::{digest, rand};
 
 fn main() {
     let mut state: GlobalState = match libtrader_init() {
@@ -40,14 +42,18 @@ fn main() {
    
     info!("state: {:?}\n", state);
 
-    let mut enc = hash_pwd_client("this is my real password").unwrap();
+    let rng = rand::SystemRandom::new();
+    let mut server_salt = [0u8; digest::SHA512_OUTPUT_LEN/2];
+    rng.fill(&mut server_salt).unwrap();
+    let enc = hash_pwd_client("this is my real password", 
+                                  server_salt).unwrap();
 
-    println!("Hash: {}", HEXUPPER.encode(&enc.0));
-    println!("Salt: {}", HEXUPPER.encode(&enc.1));
+    println!("Client Hash: {}", HEXUPPER.encode(&enc.0));
+    println!("Client Salt: {}", HEXUPPER.encode(&enc.1));
 
-    enc = hash_pwd_server(HEXUPPER.encode(&enc.0).as_str()).unwrap();
+    let enc1 = hash_pwd_server(HEXUPPER.encode(&enc.0).as_str()).unwrap();
 
-    println!("Hash: {}", HEXUPPER.encode(&enc.0));
-    println!("Salt: {}", HEXUPPER.encode(&enc.1));
+    println!("Server Hash: {}", HEXUPPER.encode(&enc1.0));
+    println!("Server Salt: {}", HEXUPPER.encode(&enc1.1));
 }
 

src/libtrader/account/hash_pwd.rs

@@ -2,14 +2,35 @@ use ring::rand::SecureRandom;
 use ring::{digest, pbkdf2, rand};
 use std::num::NonZeroU32;
 
-pub fn hash_pwd_client(pass: &str) -> 
-Result<([u8; digest::SHA512_OUTPUT_LEN], [u8;digest::SHA512_OUTPUT_LEN]), String> {
-    let client_iter: NonZeroU32 = NonZeroU32::new(100_000).unwrap();
+/// Generates a client hash from a raw password.
+///
+/// Takes in a raw password, outputs a hashed version of the client password to be sent to the
+/// server with the returned client random bits that make up the whole client salt. This function
+/// is to be used on client side account creation. The result from this function is not be stored
+/// directly on the database, result must be run through the server side hashing again.
+///
+/// Arguments:
+/// pass - The raw user password to be hashed.
+/// server_salt - The server's part sent of the salt.
+///
+/// Returns: a tuple containing the client hash and client's random salt, nothing on failure.
+///
+/// Example:
+/// ```rust
+///     let enc = hash_pwd_client("this is my real password!", server_salt).unwrap();
+///     println!("Client Hash: {}", HEXUPPER.encode(&enc.0));
+///     println!("Client Salt: {}", HEXUPPER.encode(&enc.1));
+/// ```
+pub fn hash_pwd_client(pass: &str, server_salt: [u8; digest::SHA512_OUTPUT_LEN/2]) -> 
+Result<([u8; digest::SHA512_OUTPUT_LEN], [u8; digest::SHA512_OUTPUT_LEN/2]), ()> { // client hash, client random bits
+    let client_iter: NonZeroU32 = NonZeroU32::new(250_000).unwrap();
 
     let rng = rand::SystemRandom::new();
 
-    let mut salt = [0u8; digest::SHA512_OUTPUT_LEN];
-    rng.fill(&mut salt).unwrap();
+    let mut client_salt = [0u8; digest::SHA512_OUTPUT_LEN/2];
+    rng.fill(&mut client_salt).unwrap();
+
+    let salt = [server_salt, client_salt].concat();
 
     let mut hash = [0u8; digest::SHA512_OUTPUT_LEN];
     pbkdf2::derive(
@@ -19,12 +40,29 @@ Result<([u8; digest::SHA512_OUTPUT_LEN], [u8;digest::SHA512_OUTPUT_LEN]), String
         pass.as_bytes(),
         &mut hash);
 
-    Ok((hash, salt))
+    Ok((hash, client_salt))
 }
 
+/// Generates a storable server hash from a client hashed password.
+/// 
+/// Takes in a client hashed password, outputs a storable new hash. The returned result is 'safe'
+/// to be stored on the server side. The salt returned is for the hashed version of the hashed
+/// client password.
+///
+/// Arguments:
+/// hashed_pass - The client hashed password sent to the server. 
+///
+/// Returns: a tuple containing the final hash and the hash's salt, nothing on failure.
+///
+/// Example:
+/// ```rust
+///     let enc = hash_pwd_server("THISISTOTALLYAHASHEDTHING...").unwrap();
+///     println!("Server Hash: {}", HEXUPPER.encode(&enc.0));
+///     println!("Server Salt: {}", HEXUPPER.encode(&enc.1));
+/// ```
 pub fn hash_pwd_server(hashed_pass: &str) -> 
-Result<([u8; digest::SHA512_OUTPUT_LEN], [u8;digest::SHA512_OUTPUT_LEN]), String> {
-    let client_iter: NonZeroU32 = NonZeroU32::new(200_000).unwrap();
+Result<([u8; digest::SHA512_OUTPUT_LEN], [u8;digest::SHA512_OUTPUT_LEN]), ()> {
+    let client_iter: NonZeroU32 = NonZeroU32::new(500_000).unwrap();
     
     let rng = rand::SystemRandom::new();