Rename *result* methods to finalize (ala IUF)

As discussed in #43, this adopts `finalize` naming, following the
"Initialize-Update-Finalize" (IUF) interface naming scheme pervasive
throughout cryptography and cryptographic API design.

Author: tarcieri

crypto-mac/src/dev.rs

@@ -14,7 +14,7 @@ macro_rules! new_test {
             fn run_test(key: &[u8], input: &[u8], tag: &[u8]) -> Option<&'static str> {
                 let mut mac = <$mac as NewMac>::new_varkey(key).unwrap();
                 mac.update(input);
-                let result = mac.result_reset();
+                let result = mac.finalize_reset();
                 if &result.into_bytes()[..] != tag {
                     return Some("whole message");
                 }

crypto-mac/src/lib.rs

@@ -57,19 +57,20 @@ pub trait Mac: Clone {
 
     /// Obtain the result of a [`Mac`] computation as a [`Output`] and consume
     /// [`Mac`] instance.
-    fn result(self) -> Output<Self>;
+    fn finalize(self) -> Output<Self>;
 
     /// Obtain the result of a [`Mac`] computation as a [`Output`] and reset
     /// [`Mac`] instance.
-    fn result_reset(&mut self) -> Output<Self> {
-        let res = self.clone().result();
+    fn finalize_reset(&mut self) -> Output<Self> {
+        let res = self.clone().finalize();
         self.reset();
         res
     }
 
-    /// Check if code is correct for the processed input.
-    fn verify(self, code: &[u8]) -> Result<(), MacError> {
-        let choice = self.result().code.ct_eq(code);
+    /// Check if tag/code value is correct for the processed input.
+    fn verify(self, tag: &[u8]) -> Result<(), MacError> {
+        let choice = self.finalize().bytes.ct_eq(tag);
+
         if choice.unwrap_u8() == 1 {
             Ok(())
         } else {
@@ -82,28 +83,28 @@ pub trait Mac: Clone {
 /// implementation that runs in a fixed time.
 #[derive(Clone)]
 pub struct Output<M: Mac> {
-    code: GenericArray<u8, M::OutputSize>,
+    bytes: GenericArray<u8, M::OutputSize>,
 }
 
 impl<M: Mac> Output<M> {
     /// Create a new MAC [`Output`].
-    pub fn new(code: GenericArray<u8, M::OutputSize>) -> Output<M> {
-        Output { code }
+    pub fn new(bytes: GenericArray<u8, M::OutputSize>) -> Output<M> {
+        Output { bytes }
     }
 
-    /// Get the MAC code/tag value as a byte array.
+    /// Get the MAC tag/code value as a byte array.
     ///
-    /// Be very careful using this method, since incorrect use of the code value
+    /// Be very careful using this method, since incorrect use of the tag value
     /// may permit timing attacks which defeat the security provided by the
     /// [`Mac`] trait.
     pub fn into_bytes(self) -> GenericArray<u8, M::OutputSize> {
-        self.code
+        self.bytes
     }
 }
 
 impl<M: Mac> ConstantTimeEq for Output<M> {
     fn ct_eq(&self, other: &Self) -> Choice {
-        self.code.ct_eq(&other.code)
+        self.bytes.ct_eq(&other.bytes)
     }
 }
 

digest/README.md

@@ -50,8 +50,8 @@ let data = b"Hello world!";
 hasher.input(data);
 // `input` can be called repeatedly and is generic over `AsRef<[u8]>`
 hasher.input("String data");
-// Note that calling `result()` consumes hasher
-let hash = hasher.result();
+// Note that calling `finalize()` consumes hasher
+let hash = hasher.finalize();
 println!("Result: {:x}", hash);
 ```
 
@@ -65,7 +65,7 @@ example:
 let hash = Blake2b::new()
     .chain(b"Hello world!")
     .chain("String data")
-    .result();
+    .finalize();
 
 println!("Result: {:x}", hash);
 ```
@@ -89,7 +89,7 @@ use std::{fs, io};
 let mut file = fs::File::open(&path)?;
 let mut hasher = Blake2b::new();
 let n = io::copy(&mut file, &mut hasher)?;
-let hash = hasher.result();
+let hash = hasher.finalize();
 
 println!("Path: {}", path);
 println!("Bytes processed: {}", n);
@@ -111,7 +111,7 @@ fn hash_password<D: Digest>(password: &str, salt: &str, output: &mut [u8]) {
     hasher.input(password.as_bytes());
     hasher.input(b"$");
     hasher.input(salt.as_bytes());
-    output.copy_from_slice(hasher.result().as_slice())
+    output.copy_from_slice(hasher.finalize().as_slice())
 }
 
 use blake2::Blake2b;

digest/src/dev.rs

@@ -46,14 +46,14 @@ mod foo {
         // Test that it works when accepting the message all at once
         hasher.update(input);
         let mut hasher2 = hasher.clone();
-        if hasher.result().as_slice() != output {
+        if hasher.finalize().as_slice() != output {
             return Some("whole message");
         }
 
         // Test if reset works correctly
         hasher2.reset();
         hasher2.update(input);
-        if hasher2.result().as_slice() != output {
+        if hasher2.finalize().as_slice() != output {
             return Some("whole message after reset");
         }
 
@@ -66,7 +66,7 @@ mod foo {
             hasher.update(&input[len - left..take + len - left]);
             left -= take;
         }
-        if hasher.result().as_slice() != output {
+        if hasher.finalize().as_slice() != output {
             return Some("message in pieces");
         }
 
@@ -75,7 +75,7 @@ mod foo {
         for chunk in input.chunks(1) {
             hasher.update(chunk)
         }
-        if hasher.result().as_slice() != output {
+        if hasher.finalize().as_slice() != output {
             return Some("message byte-by-byte");
         }
         None
@@ -91,7 +91,7 @@ mod foo {
             sh.update(&[b'a'; 10]);
         }
         sh.update(&[b'a'; 500_000][..]);
-        let out = sh.result();
+        let out = sh.finalize();
         assert_eq!(out[..], expected[..]);
     }
 }
@@ -111,7 +111,7 @@ where
     let mut hasher2 = hasher.clone();
     {
         let out = &mut buf[..output.len()];
-        hasher.xof_result().read(out);
+        hasher.finalize_xof().read(out);
 
         if out != output {
             return Some("whole message");
@@ -124,7 +124,7 @@ where
 
     {
         let out = &mut buf[..output.len()];
-        hasher2.xof_result().read(out);
+        hasher2.finalize_xof().read(out);
 
         if out != output {
             return Some("whole message after reset");
@@ -143,7 +143,7 @@ where
 
     {
         let out = &mut buf[..output.len()];
-        hasher.xof_result().read(out);
+        hasher.finalize_xof().read(out);
         if out != output {
             return Some("message in pieces");
         }
@@ -153,7 +153,7 @@ where
     let mut hasher = D::default();
     hasher.update(input);
 
-    let mut reader = hasher.xof_result();
+    let mut reader = hasher.finalize_xof();
     let out = &mut buf[..output.len()];
     for chunk in out.chunks_mut(1) {
         reader.read(chunk);
@@ -176,15 +176,15 @@ where
     // Test that it works when accepting the message all at once
     hasher.update(input);
     let mut hasher2 = hasher.clone();
-    hasher.variable_result(|res| buf.copy_from_slice(res));
+    hasher.finalize_variable(|res| buf.copy_from_slice(res));
     if buf != output {
         return Some("whole message");
     }
 
     // Test if reset works correctly
     hasher2.reset();
     hasher2.update(input);
-    hasher2.variable_result(|res| buf.copy_from_slice(res));
+    hasher2.finalize_variable(|res| buf.copy_from_slice(res));
     if buf != output {
         return Some("whole message after reset");
     }
@@ -198,7 +198,7 @@ where
         hasher.update(&input[len - left..take + len - left]);
         left -= take;
     }
-    hasher.variable_result(|res| buf.copy_from_slice(res));
+    hasher.finalize_variable(|res| buf.copy_from_slice(res));
     if buf != output {
         return Some("message in pieces");
     }
@@ -208,7 +208,7 @@ where
     for chunk in input.chunks(1) {
         hasher.update(chunk)
     }
-    hasher.variable_result(|res| buf.copy_from_slice(res));
+    hasher.finalize_variable(|res| buf.copy_from_slice(res));
     if buf != output {
         return Some("message byte-by-byte");
     }

digest/src/digest.rs

@@ -24,13 +24,13 @@ pub trait Digest {
         Self: Sized;
 
     /// Retrieve result and consume hasher instance.
-    fn result(self) -> Output<Self>;
+    fn finalize(self) -> Output<Self>;
 
     /// Retrieve result and reset hasher instance.
     ///
     /// This method sometimes can be more efficient compared to hasher
     /// re-creation.
-    fn result_reset(&mut self) -> Output<Self>;
+    fn finalize_reset(&mut self) -> Output<Self>;
 
     /// Reset hasher instance to its initial state.
     fn reset(&mut self);
@@ -67,12 +67,12 @@ impl<D: Update + FixedOutput + Reset + Clone + Default> Digest for D {
         Update::chain(self, data)
     }
 
-    fn result(self) -> Output<Self> {
-        self.fixed_result()
+    fn finalize(self) -> Output<Self> {
+        self.finalize_fixed()
     }
 
-    fn result_reset(&mut self) -> Output<Self> {
-        let res = self.clone().fixed_result();
+    fn finalize_reset(&mut self) -> Output<Self> {
+        let res = self.clone().finalize_fixed();
         self.reset();
         res
     }
@@ -88,7 +88,7 @@ impl<D: Update + FixedOutput + Reset + Clone + Default> Digest for D {
     fn digest(data: &[u8]) -> Output<Self> {
         let mut hasher = Self::default();
         Update::update(&mut hasher, data);
-        hasher.fixed_result()
+        hasher.finalize_fixed()
     }
 }
 

digest/src/dyn_digest.rs

@@ -13,10 +13,10 @@ pub trait DynDigest {
     fn update(&mut self, data: &[u8]);
 
     /// Retrieve result and reset hasher instance
-    fn result_reset(&mut self) -> Box<[u8]>;
+    fn finalize_reset(&mut self) -> Box<[u8]>;
 
     /// Retrieve result and consume boxed hasher instance
-    fn result(self: Box<Self>) -> Box<[u8]>;
+    fn finalize(self: Box<Self>) -> Box<[u8]>;
 
     /// Reset hasher instance to its initial state.
     fn reset(&mut self);
@@ -33,14 +33,14 @@ impl<D: Update + FixedOutput + Reset + Clone + 'static> DynDigest for D {
         Update::update(self, data);
     }
 
-    fn result_reset(&mut self) -> Box<[u8]> {
-        let res = self.clone().fixed_result().to_vec().into_boxed_slice();
+    fn finalize_reset(&mut self) -> Box<[u8]> {
+        let res = self.clone().finalize_fixed().to_vec().into_boxed_slice();
         Reset::reset(self);
         res
     }
 
-    fn result(self: Box<Self>) -> Box<[u8]> {
-        self.fixed_result().to_vec().into_boxed_slice()
+    fn finalize(self: Box<Self>) -> Box<[u8]> {
+        self.finalize_fixed().to_vec().into_boxed_slice()
     }
 
     fn reset(&mut self) {

digest/src/lib.rs

@@ -77,7 +77,7 @@ pub trait FixedOutput {
     type OutputSize: ArrayLength<u8>;
 
     /// Retrieve result and consume hasher instance.
-    fn fixed_result(self) -> GenericArray<u8, Self::OutputSize>;
+    fn finalize_fixed(self) -> GenericArray<u8, Self::OutputSize>;
 }
 
 /// Trait for returning digest result with the variable size
@@ -96,14 +96,14 @@ pub trait VariableOutput: core::marker::Sized {
     ///
     /// Closure is guaranteed to be called, length of the buffer passed to it
     /// will be equal to `output_size`.
-    fn variable_result<F: FnOnce(&[u8])>(self, f: F);
+    fn finalize_variable<F: FnOnce(&[u8])>(self, f: F);
 
     /// Retrieve result into vector and consume hasher.
     #[cfg(feature = "std")]
     #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
-    fn vec_result(self) -> Vec<u8> {
+    fn finalize_vec(self) -> Vec<u8> {
         let mut buf = Vec::with_capacity(self.output_size());
-        self.variable_result(|res| buf.extend_from_slice(res));
+        self.finalize_variable(|res| buf.extend_from_slice(res));
         buf
     }
 }
@@ -121,14 +121,14 @@ pub trait ExtendableOutput: core::marker::Sized {
     type Reader: XofReader;
 
     /// Retrieve XOF reader and consume hasher instance.
-    fn xof_result(self) -> Self::Reader;
+    fn finalize_xof(self) -> Self::Reader;
 
     /// Retrieve result into vector of specified length.
     #[cfg(feature = "std")]
     #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
-    fn vec_result(self, n: usize) -> Vec<u8> {
+    fn finalize_vec(self, n: usize) -> Vec<u8> {
         let mut buf = vec![0u8; n];
-        self.xof_result().read(&mut buf);
+        self.finalize_xof().read(&mut buf);
         buf
     }
 }

signature/tests/signature_derive.rs

@@ -43,7 +43,7 @@ mod tests {
 
     impl DigestSigner<Sha256, DummySignature> for DummySigner {
         fn try_sign_digest(&self, digest: Sha256) -> Result<DummySignature, Error> {
-            DummySignature::from_bytes(&digest.result())
+            DummySignature::from_bytes(&digest.finalize())
         }
     }
 
@@ -56,7 +56,7 @@ mod tests {
 
     impl DigestVerifier<Sha256, DummySignature> for DummyVerifier {
         fn verify_digest(&self, digest: Sha256, signature: &DummySignature) -> Result<(), Error> {
-            let actual_digest = digest.result();
+            let actual_digest = digest.finalize();
             assert_eq!(signature.as_ref(), actual_digest.as_ref());
             Ok(())
         }

universal-hash/src/lib.rs

@@ -79,12 +79,12 @@ pub trait UniversalHash: Clone {
     fn reset(&mut self);
 
     /// Obtain the [`Output`] of a [`UniversalHash`] function and consume it.
-    fn result(self) -> Output<Self>;
+    fn finalize(self) -> Output<Self>;
 
     /// Obtain the [`Output`] of a [`UniversalHash`] computation and reset it back
     /// to its initial state.
-    fn result_reset(&mut self) -> Output<Self> {
-        let res = self.clone().result();
+    fn finalize_reset(&mut self) -> Output<Self> {
+        let res = self.clone().finalize();
         self.reset();
         res
     }
@@ -93,7 +93,7 @@ pub trait UniversalHash: Clone {
     /// This is useful when constructing Message Authentication Codes (MACs)
     /// from universal hash functions.
     fn verify(self, other: &Block<Self>) -> Result<(), Error> {
-        if self.result() == other.into() {
+        if self.finalize() == other.into() {
             Ok(())
         } else {
             Err(Error)