mcf: add Field newtype (#1914)

Also extracts a `fields` submodule.

The `Field` newtype is useful as a place to provide additional methods
for operating on individual fields, such as encoding/decoding various
flavors of Base64, or parsing `k=v,...` mappings.

The functionality to do that is not yet implemented, but having a type
where we can put such functionality is the starting place.

Author: tarcieri

mcf/src/fields.rs

@@ -0,0 +1,94 @@
+//! Fields of an MCF password hash, delimited by `$`
+
+use crate::{Error, Result};
+use core::fmt;
+
+/// MCF field delimiter: `$`.
+pub const DELIMITER: char = '$';
+
+/// Iterator over the `$`-delimited fields of an MCF hash.
+pub struct Fields<'a>(&'a str);
+
+impl<'a> Fields<'a> {
+    /// Create a new field iterator from an MCF hash, returning an error in the event the hash
+    /// doesn't start with a leading `$` prefix.
+    pub(crate) fn new(s: &'a str) -> Result<Self> {
+        let mut ret = Self(s);
+
+        if ret.next() != Some(Field("")) {
+            return Err(Error {});
+        }
+
+        Ok(ret)
+    }
+}
+
+impl<'a> Iterator for Fields<'a> {
+    type Item = Field<'a>;
+
+    fn next(&mut self) -> Option<Field<'a>> {
+        if self.0.is_empty() {
+            return None;
+        }
+
+        match self.0.split_once(DELIMITER) {
+            Some((field, rest)) => {
+                self.0 = rest;
+                Some(Field(field))
+            }
+            None => {
+                let ret = self.0;
+                self.0 = "";
+                Some(Field(ret))
+            }
+        }
+    }
+}
+
+/// Individual field of an MCF hash, delimited by `$`.
+///
+/// Fields are constrained to characters in the regexp range `[A-Za-z0-9./+=,\-]`.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, PartialOrd, Ord)]
+pub struct Field<'a>(&'a str);
+
+impl<'a> Field<'a> {
+    /// Create a new [`Field`], validating the provided characters are in the allowed range.
+    pub fn new(s: &'a str) -> Result<Self> {
+        let field = Field(s);
+        field.validate()?;
+        Ok(field)
+    }
+
+    /// Borrow the field's contents as a `str`.
+    pub fn as_str(&self) -> &'a str {
+        self.0
+    }
+
+    /// Validate a field in the password hash is well-formed.
+    pub(crate) fn validate(&self) -> Result<()> {
+        if self.0.is_empty() {
+            return Err(Error {});
+        }
+
+        for c in self.0.chars() {
+            match c {
+                'A'..='Z' | 'a'..='z' | '0'..='9' | '.' | '/' | '+' | '=' | ',' | '-' => (),
+                _ => return Err(Error {}),
+            }
+        }
+
+        Ok(())
+    }
+}
+
+impl AsRef<str> for Field<'_> {
+    fn as_ref(&self) -> &str {
+        self.as_str()
+    }
+}
+
+impl fmt::Display for Field<'_> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.write_str(self.0)
+    }
+}

mcf/src/lib.rs

@@ -15,12 +15,13 @@
 
 extern crate alloc;
 
+mod fields;
+
+pub use fields::{Field, Fields};
+
 use alloc::string::String;
 use core::{fmt, str};
 
-/// MCF field delimiter: `$`.
-pub const DELIMITER: char = '$';
-
 /// Debug message used in panics when invariants aren't properly held.
 const INVARIANT_MSG: &str = "should be ensured valid by constructor";
 
@@ -59,6 +60,7 @@ impl McfHash {
             .expect(INVARIANT_MSG)
             .next()
             .expect(INVARIANT_MSG)
+            .as_str()
     }
 
     /// Get an iterator over the parts of the password hash as delimited by `$`, excluding the
@@ -68,7 +70,7 @@ impl McfHash {
 
         // Remove the leading identifier
         let id = fields.next().expect(INVARIANT_MSG);
-        debug_assert_eq!(id, self.id());
+        debug_assert_eq!(self.id(), id.as_str());
 
         fields
     }
@@ -101,13 +103,13 @@ fn validate(s: &str) -> Result<()> {
 
     // Validate characters in the identifier field
     let id = fields.next().ok_or(Error {})?;
-    validate_id(id)?;
+    validate_id(id.as_str())?;
 
     // Validate the remaining fields have an appropriate format
     let mut any = false;
     for field in fields {
         any = true;
-        validate_field(field)?;
+        field.validate()?;
     }
 
     // Must have at least one field.
@@ -143,63 +145,6 @@ fn validate_id(id: &str) -> Result<()> {
     Ok(())
 }
 
-/// Validate a field in the password hash is well-formed.
-///
-/// Fields include characters in the regexp range `[A-Za-z0-9./+=,\-]`.
-fn validate_field(field: &str) -> Result<()> {
-    if field.is_empty() {
-        return Err(Error {});
-    }
-
-    for c in field.chars() {
-        match c {
-            'A'..='Z' | 'a'..='z' | '0'..='9' | '.' | '/' | '+' | '=' | ',' | '-' => (),
-            _ => return Err(Error {}),
-        }
-    }
-
-    Ok(())
-}
-
-/// Iterator over the `$`-delimited fields of an MCF hash.
-pub struct Fields<'a>(&'a str);
-
-impl<'a> Fields<'a> {
-    /// Create a new field iterator from an MCF hash, returning an error in the event the hash
-    /// doesn't start with a leading `$` prefix.
-    fn new(s: &'a str) -> Result<Self> {
-        let mut ret = Self(s);
-
-        if ret.next() != Some("") {
-            return Err(Error {});
-        }
-
-        Ok(ret)
-    }
-}
-
-impl<'a> Iterator for Fields<'a> {
-    type Item = &'a str;
-
-    fn next(&mut self) -> Option<&'a str> {
-        if self.0.is_empty() {
-            return None;
-        }
-
-        match self.0.split_once(DELIMITER) {
-            Some((field, rest)) => {
-                self.0 = rest;
-                Some(field)
-            }
-            None => {
-                let ret = self.0;
-                self.0 = "";
-                Some(ret)
-            }
-        }
-    }
-}
-
 /// Result type for `mcf`.
 pub type Result<T> = core::result::Result<T, Error>;
 

mcf/tests/mcf.rs

@@ -22,11 +22,11 @@ fn parse_sha512_hash() {
     assert_eq!("6", hash.id());
 
     let mut fields = hash.fields();
-    assert_eq!("rounds=100000", fields.next().unwrap());
-    assert_eq!("exn6tVc2j/MZD8uG", fields.next().unwrap());
+    assert_eq!("rounds=100000", fields.next().unwrap().as_str());
+    assert_eq!("exn6tVc2j/MZD8uG", fields.next().unwrap().as_str());
     assert_eq!(
         "BI1Xh8qQSK9J4m14uwy7abn.ctj/TIAzlaVCto0MQrOFIeTXsc1iwzH16XEWo/a7c7Y9eVJvufVzYAs4EsPOy0",
-        fields.next().unwrap()
+        fields.next().unwrap().as_str()
     );
     assert_eq!(None, fields.next());
 }