feat: Massive refactor with a new API

The new API also makes it possible to wrap an existing hash into a Multihash. This
is useful if you e.g. want to create hashes for testing, without spending time with
actually hashing data.

You also interact with multicodecs less directly. This should make it easier to use
your own multihash implementations without forking the code base.

BREAKING CHANGE: There is a new API

When using multihashes, you now import implementations of that hash, which
has a `digest()` function. That function returns a Multihash.

New way:

    use multihash::Sha3_512;
    let my_multihash = Sha3_512::digest(b"hello world!");

Old way:

    use multihash::{encode, Hash};
    let my_multihash = encode(Hash::SHA3512, b"hello world!");

Author: vmx

Cargo.toml

@@ -13,10 +13,11 @@ edition = "2018"
 [dependencies]
 blake2b_simd = { version = "0.5.9", default-features = false }
 blake2s_simd = { version = "0.5.9", default-features = false }
-sha1 = "0.5"
-sha2 = { version = "0.7", default-features = false }
-tiny-keccak = "1.4"
+sha1 = "0.6"
+sha2 = { version = "0.8", default-features = false }
+tiny-keccak = { version = "2.0.0", features = ["keccak", "sha3"] }
 unsigned-varint = "0.3"
+digest = { version = "0.8", default-features = false }
 
 [dev-dependencies]
 quickcheck = "0.9.2"

src/digests.rs

@@ -1,143 +1,11 @@
 use std::convert::TryFrom;
 use std::{cmp, fmt, hash};
 
-use blake2b_simd::{blake2b, Params as Blake2bVariable};
-use blake2s_simd::{blake2s, Params as Blake2sVariable};
-use sha2::Digest;
-use tiny_keccak::Keccak;
-use unsigned_varint::{decode, encode};
-
-use crate::errors::{DecodeError, DecodeOwnedError, EncodeError};
-use crate::hashes::Hash;
-use crate::storage::Storage;
-
-// Helper macro for encoding input into output using sha1, sha2, tiny_keccak, or blake2
-macro_rules! encode {
-    (sha1, Sha1, $input:expr, $output:expr) => {{
-        let mut hasher = sha1::Sha1::new();
-        hasher.update($input);
-        $output.copy_from_slice(&hasher.digest().bytes());
-    }};
-    (sha2, $algorithm:ident, $input:expr, $output:expr) => {{
-        let mut hasher = sha2::$algorithm::default();
-        hasher.input($input);
-        $output.copy_from_slice(hasher.result().as_ref());
-    }};
-    (tiny, $constructor:ident, $input:expr, $output:expr) => {{
-        let mut kec = Keccak::$constructor();
-        kec.update($input);
-        kec.finalize($output);
-    }};
-    (blake2, $algorithm:ident, $input:expr, $output:expr) => {{
-        let hash = $algorithm($input);
-        $output.copy_from_slice(hash.as_ref());
-    }};
-    (blake2_256, $constructor:ident, $input:expr, $output:expr) => {{
-        let hash = $constructor::new()
-            .hash_length(32)
-            .to_state()
-            .update($input)
-            .finalize();
-        $output.copy_from_slice(hash.as_ref());
-    }};
-    (blake2_128, $constructor:ident, $input:expr, $output:expr) => {{
-        let hash = $constructor::new()
-            .hash_length(16)
-            .to_state()
-            .update($input)
-            .finalize();
-        $output.copy_from_slice(hash.as_ref());
-    }};
-}
-
-// And another one to keep the matching DRY
-macro_rules! match_encoder {
-    ($hash:ident for ($input:expr, $output:expr) {
-        $( $hashtype:ident => $lib:ident :: $method:ident, )*
-    }) => ({
-        match $hash {
-            $(
-                Hash::$hashtype => encode!($lib, $method, $input, $output),
-            )*
-
-            _ => return Err(EncodeError::UnsupportedType)
-        }
-    })
-}
-
-/// Encodes data into a multihash.
-///
-/// # Errors
-///
-/// Will return an error if the specified hash type is not supported. See the docs for `Hash`
-/// to see what is supported.
-///
-/// # Examples
-///
-/// ```
-/// use multihash::{encode, Hash};
-///
-/// assert_eq!(
-///     encode(Hash::SHA2256, b"hello world").unwrap().to_vec(),
-///     vec![18, 32, 185, 77, 39, 185, 147, 77, 62, 8, 165, 46, 82, 215, 218, 125, 171, 250, 196,
-///     132, 239, 227, 122, 83, 128, 238, 144, 136, 247, 172, 226, 239, 205, 233]
-/// );
-/// ```
-///
-pub fn encode(hash: Hash, input: &[u8]) -> Result<Multihash, EncodeError> {
-    // Custom length encoding for the identity multihash
-    if let Hash::Identity = hash {
-        if u64::from(std::u32::MAX) < as_u64(input.len()) {
-            return Err(EncodeError::UnsupportedInputLength);
-        }
-        let mut buf = encode::u16_buffer();
-        let code = encode::u16(hash.code(), &mut buf);
-        let mut len_buf = encode::u32_buffer();
-        let size = encode::u32(input.len() as u32, &mut len_buf);
-        Ok(Multihash {
-            storage: Storage::from_slices(&[&code, &size, &input]),
-        })
-    } else {
-        let (offset, mut output) = encode_hash(hash);
-        match_encoder!(hash for (input, &mut output[offset ..]) {
-            SHA1 => sha1::Sha1,
-            SHA2256 => sha2::Sha256,
-            SHA2512 => sha2::Sha512,
-            SHA3224 => tiny::new_sha3_224,
-            SHA3256 => tiny::new_sha3_256,
-            SHA3384 => tiny::new_sha3_384,
-            SHA3512 => tiny::new_sha3_512,
-            Keccak224 => tiny::new_keccak224,
-            Keccak256 => tiny::new_keccak256,
-            Keccak384 => tiny::new_keccak384,
-            Keccak512 => tiny::new_keccak512,
-            Blake2b512 => blake2::blake2b,
-            Blake2b256 => blake2_256::Blake2bVariable,
-            Blake2s256 => blake2::blake2s,
-            Blake2s128 => blake2_128::Blake2sVariable,
-        });
-
-        Ok(Multihash {
-            storage: Storage::from_slice(&output),
-        })
-    }
-}
+use unsigned_varint::{decode as varint_decode, encode as varint_encode};
 
