docs(rust): doc comment update for ockam_channel

Author: Jared Stanbrough

implementations/rust/ockam/ockam_channel/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this crate will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## v0.1.0 - DATE
+## v0.1.0 - 2021-04-05
 
-Initial release.
+- Initial release.
 

implementations/rust/ockam/ockam_channel/Cargo.toml

@@ -18,14 +18,14 @@ default = ["std"]
 std = []
 
 [dependencies]
-ockam_node = {path = "../ockam_node", version = "*"}
-ockam_core = {path = "../ockam_core", version = "*"}
+ockam_core = {path = "../ockam_core", version = "0"}
+ockam_key_exchange_xx = {path = "../ockam_key_exchange_xx", version = "0"}
+ockam_key_exchange_core = {path = "../ockam_key_exchange_core", version = "0"}
+ockam_node = {path = "../ockam_node", version = "0"}
+ockam_vault_core = { path = "../ockam_vault_core", version = "0" }
+ockam_vault = { path = "../ockam_vault", version = "0" }
 serde_bare = "0.3.0"
 rand = "0.8"
-ockam_key_exchange_xx = {path = "../ockam_key_exchange_xx", version = "*"}
-ockam_key_exchange_core = {path = "../ockam_key_exchange_core", version = "*"}
-ockam_vault_core = { path = "../ockam_vault_core", version = "*" }
-ockam_vault = { path = "../ockam_vault", version = "*" }
 async-trait = "0.1.42"
 serde = {version = "1.0.120", features = ["derive"]}
 tracing = "0.1"

implementations/rust/ockam/ockam_channel/src/error.rs

@@ -1,11 +1,18 @@
 use ockam_core::Error;
 
+/// Types of errors that may occur constructing a secure channel.
 pub enum SecureChannelError {
+    /// No error.
     None,
+    /// The key exchange process failed.
     KeyExchange,
+    /// Internal state is invalid.
     InvalidInternalState,
+    /// Expected nonce was invalid.
     InvalidNonce,
+    /// Key exchange process did not complete.
     KeyExchangeNotComplete,
+    /// Invalid response received from the Hub.
     InvalidHubResponse,
 }
 

implementations/rust/ockam/ockam_channel/src/lib.rs

@@ -1,3 +1,19 @@
+//! Secure channel types and traits of the Ockam library.
+//!
+//! This crate contains the secure channel types of the Ockam library and is intended
+//! for use by other crates that provide features and add-ons to the main
+//! Ockam library.
+//!
+//! The main Ockam crate re-exports types defined in this crate.
+#![deny(
+    missing_docs,
+    trivial_casts,
+    trivial_numeric_casts,
+    unsafe_code,
+    unused_import_braces,
+    unused_qualifications,
+    warnings
+)]
 mod error;
 mod key_exchange;
 mod secure_channel;

implementations/rust/ockam/ockam_channel/src/secure_channel.rs

@@ -30,9 +30,11 @@ pub struct SecureChannelInfo {
 }
 
 impl SecureChannelInfo {
+    /// Return the address of the worker.
     pub fn worker_address(&self) -> &Address {
         &self.worker_address
     }
+    /// Return the auth hash.
     pub fn auth_hash(&self) -> [u8; 32] {
         self.auth_hash
     }
@@ -195,11 +197,24 @@ impl SecureChannel {
     }
 }
 
