password-hash 0.5.0-pre.0

//! Outputs from password hashing functions.

use crate::{Encoding, Error, Result};
use core::{cmp::PartialEq, fmt, str::FromStr};
use subtle::{Choice, ConstantTimeEq};

/// Output from password hashing functions, i.e. the "hash" or "digest"
/// as raw bytes.
///
/// The [`Output`] type implements the RECOMMENDED best practices described in
/// the [PHC string format specification][1], namely:
///
/// > The hash output, for a verification, must be long enough to make preimage
/// > attacks at least as hard as password guessing. To promote wide acceptance,
/// > a default output size of 256 bits (32 bytes, encoded as 43 characters) is
/// > recommended. Function implementations SHOULD NOT allow outputs of less
/// > than 80 bits to be used for password verification.
///
/// # Recommended length
/// Per the description above, the recommended default length for an [`Output`]
/// of a password hashing function is **32-bytes** (256-bits).
///
/// # Constraints
/// The above guidelines are interpreted into the following constraints:
///
/// - Minimum length: **10**-bytes (80-bits)
/// - Maximum length: **64**-bytes (512-bits)
///
/// The specific recommendation of a 64-byte maximum length is taken as a best
/// practice from the hash output guidelines for [Argon2 Encoding][2] given in
/// the same document:
///
/// > The hash output...length shall be between 12 and 64 bytes (16 and 86
/// > characters, respectively). The default output length is 32 bytes
/// > (43 characters).
///
/// Based on this guidance, this type enforces an upper bound of 64-bytes
/// as a reasonable maximum, and recommends using 32-bytes.
///
/// # Constant-time comparisons
/// The [`Output`] type impls the [`ConstantTimeEq`] trait from the [`subtle`]
/// crate and uses it to perform constant-time comparisons.
///
/// Additionally the [`PartialEq`] and [`Eq`] trait impls for [`Output`] use
/// [`ConstantTimeEq`] when performing comparisons.
///
/// ## Attacks on non-constant-time password hash comparisons
/// Comparing password hashes in constant-time is known to mitigate at least
/// one [poorly understood attack][3] involving an adversary with the following
/// knowledge/capabilities:
///
/// - full knowledge of what password hashing algorithm is being used
///   including any relevant configurable parameters
/// - knowledge of the salt for a particular victim
/// - ability to accurately measure a timing side-channel on comparisons
///   of the password hash over the network
///
/// An attacker with the above is able to perform an offline computation of
/// the hash for any chosen password in such a way that it will match the
/// hash computed by the server.
///
/// As noted above, they also measure timing variability in the server's
/// comparison of the hash it computes for a given password and a target hash
/// the attacker is trying to learn.
///
/// When the attacker observes a hash comparison that takes longer than their
/// previous attempts, they learn that they guessed another byte in the
/// password hash correctly. They can leverage repeated measurements and
/// observations with different candidate passwords to learn the password
/// hash a byte-at-a-time in a manner similar to other such timing side-channel
/// attacks.
///
/// The attack may seem somewhat counterintuitive since learning prefixes of a
/// password hash does not reveal any additional information about the password
/// itself. However, the above can be combined with an offline dictionary
/// attack where the attacker is able to determine candidate passwords to send
/// to the server by performing a brute force search offline and selecting
/// candidate passwords whose hashes match the portion of the prefix they have
/// learned so far.
///
/// As the attacker learns a longer and longer prefix of the password hash,
/// they are able to more effectively eliminate candidate passwords offline as
/// part of a dictionary attack, until they eventually guess the correct
/// password or exhaust their set of candidate passwords.
///
/// ## Mitigations
/// While we have taken care to ensure password hashes are compared in constant
/// time, we would also suggest preventing such attacks by using randomly
/// generated salts and keeping those salts secret.
///
/// The [`SaltString::generate`][`crate::SaltString::generate`] function can be
/// used to generate random high-entropy salt values.
///
/// [1]: https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md#function-duties
/// [2]: https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md#argon2-encoding
/// [3]: https://web.archive.org/web/20130208100210/http://security-assessment.com/files/documents/presentations/TimingAttackPresentation2012.pdf
#[derive(Copy, Clone, Eq)]
pub struct Output {
    /// Byte array containing a password hashing function output.
    bytes: [u8; Self::MAX_LENGTH],

    /// Length of the password hashing function output in bytes.
    length: u8,

    /// Encoding which output should be serialized with.
    encoding: Encoding,
}

#[allow(clippy::len_without_is_empty)]
impl Output {
    /// Minimum length of a [`Output`] string: 10-bytes.
    pub const MIN_LENGTH: usize = 10;

    /// Maximum length of [`Output`] string: 64-bytes.
    ///
    /// See type-level documentation about [`Output`] for more information.
    pub const MAX_LENGTH: usize = 64;

    /// Maximum length of [`Output`] when encoded as B64 string: 86-bytes
    /// (i.e. 86 ASCII characters)
    pub const B64_MAX_LENGTH: usize = ((Self::MAX_LENGTH * 4) / 3) + 1;

    /// Create a [`Output`] from the given byte slice, validating it according
    /// to [`Output::MIN_LENGTH`] and [`Output::MAX_LENGTH`] restrictions.
    pub fn new(input: &[u8]) -> Result<Self> {
        Self::init_with(input.len(), |bytes| {
            bytes.copy_from_slice(input);
            Ok(())
        })
    }

