vendor/digest-0.8.1/src/lib.rs

   1 //! This crate provides traits which describe functionality of cryptographic hash
   2 //! functions.
   3 //!
   4 //! Traits in this repository can be separated into two levels:
   5 //! - Low level traits: `Input`, `BlockInput`, `Reset`, `FixedOutput`,
   6 //! `VariableOutput`, `ExtendableOutput`. These traits atomically describe
   7 //! available functionality of hash function implementations.
   8 //! - Convenience trait: `Digest`, `DynDigest`. They are wrappers around
   9 //! low level traits for most common hash-function use-cases.
  10 //!
  11 //! Additionally hash functions implement traits from `std`: `Default`, `Clone`,
  12 //! `Write`. (the latter depends on enabled-by-default `std` crate feature)
  13 //!
  14 //! The `Digest` trait is the most commonly used trait.
  15 #![no_std]
  16 #![doc(html_logo_url =
  17     "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]
  18 pub extern crate generic_array;
  19 #[cfg(feature = "std")]
  20 #[macro_use] extern crate std;
  21 #[cfg(feature = "dev")]
  22 pub extern crate blobby;
  23 use generic_array::{GenericArray, ArrayLength};
  24 #[cfg(feature = "std")]
  25 use std::vec::Vec;
  26
  27 mod digest;
  28 mod dyn_digest;
  29 mod errors;
  30 #[cfg(feature = "dev")]
  31 pub mod dev;
  32
  33 pub use errors::InvalidOutputSize;
  34 pub use digest::Digest;
  35 #[cfg(feature = "std")]
  36 pub use dyn_digest::DynDigest;
  37
  38 /// Trait for processing input data
  39 pub trait Input {
  40     /// Digest input data.
  41     ///
  42     /// This method can be called repeatedly, e.g. for processing streaming
  43     /// messages.
  44     fn input<B: AsRef<[u8]>>(&mut self, data: B);
  45
  46     /// Digest input data in a chained manner.
  47     fn chain<B: AsRef<[u8]>>(mut self, data: B) -> Self where Self: Sized {
  48         self.input(data);
  49         self
  50     }
  51 }
  52
  53 /// Trait to indicate that digest function processes data in blocks of size
  54 /// `BlockSize`.
  55 ///
  56 /// The main usage of this trait is for implementing HMAC generically.
  57 pub trait BlockInput {
  58     type BlockSize: ArrayLength<u8>;
  59 }
  60
  61 /// Trait for returning digest result with the fixed size
  62 pub trait FixedOutput {
  63     type OutputSize: ArrayLength<u8>;
  64
  65     /// Retrieve result and consume hasher instance.
  66     fn fixed_result(self) -> GenericArray<u8, Self::OutputSize>;
  67 }
  68
  69 /// Trait for returning digest result with the variable size
  70 pub trait VariableOutput: core::marker::Sized {
  71     /// Create new hasher instance with the given output size.
  72     ///
  73     /// It will return `Err(InvalidOutputSize)` in case if hasher can not return
  74     /// specified output size. It will always return an error if output size
  75     /// equals to zero.
  76     fn new(output_size: usize) -> Result<Self, InvalidOutputSize>;
  77
  78     /// Get output size of the hasher instance provided to the `new` method
  79     fn output_size(&self) -> usize;
  80
  81     /// Retrieve result via closure and consume hasher.
  82     ///
  83     /// Closure is guaranteed to be called, length of the buffer passed to it
  84     /// will be equal to `output_size`.
  85     fn variable_result<F: FnOnce(&[u8])>(self, f: F);
  86
  87     /// Retrieve result into vector and consume hasher.
  88     #[cfg(feature = "std")]
  89     fn vec_result(self) -> Vec<u8> {
  90         let mut buf = Vec::with_capacity(self.output_size());
  91         self.variable_result(|res| buf.extend_from_slice(res));
  92         buf
  93     }
  94 }
  95
  96 /// Trait for describing readers which are used to extract extendable output
  97 /// from XOF (extendable-output function) result.
  98 pub trait XofReader {
  99     /// Read output into the `buffer`. Can be called unlimited number of times.
 100     fn read(&mut self, buffer: &mut [u8]);
 101 }
 102
 103 /// Trait which describes extendable-output functions (XOF).
 104 pub trait ExtendableOutput: core::marker::Sized {
 105     type Reader: XofReader;
 106
 107     /// Retrieve XOF reader and consume hasher instance.
 108     fn xof_result(self) -> Self::Reader;
 109
 110     /// Retrieve result into vector of specified length.
 111     #[cfg(feature = "std")]
 112     fn vec_result(self, n: usize) -> Vec<u8> {
 113         let mut buf = vec![0u8; n];
 114         self.xof_result().read(&mut buf);
 115         buf
 116     }
 117 }
 118
 119 /// Trait for resetting hash instances
 120 pub trait Reset {
 121     /// Reset hasher instance to its initial state and return current state.
 122     fn reset(&mut self);
 123 }
 124
 125 #[macro_export]
 126 /// Implements `std::io::Write` trait for implementer of `Input`
 127 macro_rules! impl_write {
 128     ($hasher:ident) => {
 129         #[cfg(feature = "std")]
 130         impl ::std::io::Write for $hasher {
 131             fn write(&mut self, buf: &[u8]) -> ::std::io::Result<usize> {
 132                 Input::input(self, buf);
 133                 Ok(buf.len())
 134             }
 135
 136             fn flush(&mut self) -> ::std::io::Result<()> {
 137                 Ok(())
 138             }
 139         }
 140     }
 141 }