+/// A message in the secure channel protocol.
 #[derive(Serialize, Deserialize, Clone, PartialEq, Debug)]
 pub enum SecureChannelMessage {
-    KeyExchange { payload: Vec<u8> },
-    Encrypt { m: Vec<u8> },
-    Decrypt { payload: Vec<u8> },
+    /// Key exchange requested.
+    KeyExchange {
+        /// Information for key exchange.
+        payload: Vec<u8>,
+    },
+    /// Encrypted data.
+    Encrypt {
+        /// Encrypted data.
+        m: Vec<u8>,
+    },
+    /// Decrypted data.
+    Decrypt {
+        /// Decrypted payload.
+        payload: Vec<u8>,
+    },
 }
 
 impl SecureChannelMessage {

implementations/rust/ockam/ockam_channel/src/secure_channel_listener.rs

@@ -9,15 +9,20 @@ use serde::{Deserialize, Serialize};
 pub struct SecureChannelListener;
 
 impl SecureChannelListener {
+    /// Create a new SecureChannelListener.
     pub fn new() -> Self {
         Self {}
     }
 }
 
+/// SecureChannelListener message wrapper.
 #[derive(Serialize, Deserialize, Clone, PartialEq, Debug)]
 pub enum SecureChannelListenerMessage {
+    /// Create a new responder channel.
     CreateResponderChannel {
+        /// Channel ID.
         channel_id: String,
+        /// Channel information.
         payload: Vec<u8>,
     },
 }

implementations/rust/ockam/ockam_key_exchange_core/CHANGELOG.md

@@ -5,6 +5,6 @@ All notable changes to this crate will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## v0.1.0 - [RELEASE_DATE]
+## v0.1.0 - 2021-04-05
 
-Initial release.
+- Initial release.

implementations/rust/ockam/ockam_key_exchange_core/Cargo.toml

@@ -14,5 +14,5 @@ description = """The Ockam Key Exchange trait.
 
 [dependencies]
 ockam_core = { version = "0.6.0", path = "../ockam_core" }
-ockam_vault_core = { version = "0.3.0", path = "../ockam_vault_core" }
+ockam_vault_core = { version = "0.3.1", path = "../ockam_vault_core" }
 zeroize = { version = "1.1", features = ["zeroize_derive"] }

implementations/rust/ockam/ockam_key_exchange_core/src/lib.rs

@@ -1,5 +1,12 @@
+//! Key exchange types and traits of the Ockam library.
+//!
+//! This crate contains the key exchange types of the Ockam library and is intended
+//! for use by other crates that provide features and add-ons to the main
+//! Ockam library.
+//!
+//! The main Ockam crate re-exports types defined in this crate.
 #![deny(
-    // missing_docs,
+    missing_docs,
     trivial_casts,
     trivial_numeric_casts,
     unsafe_code,
@@ -11,25 +18,26 @@
 use ockam_vault_core::{PublicKey, Secret};
 use zeroize::Zeroize;
 
-/// Represents either the Initiator or the Responder
+/// A trait implemented by both Initiator and Responder peers.
 pub trait KeyExchanger {
-    /// Handle the current step in the key exchange process
+    /// Run the current phase of the key exchange process.
     fn process(&mut self, data: &[u8]) -> ockam_core::Result<Vec<u8>>;
-    /// Is the key exchange process completed yet
+    /// Returns true if the key exchange process is complete.
     fn is_complete(&self) -> bool;
-    /// If completed, then return the data and keys needed for channels
+
+    /// Return the data and keys needed for channels. Key exchange must be completed prior to calling this function.
     fn finalize(self) -> ockam_core::Result<CompletedKeyExchange>;
 }
 
-/// Instantiate a stateful key exchange vault instance
-pub trait NewKeyExchanger<E: KeyExchanger = Self, F: KeyExchanger = Self> {
+/// A creator of both initiator and responder peers of a key exchange.
+pub trait NewKeyExchanger<I: KeyExchanger = Self, R: KeyExchanger = Self> {
     /// Create a new Key Exchanger with the initiator role
-    fn initiator(&self) -> E;
+    fn initiator(&self) -> I;
     /// Create a new Key Exchanger with the responder role
-    fn responder(&self) -> F;
+    fn responder(&self) -> R;
 }
 
-/// A Completed Key Exchange elements
+/// The state of a completed key exchange.
 #[derive(Debug, Zeroize)]
 pub struct CompletedKeyExchange {
     h: [u8; 32],
@@ -40,29 +48,30 @@ pub struct CompletedKeyExchange {
 }
 
 impl CompletedKeyExchange {
-    /// The state hash
+    /// The state hash.
     pub fn h(&self) -> &[u8; 32] {
         &self.h
     }
-    /// The derived encryption key handle
+    /// The derived encryption key.
     pub fn encrypt_key(&self) -> &Secret {
         &self.encrypt_key
     }
-    /// The derived decryption key handle
+    /// The derived decryption key.
     pub fn decrypt_key(&self) -> &Secret {
         &self.decrypt_key
     }
-    /// The long term static key handle
+    /// The long term static key.
     pub fn local_static_secret(&self) -> &Secret {
         &self.local_static_secret
     }
-    /// The long term static public key from remote party
+    /// Remote peer well known public key.
     pub fn remote_static_public_key(&self) -> &PublicKey {
         &self.remote_static_public_key
     }
 }
 
 impl CompletedKeyExchange {
+    /// Build a CompletedKeyExchange comprised of the input parameters.
     pub fn new(
         h: [u8; 32],
         encrypt_key: Secret,

implementations/rust/ockam/ockam_key_exchange_xx/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this crate will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## v0.1.0 - [RELEASE_DATE]
+## v0.1.0 - 2012-04-05
 
-Initial release.
+- Initial release.