phc 0.6.1

//! Outputs from password hashing functions.

use crate::{B64, Error, Result};
use base64ct::Encoding;
use core::{cmp::Ordering, fmt, str::FromStr};
use ctutils::{Choice, CtEq};

/// 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 [`CtEq`] trait from the [`ctutils`] crate and uses it to perform
/// constant-time comparisons.
///
/// Additionally, the [`PartialEq`] and [`Eq`] trait impls for [`Output`] use [`CtEq`] 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::from_rng`][`crate::SaltString::from_rng`] and
/// [`SaltString::try_from_rng`][`crate::SaltString::try_from_rng`] functions 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,
}

#[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).div_ceil(3);

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

    /// 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::OutputSize {
                provided: Ordering::Less,
                expected: Self::MIN_LENGTH,
            });
        }

        if output_size > Self::MAX_LENGTH {
            return Err(Error::OutputSize {
                provided: Ordering::Greater,
                expected: Self::MAX_LENGTH,
            });
        }

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

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

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

    /// 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 decode(input: &str) -> Result<Self> {
        let mut bytes = [0u8; Self::MAX_LENGTH];
        B64::decode(input, &mut bytes)
            .map_err(Into::into)
            .and_then(Self::new)
    }

    /// 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 encode<'a>(&self, out: &'a mut [u8]) -> Result<&'a str> {
        Ok(B64::encode(self.as_ref(), out)?)
    }

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

    /// DEPRECATED: parse B64-encoded [`Output`], i.e. using the PHC string  specification's
    /// restricted interpretation of Base64.
    #[deprecated(since = "0.3.0", note = "Use `Output::decode` instead")]
    pub fn b64_decode(input: &str) -> Result<Self> {
        Self::decode(input)
    }

    /// DEPRECATED: 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.
    #[deprecated(since = "0.3.0", note = "Use `Output::encode` instead")]
    pub fn b64_encode<'a>(&self, out: &'a mut [u8]) -> Result<&'a str> {
        self.encode(out)
    }

    /// Get the length of this [`Output`] when encoded as B64.
    #[deprecated(since = "0.3.0", note = "Use `Output::encoded_len` instead")]
    pub fn b64_len(&self) -> usize {
        self.encoded_len()
    }
}

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

impl CtEq 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::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)
            .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)]
#[allow(clippy::unwrap_used)]
mod tests {
    use super::{Error, Ordering, 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::OutputSize {
                provided: Ordering::Less,
                expected: Output::MIN_LENGTH
            }
        );
    }

    #[test]
    fn reject_new_too_long() {
        let bytes = [65u8; 65];
        let err = Output::new(&bytes).err().unwrap();
        assert_eq!(
            err,
            Error::OutputSize {
                provided: Ordering::Greater,
                expected: Output::MAX_LENGTH
            }
        );
    }

    #[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);
    }
}