-// Encode the given [`Hash`] value and ensure the returned [`Vec<u8>`]
-// has enough capacity to hold the actual digest.
-fn encode_hash(hash: Hash) -> (usize, Vec<u8>) {
-    let mut buf = encode::u16_buffer();
-    let code = encode::u16(hash.code(), &mut buf);
-
-    let len = code.len() + 1 + usize::from(hash.size());
-
-    let mut output = Vec::with_capacity(len);
-    output.extend_from_slice(code);
-    output.push(hash.size());
-    output.resize(len, 0);
-
-    (code.len() + 1, output)
-}
+use crate::errors::{DecodeError, DecodeOwnedError};
+use crate::hashes::Code;
+use crate::storage::Storage;
 
 /// Represents a valid multihash.
 #[derive(Clone)]
@@ -202,7 +70,7 @@ impl Multihash {
     }
 
     /// Returns which hashing algorithm is used in this multihash.
-    pub fn algorithm(&self) -> Hash {
+    pub fn algorithm(&self) -> Code {
         self.as_ref().algorithm()
     }
 
@@ -257,49 +125,31 @@ impl<'a> MultihashRef<'a> {
             return Err(DecodeError::BadInputLength);
         }
 
-        // Ensure `Hash::code` returns a `u16` so that our `decode::u16` here is correct.
-        std::convert::identity::<fn(Hash) -> u16>(Hash::code);
-        let (code, bytes) = decode::u16(&input).map_err(|_| DecodeError::BadInputLength)?;
-
-        let alg = Hash::from_code(code).ok_or(DecodeError::UnknownCode)?;
+        let (_code, bytes) = varint_decode::u64(&input).map_err(|_| DecodeError::BadInputLength)?;
 
-        // handle the identity case
-        if alg == Hash::Identity {
-            let (hash_len, bytes) = decode::u32(&bytes).map_err(|_| DecodeError::BadInputLength)?;
-            if as_u64(bytes.len()) != u64::from(hash_len) {
-                return Err(DecodeError::BadInputLength);
-            }
-            return Ok(MultihashRef { bytes: input });
-        }
-
-        let hash_len = usize::from(alg.size());
-
-        // Length of input after hash code should be exactly hash_len + 1
-        if bytes.len() != hash_len + 1 {
-            return Err(DecodeError::BadInputLength);
-        }
-
-        if usize::from(bytes[0]) != hash_len {
+        let (hash_len, bytes) =
+            varint_decode::u64(&bytes).map_err(|_| DecodeError::BadInputLength)?;
+        if (bytes.len() as u64) != hash_len {
             return Err(DecodeError::BadInputLength);
         }
 
         Ok(MultihashRef { bytes: input })
     }
 
     /// Returns which hashing algorithm is used in this multihash.
-    pub fn algorithm(&self) -> Hash {
-        let code = decode::u16(&self.bytes)
-            .expect("multihash is known to be valid algorithm")
-            .0;
-        Hash::from_code(code).expect("multihash is known to be valid")
+    pub fn algorithm(&self) -> Code {
+        let (code, _bytes) =
+            varint_decode::u64(&self.bytes).expect("multihash is known to be valid algorithm");
+        Code::from_u64(code)
     }
 
     /// Returns the hashed data.
     pub fn digest(&self) -> &'a [u8] {
-        let bytes = decode::u16(&self.bytes)
-            .expect("multihash is known to be valid digest")
-            .1;
-        &bytes[1..]
+        let (_code, bytes) =
+            varint_decode::u64(&self.bytes).expect("multihash is known to be valid digest");
+        let (_hash_len, bytes) =
+            varint_decode::u64(&bytes).expect("multihash is known to be a valid digest");
+        &bytes[..]
     }
 
     /// Builds a `Multihash` that owns the data.
@@ -323,7 +173,31 @@ impl<'a> PartialEq<Multihash> for MultihashRef<'a> {
     }
 }
 
-#[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
-fn as_u64(a: usize) -> u64 {
-    a as u64
+/// The `MultihashDigest` trait specifies an interface common for all multihash functions.
+pub trait MultihashDigest {
+    /// The Mutlihash byte value.
+    fn code(&self) -> Code;
+
+    /// Hash some input and return the digest.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the digest length is bigger than 2^32. This only happens for identity hasing.
+    fn digest(&self, data: &[u8]) -> Multihash;
+}
+
+/// Wraps a hash digest in Multihash with the given Mutlihash code.
+///
+/// The size of the hash is determoned by the size of the input hash. If it should be truncated
+/// the input data must already be the truncated hash.
+pub fn wrap(code: &Code, data: &[u8]) -> Multihash {
+    let mut code_buf = varint_encode::u64_buffer();
+    let code = varint_encode::u64(code.to_u64(), &mut code_buf);
+
+    let mut size_buf = varint_encode::u64_buffer();
+    let size = varint_encode::u64(data.len() as u64, &mut size_buf);
+
+    Multihash {
+        storage: Storage::from_slices(&[code, &size, &data]),
+    }
 }