phc 0.6.1

Pure Rust implementation of the Password Hashing Competition (PHC) string format which is used for storing password hashes
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

//! Error types.

use crate::Salt;
use base64ct::Error as B64Error;
use core::{cmp::Ordering, fmt};

/// Result type.
pub type Result<T> = core::result::Result<T, Error>;

/// Password hashing errors.
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum Error {
    /// "B64" encoding error.
    Base64(B64Error),

    /// Password hash string invalid.
    MissingField,

    /// Output size unexpected.
    OutputSize {
        /// Indicates why the output size is unexpected.
        ///
        /// - [`Ordering::Less`]: Size is too small.
        /// - [`Ordering::Equal`]: Size is not exactly as `expected`.
        /// - [`Ordering::Greater`]: Size is too long.
        provided: Ordering,

        /// Expected output size in relation to `provided`.
        ///
        /// - [`Ordering::Less`]: Minimum size.
        /// - [`Ordering::Equal`]: Expected size.
        /// - [`Ordering::Greater`]: Maximum size.
        expected: usize,
    },

    /// Duplicate parameter name encountered.
    ParamNameDuplicated,

    /// Invalid parameter name.
    ParamNameInvalid,

    /// Parameter value is invalid.
    ParamValueInvalid,

    /// Parameter value is too long.
    ParamValueTooLong,

    /// Maximum number of parameters exceeded.
    ParamsMaxExceeded,

    /// Salt too short.
    SaltTooShort,

    /// Salt too long.
    SaltTooLong,

    /// Password hash string contains trailing data.
    TrailingData,

    /// Value exceeds the maximum allowed length.
    ValueTooLong,
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> core::result::Result<(), fmt::Error> {
        match self {
            Self::Base64(err) => write!(f, "{err}"),
            Self::MissingField => write!(f, "password hash string missing field"),
            Self::OutputSize { provided, expected } => match provided {
                Ordering::Less => write!(
                    f,
                    "output size too short, expected at least {expected} bytes",
                ),
                Ordering::Equal => write!(f, "output size unexpected, expected {expected} bytes"),
                Ordering::Greater => {
                    write!(f, "output size too long, expected at most {expected} bytes")
                }
            },
            Self::ParamNameDuplicated => write!(f, "duplicate parameter"),
            Self::ParamNameInvalid => write!(f, "invalid parameter name"),
            Self::ParamValueInvalid => write!(f, "invalid parameter value"),
            Self::ParamValueTooLong => write!(f, "parameter value too long"),
            Self::ParamsMaxExceeded => write!(f, "maximum number of parameters reached"),
            Self::SaltTooShort => write!(f, "salt too short (minimum {} bytes)", Salt::MIN_LENGTH),
            Self::SaltTooLong => write!(f, "salt too long (maximum {} bytes)", Salt::MAX_LENGTH),
            Self::TrailingData => write!(f, "password hash has unexpected trailing characters"),
            Self::ValueTooLong => f.write_str("value too long"),
        }
    }
}

impl core::error::Error for Error {
    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
        match self {
            Self::Base64(err) => Some(err),
            _ => None,
        }
    }
}

impl From<B64Error> for Error {
    fn from(err: B64Error) -> Error {
        Error::Base64(err)
    }
}

impl From<base64ct::InvalidLengthError> for Error {
    fn from(_: base64ct::InvalidLengthError) -> Error {
        Error::Base64(B64Error::InvalidLength)
    }
}