Update docs.

src/crypto_box.rs

@@ -4,31 +4,22 @@
 //!
 //! For details, refer to [libsodium docs](https://libsodium.gitbook.io/doc/public-key_cryptography/authenticated_encryption).
 //!
-//! # Rustaceous API
+//! # Classic API example
 //!
 //! ```
-//! use dryoc::rng::randombytes_buf;
-//! use dryoc::crypto_box::{crypto_box_keypair, crypto_box_easy, crypto_box_open_easy};
-//! use dryoc::traits::Gen;
-//! use dryoc::nonce::Nonce;
-//! ```
-//!
-//! # Classic API
-//!
-//! ```
-//! use dryoc::rng::randombytes_buf;
 //! use dryoc::prelude::*;
-//! use dryoc::constants::CRYPTO_BOX_NONCEBYTES;
+//! use dryoc::rng::copy_randombytes; // Not included in prelude
+//! use dryoc::constants::CRYPTO_BOX_NONCEBYTES; // Not included in prelude
 //!
-//! // Create a sender keypair
+//! // Create a random sender keypair
 //! let keypair_sender = crypto_box_keypair();
 //!
-//! // Recipient keypair
+//! // Create a random recipient keypair
 //! let keypair_recipient = crypto_box_keypair();
 //!
 //! // Generate a random nonce
-//! let nonce = randombytes_buf(CRYPTO_BOX_NONCEBYTES);
-//! let nonce = Nonce::gen();
+//! let mut nonce: [u8; CRYPTO_BOX_NONCEBYTES] = [0u8; CRYPTO_BOX_NONCEBYTES];
+//! copy_randombytes(&mut nonce);
 //!
 //! let message = "hello".as_bytes();
 //! // Encrypt message
@@ -57,7 +48,6 @@ use crate::crypto_box_impl::*;
 use crate::crypto_secretbox::*;
 use crate::crypto_secretbox_impl::*;
 use crate::dryocbox::DryocBox;
-use crate::dryocsecretbox::DryocSecretBox;
 use crate::error::Error;
 use crate::keypair::*;
 use crate::nonce::*;
@@ -85,7 +75,7 @@ pub fn crypto_box_beforenm(
     crypto_box_curve25519xsalsa20poly1305_beforenm(public_key, secret_key)
 }
 
