missing_docs for factory

Author: ounsworth

crypto/factory/src/hash_factory.rs

@@ -35,16 +35,24 @@ use bouncycastle_sha2::{SHA224_NAME, SHA256_NAME, SHA384_NAME, SHA512_NAME};
 use bouncycastle_sha3 as sha3;
 use bouncycastle_sha3::{SHA3_224_NAME, SHA3_256_NAME, SHA3_384_NAME, SHA3_512_NAME};
 
-/// All members must impl Hash.
+/// Wrapper object for all algorithms that impl [Hash].
 /// Note: no SHAKE because SHAKE is not NIST approved as a hash function. See FIPS 202 section A.2.
 pub enum HashFactory {
+    ///
     SHA224(sha2::SHA224),
+    ///
     SHA256(sha2::SHA256),
+    ///
     SHA384(sha2::SHA384),
+    ///
     SHA512(sha2::SHA512),
+    ///
     SHA3_224(sha3::SHA3_224),
+    ///
     SHA3_256(sha3::SHA3_256),
+    ///
     SHA3_384(sha3::SHA3_384),
+    ///
     SHA3_512(sha3::SHA3_512),
 }
 

crypto/factory/src/kdf_factory.rs

@@ -58,17 +58,25 @@ use bouncycastle_sha3::{
     SHA3_224_NAME, SHA3_256_NAME, SHA3_384_NAME, SHA3_512_NAME, SHAKE128_NAME, SHAKE256_NAME,
 };
 
-// All members must impl KDF.
+/// Wrapper object for all algorithms that impl [KDF].
 pub enum KDFFactory {
+    ///
     #[allow(non_camel_case_types)]
     HKDF_SHA256(hkdf::HKDF_SHA256),
+    ///
     #[allow(non_camel_case_types)]
     HKDF_SHA512(hkdf::HKDF_SHA512),
+    ///
     SHA3_224(sha3::SHA3_224),
+    ///
     SHA3_256(sha3::SHA3_256),
+    ///
     SHA3_384(sha3::SHA3_384),
+    ///
     SHA3_512(sha3::SHA3_512),
+    ///
     SHAKE128(sha3::SHAKE128),
+    ///
     SHAKE256(sha3::SHAKE256),
 }
 

crypto/factory/src/lib.rs

@@ -24,6 +24,11 @@
 //! get the either the default algorithm or the default algorithm at the 128-bit or 256-bit security level.
 //! It also exposes [AlgorithmFactory::new] which can be used to create an instance of the algorithm
 //! by string name according to the string constants associated with the respective factory type.
+//! 
+//! This crate compiles with STD; ie it is explicitly not tagged as `no_std` and it makes use of `Vec` and other
+//! dynamically-sized nice things.
+
+#![forbid(missing_docs)]
 
 use bouncycastle_core::errors::MACError;
 
@@ -34,13 +39,19 @@ pub mod rng_factory;
 pub mod xof_factory;
 
 /*** String constants ***/
+///
 pub const DEFAULT: &str = "Default";
+///
 pub const DEFAULT_128_BIT: &str = "Default128Bit";
+///
 pub const DEFAULT_256_BIT: &str = "Default256Bit";
 
+/// Top-level error type for Factories.
 #[derive(Debug)]
 pub enum FactoryError {
+    ///
     MACError(MACError),
+    ///
     UnsupportedAlgorithm(String),
 }
 
@@ -50,17 +61,14 @@ impl From<MACError> for FactoryError {
     }
 }
 
+///
 pub trait AlgorithmFactory: Sized + Default {
-    // Get the default configured algorithm.
-    // Not implemented because all factories MUST impl Default.
-    // fn default() -> Self;
-
     /// Get the default configured algorithm at the 128-bit security level.
     fn default_128_bit() -> Self;
 
     /// Get the default configured algorithm at the 256-bit security level.
     fn default_256_bit() -> Self;
 
-    /// Create an instance of the algorithm by name.
+    /// Get an instance of the algorithm by name.
     fn new(alg_name: &str) -> Result<Self, FactoryError>;
 }

crypto/factory/src/mac_factory.rs

