argon2/

params.rs

//! Argon2 password hash parameters.

#![allow(missing_copy_implementations, reason = "unnecessary")]
#![allow(clippy::doc_markdown, reason = "false positive")]

use crate::{Algorithm, Argon2, Error, Result, SYNC_POINTS, Version};
use base64ct::{Base64Unpadded as B64, Encoding};
use core::str::FromStr;

#[cfg(feature = "password-hash")]
use {
    core::fmt::{self, Display},
    password_hash::phc::{ParamsString, PasswordHash},
};

/// Argon2 password hash parameters.
///
/// These are parameters which can be encoded into a PHC hash string.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Params {
    /// Memory size, expressed in kibibytes, between 8\*`p_cost` and (2^32)-1.
    ///
    /// Value is an integer in decimal (1 to 10 digits).
    m_cost: u32,

    /// Number of iterations, between 1 and (2^32)-1.
    ///
    /// Value is an integer in decimal (1 to 10 digits).
    t_cost: u32,

    /// Degree of parallelism, between 1 and (2^24)-1.
    ///
    /// Value is an integer in decimal (1 to 8 digits).
    p_cost: u32,

    /// Key identifier.
    keyid: KeyId,

    /// Associated data.
    data: AssociatedData,

    /// Size of the output (in bytes).
    output_len: Option<usize>,
}

impl Params {
    /// Default memory cost.
    pub const DEFAULT_M_COST: u32 = 19 * 1024;

    /// Minimum number of 1 KiB memory blocks.
    #[allow(clippy::cast_possible_truncation)]
    pub const MIN_M_COST: u32 = 2 * SYNC_POINTS as u32; // 2 blocks per slice

    /// Maximum number of 1 KiB memory blocks.
    pub const MAX_M_COST: u32 = u32::MAX;

    /// Default number of iterations (i.e. "time").
    pub const DEFAULT_T_COST: u32 = 2;

    /// Minimum number of passes.
    pub const MIN_T_COST: u32 = 1;

    /// Maximum number of passes.
    pub const MAX_T_COST: u32 = u32::MAX;

    /// Default degree of parallelism.
    pub const DEFAULT_P_COST: u32 = 1;

    /// Minimum and maximum number of threads (i.e. parallelism).
    pub const MIN_P_COST: u32 = 1;

    /// Minimum and maximum number of threads (i.e. parallelism).
    pub const MAX_P_COST: u32 = 0xFFFFFF;

    /// Maximum length of a key ID in bytes.
    pub const MAX_KEYID_LEN: usize = 8;

    /// Maximum length of associated data in bytes.
    pub const MAX_DATA_LEN: usize = 32;

    /// Default output length.
    pub const DEFAULT_OUTPUT_LEN: usize = 32;

    /// Minimum digest size in bytes.
    pub const MIN_OUTPUT_LEN: usize = 4;

    /// Maximum digest size in bytes.
    pub const MAX_OUTPUT_LEN: usize = 0xFFFFFFFF;

    /// Default parameters (recommended).
    pub const DEFAULT: Self = Params {
        m_cost: Self::DEFAULT_M_COST,
        t_cost: Self::DEFAULT_T_COST,
        p_cost: Self::DEFAULT_P_COST,
        keyid: KeyId {
            bytes: [0u8; Self::MAX_KEYID_LEN],
            len: 0,
        },
        data: AssociatedData {
            bytes: [0u8; Self::MAX_DATA_LEN],
            len: 0,
        },
        output_len: None,
    };