-/// Precalculation variant of [crypto_box_easy]
+/// Precalculation variant of [`crate::crypto_box::crypto_box_easy`]
 pub fn crypto_box_detached_afternm(
     message: &InputBase,
     nonce: &Nonce,
@@ -94,7 +84,7 @@ pub fn crypto_box_detached_afternm(
     Ok(crypto_secretbox_detached(message, nonce, key).into())
 }
 
-/// In-place variant of [crypto_box_detached_afternm]
+/// In-place variant of [`crypto_box_detached_afternm`]
 pub fn crypto_box_detached_afternm_inplace(
     dryocbox: &mut DryocBox,
     nonce: &Nonce,
@@ -103,7 +93,7 @@ pub fn crypto_box_detached_afternm_inplace(
     crypto_secretbox_detached_inplace(&mut dryocbox.mac, &mut dryocbox.data, nonce, key);
 }
 
-/// Detached variant of [crypto_box_easy]
+/// Detached variant of [`crypto_box_easy`]
 pub fn crypto_box_detached(
     message: &InputBase,
     nonce: &Nonce,
@@ -223,7 +213,7 @@ pub fn crypto_box_open_detached_afternm_inplace(
     Ok(dryocbox.data)
 }
 
-/// Detached variant of [crypto_box_easy_open]
+/// Detached variant of [`crate::crypto_box::crypto_box_open_easy`]
 pub fn crypto_box_open_detached(
     mac: &MacBase,
     ciphertext: &InputBase,
@@ -240,7 +230,7 @@ pub fn crypto_box_open_detached(
     Ok(res)
 }
 
-/// In-place variant of [crypto_box_open_detached]
+/// In-place variant of ['crypto_box_open_detached']
 pub fn crypto_box_open_detached_inplace(
     ciphertext: Vec<u8>,
     nonce: &Nonce,

src/crypto_hash.rs

@@ -1,11 +1,13 @@
 use sha2::{Digest, Sha512};
 
+/// Computes a SHA512 hash from `input'
 pub fn crypto_hash_sha512(input: &[u8]) -> Vec<u8> {
     let mut state = crypto_hash_sha512_init();
     state.update(input);
     state.finalize()
 }
 
+/// SHA512 wrapper
 pub struct HashSha512 {
     hasher: Sha512,
 }
@@ -28,18 +30,22 @@ impl HashSha512 {
     }
 }
 
+/// Initializes SHA512 hasher
 pub fn crypto_hash_sha512_init() -> HashSha512 {
     HashSha512::new()
 }
 
+/// Updates `state` of SHA512 hasher with `input`
 pub fn crypto_hash_sha512_update(state: &mut HashSha512, input: &[u8]) {
     state.update(input);
 }
 
+/// Finalizes `state` of SHA512 and return hash result
 pub fn crypto_hash_sha512_final(state: HashSha512) -> Vec<u8> {
     state.finalize()
 }
 
+#[cfg(test)]
 mod tests {
     use super::*;
 

src/crypto_secretbox.rs

@@ -4,7 +4,7 @@
 //!
 //! For details, refer to [libsodium docs](https://libsodium.gitbook.io/doc/secret-key_cryptography/secretbox).
 //!
-//! # Basic usage
+//! # Classic API example
 //!
 //! ```
 //! use dryoc::rng::randombytes_buf;

src/dryocbox.rs

@@ -1,4 +1,31 @@
 //! # Public-key authenticated encryption
+//!
+//! _For secret-key based encryption, see [crate::dryocsecretbox]_.
+//!
+//! # Rustaceous API example
+//!
+//! ```
+//! use dryoc::prelude::*;
+//!
+//! let sender_keypair = KeyPair::gen();
+//! let recipient_keypair = KeyPair::gen();
+//! let nonce = Nonce::gen();
+//! let message = "hey";
+//!
+//! let dryocbox = DryocBox::encrypt(
+//!     &message.into(),
+//!     &nonce,
+//!     &recipient_keypair.clone().into(),
+//!     &sender_keypair.clone().into(),
+//! )
+//! .expect("unable to encrypt");
+//!
+//! let decrypted = dryocbox
+//!     .decrypt(&nonce, &sender_keypair.into(), &recipient_keypair.into())
+//!     .expect("unable to decrypt");
+//!
+//! assert_eq!(message.as_bytes(), decrypted.as_slice());
+//! ```
 
 use crate::constants::CRYPTO_BOX_MACBYTES;
 use crate::dryocsecretbox::DryocSecretBox;
@@ -131,6 +158,7 @@ impl From<DryocSecretBox> for DryocBox {
     }
 }
 
+#[cfg(test)]
 mod tests {
     use super::*;
 

src/dryocsecretbox.rs

@@ -1,7 +1,26 @@
 //! # Secret-key authenticated encryption
+//!
+//! _For public-key based encryption, see [crate::dryocbox]_.
+//!
+//! # Rustaceous API example
+//!
+//! ```
+//! use dryoc::prelude::*;
+//!
+//! let secret_key = SecretBoxKey::gen();
+//! let nonce = Nonce::gen();
+//! let message = "hey";
+//!
+//! let dryocsecretbox = DryocSecretBox::encrypt(&message.into(), &nonce, &secret_key);
+//!
+//! let decrypted = dryocsecretbox
+//!     .decrypt(&nonce, &secret_key)
+//!     .expect("unable to decrypt");
+//!
+//! assert_eq!(message.as_bytes(), decrypted.as_slice());
+//! ```
 
 use crate::constants::CRYPTO_SECRETBOX_MACBYTES;
-use crate::dryocbox::DryocBox;
 use crate::error::Error;
 use crate::message::Message;
 use crate::nonce::Nonce;
@@ -100,6 +119,7 @@ impl Default for DryocSecretBox {
     }
 }
 
+#[cfg(test)]
 mod tests {
     use super::*;
 

src/keypair.rs

@@ -13,6 +13,7 @@ use zeroize::Zeroize;
 )]
 #[cfg_attr(not(feature = "serde"), derive(Zeroize, Debug, Clone, PartialEq))]
 #[zeroize(drop)]
+/// Wrapper for [`crate::dryocbox::DryocBox`] secret keys
 pub struct SecretKey(pub SecretKeyBase);
 
 #[cfg_attr(
@@ -21,6 +22,7 @@ pub struct SecretKey(pub SecretKeyBase);
 )]
 #[cfg_attr(not(feature = "serde"), derive(Zeroize, Debug, Clone, PartialEq))]
 #[zeroize(drop)]
+/// Wrapper for [`crate::dryocbox::DryocBox`] public keys
 pub struct PublicKey(pub PublicKeyBase);
 
 #[cfg_attr(
@@ -29,7 +31,7 @@ pub struct PublicKey(pub PublicKeyBase);
 )]
 #[cfg_attr(not(feature = "serde"), derive(Zeroize, Debug, Clone, PartialEq))]
 #[zeroize(drop)]
