password-hash 0.3.2

Traits which describe the functionality of password hashing algorithms, as well as a `no_std`-friendly implementation of the PHC string format (a well-defined subset of the Modular Crypt Format a.k.a. MCF)
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

//! Error types.

pub use base64ct::Error as B64Error;

use core::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 {
    /// Unsupported algorithm.
    Algorithm,

    /// "B64" encoding error.
    B64Encoding(B64Error),

    /// Cryptographic error.
    Crypto,

    /// Output too short (min 10-bytes).
    OutputTooShort,

    /// Output too long (max 64-bytes).
    OutputTooLong,

    /// Duplicate parameter name encountered.
    ParamNameDuplicated,

    /// Invalid parameter name.
    ParamNameInvalid,

    /// Invalid parameter value.
    ParamValueInvalid(InvalidValue),

    /// Maximum number of parameters exceeded.
    ParamsMaxExceeded,

    /// Invalid password.
    Password,

    /// Password hash string contains invalid characters.
    PhcStringInvalid,

    /// Password hash string too short.
    PhcStringTooShort,

    /// Password hash string too long.
    PhcStringTooLong,

    /// Salt invalid.
    SaltInvalid(InvalidValue),

    /// Invalid algorithm version.
    Version,
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> core::result::Result<(), fmt::Error> {
        match self {
            Self::Algorithm => write!(f, "unsupported algorithm"),
            Self::B64Encoding(err) => write!(f, "{}", err),
            Self::Crypto => write!(f, "cryptographic error"),
            Self::OutputTooShort => f.write_str("PHF output too short (min 10-bytes)"),
            Self::OutputTooLong => f.write_str("PHF output too long (max 64-bytes)"),
            Self::ParamNameDuplicated => f.write_str("duplicate parameter"),
            Self::ParamNameInvalid => f.write_str("invalid parameter name"),
            Self::ParamValueInvalid(val_err) => write!(f, "invalid parameter value: {}", val_err),
            Self::ParamsMaxExceeded => f.write_str("maximum number of parameters reached"),
            Self::Password => write!(f, "invalid password"),
            Self::PhcStringInvalid => write!(f, "password hash string invalid"),
            Self::PhcStringTooShort => write!(f, "password hash string too short"),
            Self::PhcStringTooLong => write!(f, "password hash string too long"),
            Self::SaltInvalid(val_err) => write!(f, "salt invalid: {}", val_err),
            Self::Version => write!(f, "invalid algorithm version"),
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for Error {}

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

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

/// Parse errors relating to invalid parameter values or salts.
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum InvalidValue {
    /// Character is not in the allowed set.
    InvalidChar(char),

    /// Format is invalid.
    InvalidFormat,

    /// Value is malformed.
    Malformed,

    /// Value exceeds the maximum allowed length.
    TooLong,

    /// Value does not satisfy the minimum length.
    TooShort,
}

impl InvalidValue {
    /// Create an [`Error::ParamValueInvalid`] which warps this error.
    pub fn param_error(self) -> Error {
        Error::ParamValueInvalid(self)
    }

    /// Create an [`Error::SaltInvalid`] which wraps this error.
    pub fn salt_error(self) -> Error {
        Error::SaltInvalid(self)
    }
}

impl fmt::Display for InvalidValue {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> core::result::Result<(), fmt::Error> {
        match self {
            Self::InvalidChar(c) => write!(f, "contains invalid character: '{}'", c),
            Self::InvalidFormat => f.write_str("value format is invalid"),
            Self::Malformed => f.write_str("value malformed"),
            Self::TooLong => f.write_str("value to long"),
            Self::TooShort => f.write_str("value to short"),
        }
    }
}