Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

3.4 KB
Raw Blame
//! Argon2id key derivation.

use serde::Deserialize;
use thiserror::Error;
use zeroize::Zeroizing;

/// Length of every derived key in bytes; the vault format assumes a 256-bit key throughout.
const ARGON2_OUTPUT_LENGTH: usize = 32;

/*
 * The weakest Argon2id parameters a client accepts from the server, to prevent a KDF downgrade by the server. They match the
 * defaults of the first public release (0.9.0). Clients from 0.32.0 upgrade older accounts at login, so this floor can be
 * raised once all users run 0.32.0+.
 */
const MIN_MEMORY_KIB: u32 = 19456;
const MIN_ITERATIONS: u32 = 2;
const MIN_PARALLELISM: u32 = 1;

/// Argon2-related errors.
#[derive(Error, Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Error))]
#[cfg_attr(feature = "uniffi", uniffi(flat_error))]
pub enum Argon2Error {
    /// The encryption settings JSON could not be read.
    #[error("Invalid encryption settings: {0}")]
    InvalidSettings(String),

    /// The cost parameters were rejected by the Argon2 implementation.
    #[error("Invalid parameter: {0}")]
    InvalidParameter(String),
}

/// Argon2id cost parameters, matching the `EncryptionSettings` the server stores per account.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Argon2Params {
    /// Memory cost in KiB (`MemorySize` in the settings JSON).
    pub memory_kib: u32,

    /// Number of passes over memory (`Iterations` in the settings JSON).
    pub iterations: u32,

    /// Number of lanes (`DegreeOfParallelism` in the settings JSON).
    pub parallelism: u32,
}

impl Argon2Params {
    /// The cost parameters from the server's `EncryptionSettings` JSON
    /// (`{"DegreeOfParallelism":1,"MemorySize":65536,"Iterations":5}`); every field is required.
    pub fn from_settings_json(settings_json: &str) -> Result<Self, Argon2Error> {
        let parsed: EncryptionSettingsJson = serde_json::from_str(settings_json).map_err(|e| Argon2Error::InvalidSettings(e.to_string()))?;

        Ok(Self { memory_kib: parsed.memory_size, iterations: parsed.iterations, parallelism: parsed.degree_of_parallelism })
    }
}

/// The `EncryptionSettings` JSON as the server stores it.
#[derive(Deserialize)]
struct EncryptionSettingsJson {
    #[serde(rename = "MemorySize")]
    memory_size: u32,

    #[serde(rename = "Iterations")]
    iterations: u32,

    #[serde(rename = "DegreeOfParallelism")]
    degree_of_parallelism: u32,
}

/// Derive a 32-byte key from a password with Argon2id under explicit cost parameters; the salt is at least 8 bytes.
pub fn argon2_derive_key(password: &[u8], salt: &[u8], params: Argon2Params) -> Result<Zeroizing<Vec<u8>>, Argon2Error> {
    use argon2::{Algorithm, Argon2, Params, Version};

    if params.memory_kib < MIN_MEMORY_KIB || params.iterations < MIN_ITERATIONS || params.parallelism < MIN_PARALLELISM {
        return Err(Argon2Error::InvalidParameter(format!("Argon2 params below the minimum: {:?}", params)));
    }

    let argon2_params = Params::new(params.memory_kib, params.iterations, params.parallelism, Some(ARGON2_OUTPUT_LENGTH))
        .map_err(|e| Argon2Error::InvalidParameter(format!("Invalid Argon2 params: {}", e)))?;

    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, argon2_params);

    let mut output = Zeroizing::new(vec![0u8; ARGON2_OUTPUT_LENGTH]);
    argon2
        .hash_password_into(password, salt, &mut output[..])
        .map_err(|e| Argon2Error::InvalidParameter(format!("Argon2 hash failed: {}", e)))?;

    Ok(output)
}