-/// Public/private keypair for use with [DryocBox], aka libsodium box
+/// Public/private keypair for use with [`crate::dryocbox::DryocBox`], aka libsodium box
 pub struct KeyPair {
     /// Public key
     pub public_key: PublicKey,
@@ -38,6 +40,7 @@ pub struct KeyPair {
 }
 
 impl PublicKey {
+    /// Returns an empty public key
     pub fn new() -> Self {
         Self([0u8; CRYPTO_BOX_SECRETKEYBYTES])
     }
@@ -50,6 +53,7 @@ impl From<[u8; CRYPTO_BOX_SECRETKEYBYTES]> for PublicKey {
 }
 
 impl SecretKey {
+    /// Returns an empty secret key
     pub fn new() -> Self {
         Self([0u8; CRYPTO_BOX_SECRETKEYBYTES])
     }
@@ -139,6 +143,7 @@ impl From<KeyPair> for PublicKey {
     }
 }
 
+#[cfg(test)]
 mod tests {
     use super::*;
 

src/lib.rs

@@ -5,11 +5,15 @@
 //! limited dependencies.
 //!
 //! This library includes both a _classic_ API, which is very similar to the
-//! original libsodium API, and Rustaceous API with Rust-specific features. Both
-//! APIs can be used together interchangeably, according to your preferences. The
-//! Rustaceous API is a wrapper around the underlying classic API.
+//! original libsodium API, and _Rustaceous_ API with Rust-specific features.
+//! Both APIs can be used together interchangeably, according to your
+//! preferences. The Rustaceous API is a wrapper around the underlying classic
+//! API.
 //!
-//! To get started with the Rustaceous API, refer to [dryocbox].
+//! It's recommended that you use the Rustaceous API unless you have strong
+//! feelings about using the Classic API.
+//!
+//! To get started with the Rustaceous API, refer to [dryocbox] and [dryocsecretbox].
 //!
 //! To get started, with the classic (libsodium) API, refer to [crypto_box] and
 //! [crypto_secretbox].
@@ -36,6 +40,7 @@ mod hsalsa20;
 mod scalarmult_curve25519;
 mod types;
 
+/// Ciphertext wrapper
 pub mod ciphertext;
 /// Constant value definitions
 pub mod constants;
@@ -49,12 +54,16 @@ pub mod dryocbox;
 pub mod dryocsecretbox;
 /// Public-key tools
 pub mod keypair;
+/// Message wrapper
 pub mod message;
+/// Nonce wrapper
 pub mod nonce;
 pub mod prelude;
 /// Random number generation utilities
 pub mod rng;
+/// Secret-key box key wrapper
 pub mod secretboxkey;
+/// Public traits
 pub mod traits;
 
 #[cfg(test)]

src/prelude.rs

@@ -13,6 +13,8 @@
 pub use crate::crypto_box::*;
 pub use crate::crypto_secretbox::*;
 pub use crate::dryocbox::*;
+pub use crate::dryocsecretbox::*;
 pub use crate::keypair::*;
 pub use crate::nonce::*;
+pub use crate::secretboxkey::*;
 pub use crate::traits::*;

src/secretboxkey.rs

@@ -14,9 +14,11 @@ use zeroize::Zeroize;
 )]
 #[cfg_attr(not(feature = "serde"), derive(Zeroize, Debug, Clone, PartialEq))]
 #[zeroize(drop)]
+/// A wrapper for [`crate::dryocsecretbox::DryocSecretBox`] secret keys
 pub struct SecretBoxKey(pub SecretBoxKeyBase);
 
 impl SecretBoxKey {
+    /// Returns an empty initialized secret key
     pub fn new() -> Self {
         Self([0u8; CRYPTO_SECRETBOX_KEYBYTES])
     }

src/traits.rs

@@ -1,3 +1,5 @@
+/// Trait for generating random values
 pub trait Gen {
+    /// This function should return a new instance of `Self` with random values
     fn gen() -> Self;
 }

tests/integration_tests.rs

@@ -21,3 +21,20 @@ fn test_dryocbox() {
 
     assert_eq!(message.as_bytes(), decrypted.as_slice());
 }
+
+#[test]
+fn test_dryocsecretbox() {
+    use dryoc::prelude::*;
+
+    let secret_key = SecretBoxKey::gen();
+    let nonce = Nonce::gen();
+    let message = "hey";
+
+    let dryocsecretbox = DryocSecretBox::encrypt(&message.into(), &nonce, &secret_key);
+
+    let decrypted = dryocsecretbox
+        .decrypt(&nonce, &secret_key)
+        .expect("unable to decrypt");
+
+    assert_eq!(message.as_bytes(), decrypted.as_slice());
+}