    /// Create new parameters.
    ///
    /// # Arguments
    /// - `m_cost`: memory size in 1 KiB blocks. Between 8\*`p_cost` and (2^32)-1.
    /// - `t_cost`: number of iterations. Between 1 and (2^32)-1.
    /// - `p_cost`: degree of parallelism. Between 1 and (2^24)-1.
    /// - `output_len`: size of the KDF output in bytes. Default 32.
    ///
    /// # Errors
    /// - Returns [`Error::MemoryTooLittle`] if `m_cost` is smaller than [`Params::MIN_M_COST`].
    /// - Returns [`Error::ThreadsTooFew`] if `p_cost` is smaller than [`Params::MIN_P_COST`].
    /// - Returns [`Error::ThreadsTooMany`] if `p_cost` is larger than [`Params::MAX_P_COST`].
    /// - Returns [`Error::TimeTooSmall`] if `t_cost` is smaller than [`Params::MIN_T_COST`].
    /// - Returns [`Error::OutputTooShort`] if `output_len` is smaller than
    ///   [`Params::MIN_OUTPUT_LEN`].
    /// - Returns [`Error::OutputTooLong`] if `output_len` is larger than
    ///   [`Params::MAX_OUTPUT_LEN`].
    pub const fn new(
        m_cost: u32,
        t_cost: u32,
        p_cost: u32,
        output_len: Option<usize>,
    ) -> Result<Self> {
        if m_cost < Params::MIN_M_COST {
            return Err(Error::MemoryTooLittle);
        }

        // Note: we don't need to check `MAX_T_COST`, since it's `u32::MAX`

        if p_cost < Params::MIN_P_COST {
            return Err(Error::ThreadsTooFew);
        }

        if p_cost > Params::MAX_P_COST {
            return Err(Error::ThreadsTooMany);
        }

        // Note: we don't need to check `MAX_M_COST`, since it's `u32::MAX`

        if m_cost < p_cost * 8 {
            return Err(Error::MemoryTooLittle);
        }

        if t_cost < Params::MIN_T_COST {
            return Err(Error::TimeTooSmall);
        }

        if let Some(len) = output_len {
            if len < Params::MIN_OUTPUT_LEN {
                return Err(Error::OutputTooShort);
            }

            if len > Params::MAX_OUTPUT_LEN {
                return Err(Error::OutputTooLong);
            }
        }

        Ok(Params {
            m_cost,
            t_cost,
            p_cost,
            keyid: KeyId::EMPTY,
            data: AssociatedData::EMPTY,
            output_len,
        })
    }

    /// Memory size, expressed in kibibytes. Between 8\*`p_cost` and (2^32)-1.
    ///
    /// Value is an integer in decimal (1 to 10 digits).
    #[must_use]
    pub const fn m_cost(&self) -> u32 {
        self.m_cost
    }

    /// Number of iterations. Between 1 and (2^32)-1.
    ///
    /// Value is an integer in decimal (1 to 10 digits).
    #[must_use]
    pub const fn t_cost(&self) -> u32 {
        self.t_cost
    }

    /// Degree of parallelism. Between 1 and (2^24)-1.
    ///
    /// Value is an integer in decimal (1 to 3 digits).
    #[must_use]
    pub const fn p_cost(&self) -> u32 {
        self.p_cost
    }

    /// Key identifier: byte slice between 0 and 8 bytes in length.
    ///
    /// Defaults to an empty byte slice.
    ///
    /// Note this field is only present as a helper for reading/storing in
    /// the PHC hash string format (i.e. it is totally ignored from a
    /// cryptographical standpoint).
    ///
    /// On top of that, this field is not longer part of the Argon2 standard
    /// (see: <https://github.com/P-H-C/phc-winner-argon2/pull/173>), and should
    /// not be used for any non-legacy work.
    #[must_use]
    pub fn keyid(&self) -> &[u8] {
        self.keyid.as_bytes()
    }

    /// Associated data: byte slice between 0 and 32 bytes in length.
    ///
    /// Defaults to an empty byte slice.
    ///
    /// This field is not longer part of the argon2 standard
    /// (see: <https://github.com/P-H-C/phc-winner-argon2/pull/173>), and should
    /// not be used for any non-legacy work.
    #[must_use]
    pub fn data(&self) -> &[u8] {
        self.data.as_bytes()
    }

    /// Length of the output (in bytes).
    #[must_use]
    pub const fn output_len(&self) -> Option<usize> {
        self.output_len
    }

