path: root/openpgp/src/crypto/s2k.rs

//! String-to-Key (S2K) specifiers.
//!
//! String-to-key (S2K) specifiers are used to convert password
//! strings into symmetric-key encryption/decryption keys.  See
//! [Section 3.7 of RFC 4880].
//!
//!   [Section 3.7 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-3.7

use crate::Error;
use crate::Result;
use crate::HashAlgorithm;
use crate::crypto::Password;
use crate::crypto::SessionKey;
use crate::crypto::hash::Digest;

use std::fmt;

#[cfg(test)]
use quickcheck::{Arbitrary, Gen};
#[cfg(test)]
use rand::Rng;

/// String-to-Key (S2K) specifiers.
///
/// String-to-key (S2K) specifiers are used to convert password
/// strings into symmetric-key encryption/decryption keys.  See
/// [Section 3.7 of RFC 4880].  This is used to encrypt messages with
/// a password (see [`SKESK`]), and to protect secret keys (see
/// [`key::Encrypted`]).
///
///   [Section 3.7 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-3.7
///   [`SKESK`]: ../../packet/enum.SKESK.html
///   [`key::Encrypted`]: ../../packet/key/struct.Encrypted.html
///
/// Note: This enum cannot be exhaustively matched to allow future
/// extensions.
#[non_exhaustive]
#[derive(Clone, PartialEq, Eq, Hash, Debug)]
pub enum S2K {
    /// Repeatently hashes the password with a public `salt` value.
    Iterated {
        /// Hash used for key derivation.
        hash: HashAlgorithm,
        /// Public salt value mixed into the password.
        salt: [u8; 8],
        /// Number of bytes to hash.
        ///
        /// This parameter increases the workload for an attacker
        /// doing a dictionary attack.  Note that not all values are
        /// representable.  See [`S2K::new_iterated`].
        ///
        ///   [`S2K::new_iterated`]: #method.new_iterated
        hash_bytes: u32,
    },

    /// Hashes the password with a public `salt` value.
    ///
    /// This mechanism does not use iteration to increase the time it
    /// takes to derive the key from the password.  This makes
    /// dictionary attacks more feasible.  Do not use this variant.
    #[deprecated(note = "Use `S2K::Iterated`.")]
    Salted {
        /// Hash used for key derivation.
        hash: HashAlgorithm,
        /// Public salt value mixed into the password.
        salt: [u8; 8],
    },

    /// Simply hashes the password.
    ///
    /// This mechanism uses neither iteration to increase the time it
    /// takes to derive the key from the password nor does it salt the
    /// password.  This makes dictionary attacks more feasible.
    ///
    /// This mechanism has been deprecated in RFC 4880. Do not use this
    /// variant.
    #[deprecated(note = "Use `S2K::Iterated`.")]
    Simple {
        /// Hash used for key derivation.
        hash: HashAlgorithm
    },

    /// Private S2K algorithm.
    Private {
        /// Tag identifying the private algorithm.
        ///
        /// Tags 100 to 110 are reserved for private use.
        tag: u8,

        /// The parameters for the private algorithm.
        ///
        /// This is optional, because when we parse a packet
        /// containing an unknown S2K algorithm, we do not know how
        /// many octets to attribute to the S2K's parameters.  In this
        /// case, `parameters` is set to `None`.  Note that the
        /// information is not lost, but stored in the packet.  If the
        /// packet is serialized again, it is written out.
        parameters: Option<Box<[u8]>>,
    },

    /// Unknown S2K algorithm.
    Unknown {
        /// Tag identifying the unknown algorithm.
        tag: u8,

        /// The parameters for the unknown algorithm.
        ///
        /// This is optional, because when we parse a packet
        /// containing an unknown S2K algorithm, we do not know how
        /// many octets to attribute to the S2K's parameters.  In this
        /// case, `parameters` is set to `None`.  Note that the
        /// information is not lost, but stored in the packet.  If the
        /// packet is serialized again, it is written out.
        parameters: Option<Box<[u8]>>,
    },
}
assert_send_and_sync!{S2K}

impl Default for S2K {
    fn default() -> Self {
        S2K::new_iterated(
            // SHA2-256, being optimized for implementations on
            // architectures with a word size of 32 bit, has a more
            // consistent runtime across different architectures than
            // SHA2-512.  Furthermore, the digest size is large enough
            // for every cipher algorithm currently in use.
            HashAlgorithm::SHA256,
            // This is the largest count that OpenPGP can represent.
            // On moderate machines, like my Intel(R) Core(TM) i5-2400
            // CPU @ 3.10GHz, it takes ~354ms to derive a key.
            0x3e00000,
        ).expect("0x3e00000 is representable")
    }
}

impl S2K {
    /// Creates a new iterated `S2K` object.
    ///
    /// Usually, you should use `S2K`s [`Default`] implementation to
    /// create `S2K` objects with sane default parameters.  The
    /// parameters are chosen with contemporary machines in mind, and
    /// should also be usable on lower-end devices like smart phones.
    ///
    ///   [`Default`]: https://doc.rust-lang.org/std/default/trait.Default.html
    ///
    /// Using this method, you can tune the parameters for embedded
    /// devices.  Note, however, that this also decreases the work
    /// factor for attackers doing dictionary attacks.
    pub fn new_iterated(hash: HashAlgorithm, approx_hash_bytes: u32)
                        -> Result<Self> {
        if approx_hash_bytes > 0x3e00000 {
            Err(Error::InvalidArgument(format!(
                "Number of bytes to hash not representable: {}",
                approx_hash_bytes)).into())
        } else {
            let mut salt = [0u8; 8];
            crate::crypto::random(&mut salt);
            Ok(S2K::Iterated {
                hash,
                salt,
                hash_bytes:
                Self::nearest_hash_count(approx_hash_bytes as usize),
            })
        }
    }

    /// Derives a key of the given size from a password.
    pub fn derive_key(&self, password: &Password, key_size: usize)
    -> Result<SessionKey> {
        #[allow(deprecated)]
        match self {
            &S2K::Simple { hash } | &S2K::Salted { hash, .. }
            | &S2K::Iterated { hash, .. } => password.map(|string| {
                let mut hash = hash.context()?;

                // If the digest length is shorter than the key length,
                // then we need to concatenate multiple hashes, each
                // preloaded with i 0s.
                let hash_sz = hash.digest_size();
                let num_contexts = (key_size + hash_sz - 1) / hash_sz;
                let mut zeros = Vec::with_capacity(num_contexts + 1);
                let mut ret = vec![0u8; key_size];

                for data in ret.chunks_mut(hash_sz) {
                    hash.update(&zeros[..]);

                    match self {
                        &S2K::Simple { .. } => {
                            hash.update(string);
                        }
                        &S2K::Salted { ref salt, .. } => {
                            hash