    /// Create a [`Output`] from the given byte slice and [`Encoding`],
    /// validating it according to [`Output::MIN_LENGTH`] and
    /// [`Output::MAX_LENGTH`] restrictions.
    pub fn new_with_encoding(input: &[u8], encoding: Encoding) -> Result<Self> {
        let mut result = Self::new(input)?;
        result.encoding = encoding;
        Ok(result)
    }

    /// Initialize an [`Output`] using the provided method, which is given
    /// a mutable byte slice into which it should write the output.
    ///
    /// The `output_size` (in bytes) must be known in advance, as well as at
    /// least [`Output::MIN_LENGTH`] bytes and at most [`Output::MAX_LENGTH`]
    /// bytes.
    pub fn init_with<F>(output_size: usize, f: F) -> Result<Self>
    where
        F: FnOnce(&mut [u8]) -> Result<()>,
    {
        if output_size < Self::MIN_LENGTH {
            return Err(Error::OutputTooShort);
        }

        if output_size > Self::MAX_LENGTH {
            return Err(Error::OutputTooLong);
        }

        let mut bytes = [0u8; Self::MAX_LENGTH];
        f(&mut bytes[..output_size])?;

        Ok(Self {
            bytes,
            length: output_size as u8,
            encoding: Encoding::default(),
        })
    }

    /// Borrow the output value as a byte slice.
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes[..self.len()]
    }

    /// Get the [`Encoding`] that this [`Output`] is serialized with.
    pub fn encoding(&self) -> Encoding {
        self.encoding
    }

    /// Get the length of the output value as a byte slice.
    pub fn len(&self) -> usize {
        usize::from(self.length)
    }

    /// Parse B64-encoded [`Output`], i.e. using the PHC string
    /// specification's restricted interpretation of Base64.
    pub fn b64_decode(input: &str) -> Result<Self> {
        Self::decode(input, Encoding::B64)
    }

    /// Write B64-encoded [`Output`] to the provided buffer, returning
    /// a sub-slice containing the encoded data.
    ///
    /// Returns an error if the buffer is too short to contain the output.
    pub fn b64_encode<'a>(&self, out: &'a mut [u8]) -> Result<&'a str> {
        self.encode(out, Encoding::B64)
    }

    /// Decode the given input string using the specified [`Encoding`].
    pub fn decode(input: &str, encoding: Encoding) -> Result<Self> {
        let mut bytes = [0u8; Self::MAX_LENGTH];
        encoding
            .decode(input, &mut bytes)
            .map_err(Into::into)
            .and_then(|decoded| Self::new_with_encoding(decoded, encoding))
    }

    /// Encode this [`Output`] using the specified [`Encoding`].
    pub fn encode<'a>(&self, out: &'a mut [u8], encoding: Encoding) -> Result<&'a str> {
        Ok(encoding.encode(self.as_ref(), out)?)
    }

    /// Get the length of this [`Output`] when encoded as B64.
    pub fn b64_len(&self) -> usize {
        Encoding::B64.encoded_len(self.as_ref())
    }
}

impl AsRef<[u8]> for Output {
    fn as_ref(&self) -> &[u8] {
        self.as_bytes()
    }
}

impl ConstantTimeEq for Output {
    fn ct_eq(&self, other: &Self) -> Choice {
        self.as_ref().ct_eq(other.as_ref())
    }
}

impl FromStr for Output {
    type Err = Error;

    fn from_str(s: &str) -> Result<Self> {
        Self::b64_decode(s)
    }
}

impl PartialEq for Output {
    fn eq(&self, other: &Self) -> bool {
        self.ct_eq(other).into()
    }
}

impl TryFrom<&[u8]> for Output {
    type Error = Error;

    fn try_from(input: &[u8]) -> Result<Output> {
        Self::new(input)
    }
}

impl fmt::Display for Output {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut buffer = [0u8; Self::B64_MAX_LENGTH];
        self.encode(&mut buffer, self.encoding)
            .map_err(|_| fmt::Error)
            .and_then(|encoded| f.write_str(encoded))
    }
}

impl fmt::Debug for Output {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Output(\"{}\")", self)
    }
}

#[cfg(test)]
mod tests {
    use super::{Error, Output};

    #[test]
    fn new_with_valid_min_length_input() {
        let bytes = [10u8; 10];
        let output = Output::new(&bytes).unwrap();
        assert_eq!(output.as_ref(), &bytes);
    }

    #[test]
    fn new_with_valid_max_length_input() {
        let bytes = [64u8; 64];
        let output = Output::new(&bytes).unwrap();
        assert_eq!(output.as_ref(), &bytes);
    }

    #[test]
    fn reject_new_too_short() {
        let bytes = [9u8; 9];
        let err = Output::new(&bytes).err().unwrap();
        assert_eq!(err, Error::OutputTooShort);
    }

    #[test]
    fn reject_new_too_long() {
        let bytes = [65u8; 65];
        let err = Output::new(&bytes).err().unwrap();
        assert_eq!(err, Error::OutputTooLong);
    }

    #[test]
    fn partialeq_true() {
        let a = Output::new(&[1u8; 32]).unwrap();
        let b = Output::new(&[1u8; 32]).unwrap();
        assert_eq!(a, b);
    }

    #[test]
    fn partialeq_false() {
        let a = Output::new(&[1u8; 32]).unwrap();
        let b = Output::new(&[2u8; 32]).unwrap();
        assert_ne!(a, b);
    }
}