mcf 0.6.0

Pure Rust implementation of the Modular Crypt Format (MCF) which is used to store password hashes in the form `${id}$...`
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

//! Fields of an MCF password hash, delimited by `$`

use crate::{Error, Result};
use core::fmt;

#[cfg(feature = "base64")]
use crate::Base64;
#[cfg(all(feature = "alloc", feature = "base64"))]
use alloc::vec::Vec;

/// 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.
    ///
    /// NOTE: this method is deliberately non-public because it doesn't first validate the fields
    /// are well-formed. Calling it with non-validated inputs can lead to invalid [`Field`] values.
    pub(crate) fn new(s: &'a str) -> Self {
        let mut ret = Self(s);

        let should_be_empty = ret.next().expect("shouldn't be empty");
        debug_assert_eq!(should_be_empty.as_str(), "");

        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
    }

    /// Decode Base64 into the provided output buffer.
    #[cfg(feature = "base64")]
    pub fn decode_base64_into(self, base64_variant: Base64, out: &mut [u8]) -> Result<&[u8]> {
        Ok(base64_variant.decode(self.0, out)?)
    }

    /// Decode this field as the provided Base64 variant.
    #[cfg(all(feature = "alloc", feature = "base64"))]
    pub fn decode_base64(self, base64_variant: Base64) -> Result<Vec<u8>> {
        Ok(base64_variant.decode_vec(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::FieldInvalid);
        }

        for c in self.0.chars() {
            match c {
                'A'..='Z' | 'a'..='z' | '0'..='9' | '.' | '/' | '+' | '=' | ',' | '-' => (),
                _ => return Err(Error::EncodingInvalid),
            }
        }

        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)
    }
}