Docstring updates and misc cleanups

5 files changed, 62 insertions, 31 deletions

diff --git a/src/config/memory.rs b/src/config/memory.rs
index 0f65be1..aaf2e08 100644
--- a/src/config/memory.rs
+++ b/src/config/memory.rs
@@ -19,9 +19,9 @@ use std::time::Duration;
 
 use hex;
 
-/// A purely in-memory Roughenough config
-/// This is useful for fuzzing a server without the need
-/// to create additioanl files.
+/// A purely in-memory Roughenough config for testing purposes.
+///
+/// This is useful for testing or fuzzing a server without the need to create additional files.
 pub struct MemoryConfig {
     pub port: u16,
     pub interface: String,
diff --git a/src/kms/envelope.rs b/src/kms/envelope.rs
index 00206de..bc75994 100644
--- a/src/kms/envelope.rs
+++ b/src/kms/envelope.rs
@@ -15,7 +15,6 @@
 extern crate hex;
 
 use std::io::{Cursor, Read, Write};
-use std::str::FromStr;
 
 use ring::aead::{open_in_place, seal_in_place, OpeningKey, SealingKey, AES_256_GCM};
 use ring::rand::{SecureRandom, SystemRandom};
@@ -175,12 +174,9 @@ impl EnvelopeEncryption {
 
 #[cfg(test)]
 mod test {
-    use hex;
     use kms::envelope::{DEK_LEN_FIELD, MIN_PAYLOAD_SIZE, NONCE_LEN_FIELD};
     use kms::EnvelopeEncryption;
     use kms::{KmsError, KmsProvider};
-    use std::str::FromStr;
-    use std::string::ToString;
 
     struct MockKmsProvider {}
 
diff --git a/src/kms/mod.rs b/src/kms/mod.rs
index b411578..ef3dd58 100644
--- a/src/kms/mod.rs
+++ b/src/kms/mod.rs
@@ -193,11 +193,23 @@ pub fn load_seed(config: &Box<ServerConfig>) -> Result<Vec<u8>, error::Error> {
     }
 }
 
-///
+
 /// Load the seed value for the long-term key.
 ///
-/// The KMS feature was disabled in this build of Roughenough. The only supported `key_protection`
-/// value is `plaintext`. Any other value is an error.
+/// Loading behavior depends on the value of `config.key_protection()`:
+///
+///  * If `config.key_protection() == Plaintext` then the value returned from `config.seed()`
+///    is used as-is and assumed to be a 32-byte hexadecimal value.
+///
+///  * Otherwise `config.seed()` is assumed to be an encrypted opaque blob generated from
+///    a prior `EnvelopeEncryption::encrypt_seed` call. The value of `config.key_protection()`
+///    is parsed as a KMS key id and `EnvelopeEncryption::decrypt_seed` is called to obtain
+///    the plaintext seed value.
+///
+/// ## KMS Disabled
+///
+/// The KMS feature is *disabled* in this build of Roughenough. The only
+/// supported `key_protection` value is `plaintext`. Any other value is an error.
 ///
 #[cfg(all(not(feature = "awskms"), not(feature = "gcpkms")))]
 pub fn load_seed(config: &Box<ServerConfig>) -> Result<Vec<u8>, error::Error> {
diff --git a/src/lib.rs b/src/lib.rs
index 25d4730..614dd90 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -47,8 +47,12 @@
 //!
 //! # Server
 //!
-//! The Roughtime server implementation is in `src/bin/server.rs`. The server has multiple
-//! ways it can be configured, see [`ServerConfig`](config/trait.ServerConfig.html) for details.
+//! The core Roughtime server implementation is in `src/server.rs` and the server's CLI can
+//! be found in `src/bin/roughenough-server.rs`.
+//!
+//! The server has multiple ways it can be configured,
+//! see [`ServerConfig`](config/trait.ServerConfig.html) for the configuration trait and
+//!
 //!
 
 extern crate base64;
diff --git a/src/server.rs b/src/server.rs
index fa26b34..26f9428 100644
--- a/src/server.rs
+++ b/src/server.rs
@@ -12,6 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//!
+//! Implements the Roughenough server functionality.
+//!
+
 use hex;
 use std::io::ErrorKind;
 use std::net::SocketAddr;
@@ -46,10 +50,16 @@ macro_rules! check_ctrlc {
 const MESSAGE: Token = Token(0);
 const STATUS: Token = Token(1);
 
-/// The main server instance.
-/// A Server is initialiezd from a Server Config
-/// and processes incoming messages in
-/// 'process_events'
+/// The main Roughenough server instance.
+///
+/// The [ServerConfig](../config/trait.ServerConfig.html) trait specifies the required and optional
+/// parameters available for configuring a Roughenoguh server instance.
+///
+/// Implementations of `ServerConfig` obtain configurations from different back-end sources
+/// such as files or environment variables.
+///
+/// See [the config module](../config/index.html) for more information.
+///
 pub struct Server {
     config: Box<ServerConfig>,
     online_key: OnlineKey,
@@ -70,12 +80,17 @@ pub struct Server {
 
     public_key: String,
 
-    // Used to send requests to outselves in fuzing mode
+    // Used to send requests to ourselves in fuzzing mode
     #[cfg(fuzzing)]
     fake_client_socket: UdpSocket,
 }
 
 impl Server {
+
+    ///
+    /// Create a new server instance from the provided
+    /// [`ServerConfig`](../config/trait.ServerConfig.html) trait object instance.
+    ///
     pub fn new(config: Box<ServerConfig>) -> Server {
         let online_key = OnlineKey::new();
         let public_key: String;
@@ -138,6 +153,7 @@ impl Server {
         }
     }
 
+    /// Returns a reference counted pointer the this server's `keep_running` value.
     pub fn get_keep_running(&self) -> Arc<AtomicBool> {
         return self.keep_running.clone();
     }
@@ -188,10 +204,10 @@ impl Server {
         response
     }
 
-    /// The main processing function for incoming connections.
-    /// This method should be called repeatedly in a loop
-    /// to process requests. It returns 'true' when the server
-    /// has shutdown (due to keep_running being set to 'false')
+    /// The main processing function for incoming connections. This method should be
+    /// called repeatedly in a loop to process requests. It returns 'true' when the
+    /// server has shutdown (due to keep_running being set to 'false').
+    ///
     pub fn process_events(&mut self) -> bool {
         self.poll
             .poll(&mut self.events, self.poll_duration)
@@ -298,25 +314,28 @@ impl Server {
         false
     }
 
-    #[cfg(fuzzing)]
-    pub fn send_to_self(&mut self, data: &[u8]) {
-        self.response_counter.store(0, Ordering::SeqCst);;
-        self.num_bad_requests = 0;
-        let res = self
-            .fake_client_socket
-            .send_to(data, &self.socket.local_addr().unwrap());
-        info!("Sent to self: {:?}", res);
-    }
-
+    /// Returns a reference to the server's long-term public key
     pub fn get_public_key(&self) -> &str {
         return &self.public_key;
     }
 
+    /// Returns a reference to the server's on-line (delegated) key
     pub fn get_online_key(&self) -> &OnlineKey {
         return &self.online_key;
     }
 
+    /// Returns a reference to the `ServerConfig` this server was configured with
     pub fn get_config(&self) -> &Box<ServerConfig> {
         return &self.config;
     }
+
+    #[cfg(fuzzing)]
+    pub fn send_to_self(&mut self, data: &[u8]) {
+        self.response_counter.store(0, Ordering::SeqCst);;
+        self.num_bad_requests = 0;
+        let res = self
+            .fake_client_socket
+            .send_to(data, &self.socket.local_addr().unwrap());
+        info!("Sent to self: {:?}", res);
+    }
 }