    /// Get the number of lanes.
    #[allow(clippy::cast_possible_truncation)]
    pub(crate) const fn lanes(&self) -> usize {
        self.p_cost as usize
    }

    /// Get the number of blocks in a lane.
    pub(crate) const fn lane_length(&self) -> usize {
        self.segment_length() * SYNC_POINTS
    }

    /// Get the segment length given the configured `m_cost` and `p_cost`.
    ///
    /// Minimum `memory_blocks` = 8*`L` blocks, where `L` is the number of lanes.
    pub(crate) const fn segment_length(&self) -> usize {
        let m_cost = self.m_cost as usize;

        let memory_blocks = if m_cost < 2 * SYNC_POINTS * self.lanes() {
            2 * SYNC_POINTS * self.lanes()
        } else {
            m_cost
        };

        memory_blocks / (self.lanes() * SYNC_POINTS)
    }

    /// Get the number of blocks required given the configured `m_cost` and `p_cost`.
    #[must_use]
    pub const fn block_count(&self) -> usize {
        self.segment_length() * self.lanes() * SYNC_POINTS
    }
}

impl Default for Params {
    fn default() -> Params {
        Params::DEFAULT
    }
}

macro_rules! param_buf {
    ($ty:ident, $name:expr, $max_len:expr, $error:expr, $doc:expr) => {
        #[doc = $doc]
        #[derive(Copy, Clone, Debug, Default, Eq, Hash, PartialEq, PartialOrd, Ord)]
        pub struct $ty {
            /// Byte array
            bytes: [u8; Self::MAX_LEN],

            /// Length of byte array
            len: usize,
        }

        impl $ty {
            /// Maximum length in bytes
            pub const MAX_LEN: usize = $max_len;

            #[doc = "Create a new"]
            #[doc = $name]
            #[doc = "from a slice.\n"]
            #[doc = "# Errors"]
            #[doc = concat!("Returns [`", stringify!($error), "`] in event the provided slice is too long.")]
            pub fn new(slice: &[u8]) -> Result<Self> {
                let mut bytes = [0u8; Self::MAX_LEN];
                let len = slice.len();
                bytes.get_mut(..len).ok_or($error)?.copy_from_slice(slice);
                Ok(Self { bytes, len })
            }

            /// Empty value.
            pub const EMPTY: Self = Self {
                bytes: [0u8; Self::MAX_LEN],
                len: 0,
            };

            #[doc = "Decode"]
            #[doc = $name]
            #[doc = " from a B64 string.\n"]
            #[doc = "# Errors"]
            #[doc = "Returns [`Error::B64Encoding`] if the providing string couldn't be decoded as B64." ]
            pub fn from_b64(s: &str) -> Result<Self> {
                let mut bytes = [0u8; Self::MAX_LEN];
                let len = B64::decode(s, &mut bytes)?.len();
                Ok(Self { bytes, len })
            }

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

            /// Get the length in bytes.
            pub const fn len(&self) -> usize {
                self.len
            }

            /// Is this value empty?
            pub const fn is_empty(&self) -> bool {
                self.len() == 0
            }
        }

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

        impl FromStr for $ty {
            type Err = Error;

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

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

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

// KeyId
param_buf!(
    KeyId,
    "KeyId",
    Params::MAX_KEYID_LEN,
    Error::KeyIdTooLong,
    "Key identifier"
);

// AssociatedData
param_buf!(
    AssociatedData,
    "AssociatedData",
    Params::MAX_DATA_LEN,
    Error::AdTooLong,
    "Associated data"
);

#[cfg(feature = "password-hash")]
impl Display for Params {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        ParamsString::try_from(self).map_err(|_| fmt::Error)?.fmt(f)
    }
}

#[cfg(feature = "password-hash")]
impl FromStr for Params {
    type Err = password_hash::Error;

    fn from_str(s: &str) -> password_hash::Result<Self> {
        let params_string =
            ParamsString::from_str(s).map_err(|_| password_hash::Error::ParamsInvalid)?;
        Self::try_from(&params_string)
    }
}

#[cfg(feature = "password-hash")]
impl TryFrom<&ParamsString> for Params {
    type Error = password_hash::Error;

    fn try_from(params: &ParamsString) -> password_hash::Result<Self> {
        let mut builder = ParamsBuilder::new();

        for (ident, value) in params.iter() {
            match ident.as_str() {
                "m" => {
                    builder.m_cost(
                        value
                            .decimal()
                            .map_err(|_| password_hash::Error::ParamInvalid { name: "m" })?,
                    );
                }
                "t" => {
                    builder.t_cost(
                        value
                            .decimal()
                            .map_err(|_| password_hash::Error::ParamInvalid { name: "t" })?,
                    );
                }
                "p" => {
                    builder.p_cost(
                        value
                            .decimal()
                            .map_err(|_| password_hash::Error::ParamInvalid { name: "p" })?,
                    );
                }
                "keyid" => {
                    builder.keyid(
                        value
                            .as_str()
                            .parse()
                            .map_err(|_| password_hash::Error::ParamInvalid { name: "keyid" })?,
                    );
                }
                "data" => {
                    builder.data(
                        value
                            .as_str()
                            .parse()
                            .map_err(|_| password_hash::Error::ParamInvalid { name: "data" })?,
                    );
                }
                _ => return Err(password_hash::Error::ParamsInvalid),
            }
        }

        Ok(builder.build()?)
    }
}

#[cfg(feature = "password-hash")]
impl TryFrom<&PasswordHash> for Params {
    type Error = password_hash::Error;

    fn try_from(hash: &PasswordHash) -> password_hash::Result<Self> {
        let mut params = Self::try_from(&hash.params)?;

        if let Some(output) = &hash.hash {
            params.output_len = Some(output.len());
        }

        Ok(params)
    }
}

#[cfg(feature = "password-hash")]
impl TryFrom<Params> for ParamsString {
    type Error = password_hash::Error;

    fn try_from(params: Params) -> password_hash::Result<ParamsString> {
        ParamsString::try_from(&params)
    }
}

#[cfg(feature = "password-hash")]
impl TryFrom<&Params> for ParamsString {
    type Error = password_hash::Error;

    fn try_from(params: &Params) -> password_hash::Result<ParamsString> {
        let mut output = ParamsString::new();

        for (name, value) in [
            ("m", params.m_cost),
            ("t", params.t_cost),
            ("p", params.p_cost),
        ] {
            output
                .add_decimal(name, value)
                .map_err(|_| password_hash::Error::ParamInvalid { name })?;
        }

        if !params.keyid.is_empty() {
            output
                .add_b64_bytes("keyid", params.keyid.as_bytes())
                .map_err(|_| password_hash::Error::ParamInvalid { name: "keyid" })?;
        }

        if !params.data.is_empty() {
            output
                .add_b64_bytes("data", params.data.as_bytes())
                .map_err(|_| password_hash::Error::ParamInvalid { name: "keyid" })?;
        }

        Ok(output)
    }
}

/// Builder for Argon2 [`Params`].
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ParamsBuilder {
    m_cost: u32,
    t_cost: u32,
    p_cost: u32,
    keyid: Option<KeyId>,
    data: Option<AssociatedData>,
    output_len: Option<usize>,
}

impl ParamsBuilder {
    /// Create a new builder with the default parameters.
    #[must_use]
    pub const fn new() -> Self {
        Self::DEFAULT
    }

    /// Set memory size, expressed in kibibytes, between 8\*`p_cost` and (2^32)-1.
    pub fn m_cost(&mut self, m_cost: u32) -> &mut Self {
        self.m_cost = m_cost;
        self
    }

    /// Set number of iterations, between 1 and (2^32)-1.
    pub fn t_cost(&mut self, t_cost: u32) -> &mut Self {
        self.t_cost = t_cost;
        self
    }

    /// Set degree of parallelism, between 1 and (2^24)-1.
    pub fn p_cost(&mut self, p_cost: u32) -> &mut Self {
        self.p_cost = p_cost;
        self
    }

    /// Set key identifier.
    pub fn keyid(&mut self, keyid: KeyId) -> &mut Self {
        self.keyid = Some(keyid);
        self
    }

    /// Set associated data.
    pub fn data(&mut self, data: AssociatedData) -> &mut Self {
        self.data = Some(data);
        self
    }

    /// Set length of the output (in bytes).
    pub fn output_len(&mut self, len: usize) -> &mut Self {
        self.output_len = Some(len);
        self
    }

    /// Get the finished [`Params`].
    ///
    /// This performs validations to ensure that the given parameters are valid
    /// and compatible with each other, and will return an error if they are not.
    ///
    /// # Errors
    /// Propagates errors from [`Params::new`]. See error documentation for that function for
    /// additional information.
    pub const fn build(&self) -> Result<Params> {
        let mut params = match Params::new(self.m_cost, self.t_cost, self.p_cost, self.output_len) {
            Ok(params) => params,
            Err(err) => return Err(err),
        };

        if let Some(keyid) = self.keyid {
            params.keyid = keyid;
        }

        if let Some(data) = self.data {
            params.data = data;
        };

        Ok(params)
    }

    /// Create a new [`Argon2`] context using the provided algorithm/version.
    ///
    /// # Errors
    /// Propagates errors from [`Params::new`]. See error documentation for that function for
    /// additional information.
    pub fn context(&self, algorithm: Algorithm, version: Version) -> Result<Argon2<'_>> {
        Ok(Argon2::new(algorithm, version, self.build()?))
    }

    /// Default parameters (recommended).
    pub const DEFAULT: ParamsBuilder = {
        let params = Params::DEFAULT;
        Self {
            m_cost: params.m_cost,
            t_cost: params.t_cost,
            p_cost: params.p_cost,
            keyid: None,
            data: None,
            output_len: params.output_len,
        }
    };
}

impl Default for ParamsBuilder {
    fn default() -> Self {
        Self::DEFAULT
    }
}

impl TryFrom<ParamsBuilder> for Params {
    type Error = Error;

    fn try_from(builder: ParamsBuilder) -> Result<Params> {
        builder.build()
    }
}

#[cfg(all(test, feature = "alloc", feature = "password-hash"))]
mod tests {

    use super::*;

    #[test]
    fn params_builder_bad_values() {
        assert_eq!(
            ParamsBuilder::new().m_cost(Params::MIN_M_COST - 1).build(),
            Err(Error::MemoryTooLittle)
        );
        assert_eq!(
            ParamsBuilder::new().t_cost(Params::MIN_T_COST - 1).build(),
            Err(Error::TimeTooSmall)
        );
        assert_eq!(
            ParamsBuilder::new().p_cost(Params::MIN_P_COST - 1).build(),
            Err(Error::ThreadsTooFew)
        );
        assert_eq!(
            ParamsBuilder::new()
                .m_cost(Params::DEFAULT_P_COST * 8 - 1)
                .build(),
            Err(Error::MemoryTooLittle)
        );
        assert_eq!(
            ParamsBuilder::new()
                .m_cost((Params::MAX_P_COST + 1) * 8)
                .p_cost(Params::MAX_P_COST + 1)
                .build(),
            Err(Error::ThreadsTooMany)
        );
    }

    #[test]
    fn associated_data_too_long() {
        let ret = AssociatedData::new(&[0u8; Params::MAX_DATA_LEN + 1]);
        assert_eq!(ret, Err(Error::AdTooLong));
    }

    #[test]
    fn keyid_too_long() {
        let ret = KeyId::new(&[0u8; Params::MAX_KEYID_LEN + 1]);
        assert_eq!(ret, Err(Error::KeyIdTooLong));
    }
}