@@ -83,39 +83,51 @@ use bouncycastle_sha2 as sha2;
 use bouncycastle_sha3 as sha3;
 
 /*** Defaults ***/
+///
 pub const DEFAULT_MAC_NAME: &str = HMAC_SHA256_NAME;
+///
 pub const DEFAULT_128BIT_MAC_NAME: &str = HMAC_SHA256_NAME;
+///
 pub const DEFAULT_256BIT_MAC_NAME: &str = HMAC_SHA256_NAME;
 
 #[allow(non_camel_case_types)]
 
+/// Wrapper object for all algorithms that impl [MAC].
 /// MACFactory deviates from the usual AlgorithmFactory trait because MAC objects do not have a no-arg constructor;
 /// instead they have a constructor that takes a [KeyMaterialTrait] and can return an error.
 pub enum MACFactory {
-    // All members must impl MAC.
+    ///
     HMAC_SHA224(hmac::HMAC<sha2::SHA224>),
+    ///
     HMAC_SHA256(hmac::HMAC<sha2::SHA256>),
+    ///
     HMAC_SHA384(hmac::HMAC<sha2::SHA384>),
+    ///
     HMAC_SHA512(hmac::HMAC<sha2::SHA512>),
+    ///
     HMAC_SHA3_224(hmac::HMAC<sha3::SHA3_224>),
+    ///
     HMAC_SHA3_256(hmac::HMAC<sha3::SHA3_256>),
+    ///
     HMAC_SHA3_384(hmac::HMAC<sha3::SHA3_384>),
+    ///
     HMAC_SHA3_512(hmac::HMAC<sha3::SHA3_512>),
 }
 
 impl MACFactory {
+    /// Get the default MAC algorithm.
     pub fn default(key: &impl KeyMaterialTrait) -> Result<Self, FactoryError> {
         Self::new(DEFAULT_MAC_NAME, key)
     }
-
+    /// Get the default 128-bit MAC algorithm.
     pub fn default_128_bit(key: &impl KeyMaterialTrait) -> Result<Self, FactoryError> {
         Self::new(DEFAULT_128BIT_MAC_NAME, key)
     }
-
+    /// Get the default 256-bit MAC algorithm.
     pub fn default_256_bit(key: &impl KeyMaterialTrait) -> Result<Self, FactoryError> {
         Self::new(DEFAULT_256BIT_MAC_NAME, key)
     }
-
+    /// Get an instance of the algorithm by name.
     pub fn new(alg_name: &str, key: &impl KeyMaterialTrait) -> Result<Self, FactoryError> {
         match alg_name {
             DEFAULT => Self::default(key),

crypto/factory/src/rng_factory.rs

@@ -50,10 +50,12 @@ use bouncycastle_core::traits::{RNG, SecurityStrength};
 use bouncycastle_rng as rng;
 use bouncycastle_rng::{HASH_DRBG_SHA256_NAME, HASH_DRBG_SHA512_NAME};
 
-/// All members must impl RNG.
+/// Wrapper object for all algorithms that impl [RNG].
 pub enum RNGFactory {
+    ///
     #[allow(non_camel_case_types)]
     HashDRBG_SHA256(rng::HashDRBG_SHA256),
+    ///
     #[allow(non_camel_case_types)]
     HashDRBG_SHA512(rng::HashDRBG_SHA512),
 }

crypto/factory/src/xof_factory.rs

@@ -41,13 +41,18 @@ use bouncycastle_sha3 as sha3;
 use bouncycastle_sha3::{SHAKE128_NAME, SHAKE256_NAME};
 
 /*** Defaults ***/
+///
 pub const DEFAULT_XOF_NAME: &str = SHAKE128_NAME;
+///
 pub const DEFAULT_128BIT_XOF_NAME: &str = SHAKE128_NAME;
+///
 pub const DEFAULT_256BIT_XOF_NAME: &str = SHAKE256_NAME;
 
-// All members must impl XOF.
+/// Wrapper object for all algorithms that impl [XOF].
 pub enum XOFFactory {
+    ///
     SHAKE128(sha3::SHAKE128),
+    ///
     SHAKE256(sha3::SHAKE256),
 }