Skip to content

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

Update Argon2 in Rust in order to replace app-specific libs (#2159)

Leendert de Borsta35d676af5ea
diff --git a/core/rust/src/argon2/mod.rs b/core/rust/src/argon2/mod.rs
index 48d216281..e15aa2f45 100644
--- a/core/rust/src/argon2/mod.rs
+++ b/core/rust/src/argon2/mod.rs
@@ -1,82 +1,250 @@
-//! Argon2id password hashing.
-//!
-//! Derives the password hash that feeds into SRP private key derivation.
-//! Parameters must stay identical across all AliasVault clients.
+//! Argon2id key derivation.
+use serde::Deserialize;
use thiserror::Error;
-use crate::hex::bytes_to_hex;
+/// Length of every derived key in bytes; the vault format assumes a 256-bit key throughout.
+pub const ARGON2_OUTPUT_LENGTH: usize = 32;
+
+/// Default memory cost in KiB, used when the settings do not state one.
+pub const ARGON2_DEFAULT_MEMORY_KIB: u32 = 19456;
+
+/// Default number of passes, used when the settings do not state one.
+pub const ARGON2_DEFAULT_ITERATIONS: u32 = 2;
+
+/// Default number of lanes, used when the settings do not state one.
+pub const ARGON2_DEFAULT_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),
}
-/// Derive a key from a password using Argon2Id.
-///
-/// Uses the AliasVault default parameters:
-/// - Iterations: 2
-/// - Memory: 19456 KiB
-/// - Parallelism: 1
-/// - Output length: 32 bytes
+/// 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 Default for Argon2Params {
+ fn default() -> Self {
+ Self {
+ memory_kib: ARGON2_DEFAULT_MEMORY_KIB,
+ iterations: ARGON2_DEFAULT_ITERATIONS,
+ parallelism: ARGON2_DEFAULT_PARALLELISM,
+ }
+ }
+}
+
+impl Argon2Params {
+ /// Reads the `EncryptionSettings` JSON the server handed the client with its login challenge.
+ ///
+ /// A missing field falls back to the AliasVault default for that field. An empty string means
+ /// the caller has no settings at all and wants the defaults.
+ ///
+ /// # Arguments
+ /// * `settings_json` - Settings as `{"DegreeOfParallelism":1,"MemorySize":19456,"Iterations":2}`.
+ ///
+ /// # Returns
+ /// The parsed cost parameters.
+ pub fn from_settings_json(settings_json: &str) -> Result<Self, Argon2Error> {
+ let defaults = Self::default();
+ if settings_json.trim().is_empty() {
+ return Ok(defaults);
+ }
+
+ let parsed: EncryptionSettingsJson = serde_json::from_str(settings_json).map_err(|e| Argon2Error::InvalidSettings(e.to_string()))?;
+
+ Ok(Self {
+ memory_kib: parsed.memory_size.unwrap_or(defaults.memory_kib),
+ iterations: parsed.iterations.unwrap_or(defaults.iterations),
+ parallelism: parsed.degree_of_parallelism.unwrap_or(defaults.parallelism),
+ })
+ }
+}
+
+/// The `EncryptionSettings` JSON as the server stores it.
+#[derive(Deserialize)]
+struct EncryptionSettingsJson {
+ #[serde(rename = "MemorySize")]
+ memory_size: Option<u32>,
+
+ #[serde(rename = "Iterations")]
+ iterations: Option<u32>,
+
+ #[serde(rename = "DegreeOfParallelism")]
+ degree_of_parallelism: Option<u32>,
+}
+
+/// Derives a 32-byte key from a password using Argon2id with explicit cost parameters.
///
/// # Arguments
-/// * `password` - The password to hash
-/// * `salt` - Salt as a string (will be UTF-8 encoded, minimum 8 bytes)
+/// * `password` - The password bytes.
+/// * `salt` - The salt bytes, at least 8 bytes long.
+/// * `params` - The cost parameters.
///
/// # Returns
-/// Derived key as uppercase hex string (64 characters = 32 bytes)
-pub fn argon2_hash_password(password: &str, salt: &str) -> Result<String, Argon2Error> {
+/// The derived key, [`ARGON2_OUTPUT_LENGTH`] bytes long.
+pub fn argon2_derive_key(password: &[u8], salt: &[u8], params: Argon2Params) -> Result<Vec<u8>, Argon2Error> {
use argon2::{Algorithm, Argon2, Params, Version};
- // AliasVault default parameters
- let params = Params::new(
- 19456, // m_cost (memory in KiB)
- 2, // t_cost (iterations)
- 1, // p_cost (parallelism)
- Some(32), // output length
- )
- .map_err(|e| Argon2Error::InvalidParameter(format!("Invalid Argon2 params: {}", e)))?;
+ 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, params);
+ let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, argon2_params);
- let mut output = [0u8; 32];
+ let mut output = vec![0u8; ARGON2_OUTPUT_LENGTH];
argon2
- .hash_password_into(password.as_bytes(), salt.as_bytes(), &mut output)
+ .hash_password_into(password, salt, &mut output)
.map_err(|e| Argon2Error::InvalidParameter(format!("Argon2 hash failed: {}", e)))?;
- Ok(bytes_to_hex(&output))
+ Ok(output)
+}
+
+/// Derives a 32-byte key from a password using the cost parameters stated as settings JSON.
+///
+/// # Arguments
+/// * `password` - The password; hashed as its UTF-8 bytes.
+/// * `salt` - The salt; hashed as its UTF-8 bytes, at least 8 bytes long.
+/// * `settings_json` - The `EncryptionSettings` JSON, or an empty string for the defaults.
+///
+/// # Returns
+/// The derived key, [`ARGON2_OUTPUT_LENGTH`] bytes long.
+pub fn argon2_derive_key_from_settings(password: &str, salt: &str, settings_json: &str) -> Result<Vec<u8>, Argon2Error> {
+ let params = Argon2Params::from_settings_json(settings_json)?;
+ argon2_derive_key(password.as_bytes(), salt.as_bytes(), params)
}
#[cfg(test)]
mod tests {
use super::*;
+ use crate::hex::bytes_to_hex;
+
+ const PASSWORD: &str = "correct horse battery staple";
+ const SALT: &str = "somesalt12345678";
+
+ /// The parameters the E2E suite overrides accounts to, cheap enough to run in a debug build.
+ const CHEAP: Argon2Params = Argon2Params { memory_kib: 1024, iterations: 1, parallelism: 1 };
+
+ /// Known-answer vector at the E2E override parameters.
+ ///
+ /// Produced by the C reference implementation (`argon2-browser`, which the browser extension
+ /// ships) and independently by C# Konscious (which the Blazor client ships). If this ever
+ /// fails, the Rust implementation has drifted away from the other clients and no vault
+ /// written by one will open in the other.
+ #[test]
+ fn test_known_answer_cheap_params() {
+ let key = argon2_derive_key(PASSWORD.as_bytes(), SALT.as_bytes(), CHEAP).unwrap();
+ assert_eq!(bytes_to_hex(&key), "64596CFF33144564EEF5652EBB00DB5AA9B98E8FE45E87DC4718147381EEA2E4");
+ }
+
+ /// Known-answer vector at the multi-lane parameters, guarding the parallelism plumbing.
+ #[test]
+ fn test_known_answer_multiple_lanes() {
+ let params = Argon2Params { memory_kib: 2048, iterations: 2, parallelism: 4 };
+ let key = argon2_derive_key(PASSWORD.as_bytes(), SALT.as_bytes(), params).unwrap();
+ assert_eq!(bytes_to_hex(&key), "21C9EB8CEFAAEA52FA9D5D0E07F33810AFFA86AAD928A107D83554DB8DA78696");
+ }
+
+ /// Known-answer vector at the production defaults, reached through the settings JSON.
+ #[test]
+ fn test_known_answer_default_params() {
+ let key = argon2_derive_key_from_settings(PASSWORD, SALT, "").unwrap();
+ assert_eq!(bytes_to_hex(&key), "8AA6C7860B6A24C5967F6DE421AB515A7898351CA115689FFE5E88FA6FF6131C");
+ }
+
+ /// Known-answer vector at the PIN unlock parameters.
+ #[test]
+ fn test_known_answer_pin_params() {
+ let params = Argon2Params { memory_kib: 65536, iterations: 3, parallelism: 1 };
+ let key = argon2_derive_key(b"123456", b"AAAAAAAAAAAAAAAAAAAAAA==", params).unwrap();
+ assert_eq!(bytes_to_hex(&key), "94E3C74246F03BA82A02BCD0665DADB3F6569CC2565F4C2F6DEB9046EB139166");
+ }
+
+ /// The settings JSON the server actually sends must map onto the right parameters.
+ #[test]
+ fn test_settings_json_is_parsed() {
+ let params = Argon2Params::from_settings_json("{\"DegreeOfParallelism\":4,\"MemorySize\":2048,\"Iterations\":3}").unwrap();
+ assert_eq!(params, Argon2Params { memory_kib: 2048, iterations: 3, parallelism: 4 });
+ }
+
+ /// An empty settings string means "use the defaults", as does a settings object that omits a field.
#[test]
- fn test_hash_password_deterministic() {
- let hash1 = argon2_hash_password("password123", "somesalt12345678").unwrap();
- let hash2 = argon2_hash_password("password123", "somesalt12345678").unwrap();
+ fn test_settings_fall_back_per_field() {
+ assert_eq!(Argon2Params::from_settings_json("").unwrap(), Argon2Params::default());
+ assert_eq!(Argon2Params::from_settings_json("{}").unwrap(), Argon2Params::default());
- assert_eq!(hash1.len(), 64); // 32 bytes = 64 hex chars
- assert_eq!(hash1, hash2);
+ let partial = Argon2Params::from_settings_json("{\"Iterations\":5}").unwrap();
+ assert_eq!(partial.iterations, 5);
+ assert_eq!(partial.memory_kib, ARGON2_DEFAULT_MEMORY_KIB);
+ assert_eq!(partial.parallelism, ARGON2_DEFAULT_PARALLELISM);
}
+ /// Malformed settings are an error rather than a silent fall back to the defaults, so a
+ /// corrupted value can never quietly derive a different key than the account was created with.
#[test]
- fn test_hash_password_varies_with_inputs() {
- let base = argon2_hash_password("password123", "somesalt12345678").unwrap();
- let other_password = argon2_hash_password("password124", "somesalt12345678").unwrap();
- let other_salt = argon2_hash_password("password123", "somesalt12345679").unwrap();
+ fn test_malformed_settings_are_rejected() {
+ assert!(matches!(Argon2Params::from_settings_json("not json"), Err(Argon2Error::InvalidSettings(_))));
+ assert!(matches!(Argon2Params::from_settings_json("{\"MemorySize\":\"lots\"}"), Err(Argon2Error::InvalidSettings(_))));
+ }
- assert_ne!(base, other_password);
- assert_ne!(base, other_salt);
+ /// The salt is hashed as the characters of the string, never as decoded bytes.
+ #[test]
+ fn test_salt_is_hashed_as_utf8_bytes() {
+ let cheap_settings = "{\"MemorySize\":1024,\"Iterations\":1,\"DegreeOfParallelism\":1}";
+ let from_str = argon2_derive_key_from_settings("pw", "0A0B0C0D0E0F1011", cheap_settings).unwrap();
+ let from_bytes = argon2_derive_key(b"pw", b"0A0B0C0D0E0F1011", CHEAP).unwrap();
+ assert_eq!(from_str, from_bytes);
+
+ let decoded = argon2_derive_key(b"pw", &[0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10, 0x11], CHEAP).unwrap();
+ assert_ne!(from_bytes, decoded);
}
+ /// Argon2 requires a salt of at least 8 bytes.
#[test]
fn test_short_salt_fails() {
- // Argon2 requires a salt of at least 8 bytes
- let result = argon2_hash_password("password123", "short");
+ let result = argon2_derive_key(PASSWORD.as_bytes(), b"short", CHEAP);
assert!(matches!(result, Err(Argon2Error::InvalidParameter(_))));
}
+
+ /// Cost parameters outside what Argon2 accepts are reported rather than silently corrected.
+ #[test]
+ fn test_invalid_params_fail() {
+ let no_iterations = Argon2Params { memory_kib: 1024, iterations: 0, parallelism: 1 };
+ assert!(matches!(argon2_derive_key(PASSWORD.as_bytes(), SALT.as_bytes(), no_iterations), Err(Argon2Error::InvalidParameter(_))));
+
+ let too_little_memory = Argon2Params { memory_kib: 1, iterations: 1, parallelism: 1 };
+ assert!(matches!(argon2_derive_key(PASSWORD.as_bytes(), SALT.as_bytes(), too_little_memory), Err(Argon2Error::InvalidParameter(_))));
+ }
+
+ /// Different inputs must produce different keys, and identical inputs the same key.
+ #[test]
+ fn test_hash_varies_with_inputs() {
+ let base = argon2_derive_key(PASSWORD.as_bytes(), SALT.as_bytes(), CHEAP).unwrap();
+ assert_eq!(base, argon2_derive_key(PASSWORD.as_bytes(), SALT.as_bytes(), CHEAP).unwrap());
+ assert_eq!(base.len(), ARGON2_OUTPUT_LENGTH);
+
+ assert_ne!(base, argon2_derive_key(b"other password", SALT.as_bytes(), CHEAP).unwrap());
+ assert_ne!(base, argon2_derive_key(PASSWORD.as_bytes(), b"othersalt1234567", CHEAP).unwrap());
+
+ let other_params = Argon2Params { memory_kib: 1024, iterations: 2, parallelism: 1 };
+ assert_ne!(base, argon2_derive_key(PASSWORD.as_bytes(), SALT.as_bytes(), other_params).unwrap());
+ }
}
diff --git a/core/rust/src/lib.rs b/core/rust/src/lib.rs
index b4d85a60e..c2d382932 100644
--- a/core/rust/src/lib.rs
+++ b/core/rust/src/lib.rs
@@ -8,7 +8,7 @@
//! - **password_generator**: Password and passphrase (Diceware) generation
//! - **identity_generator**: Random identity (alias persona) generation
//! - **srp**: Secure Remote Password (SRP-6a) protocol for authentication
-//! - **argon2**: Argon2id password hashing
+//! - **argon2**: Argon2id key derivation
//!
//! This library accepts data as JSON and returns results as JSON.
//! Each platform (browser, iOS, Android, .NET) handles its own I/O
@@ -63,7 +63,7 @@ pub use srp::{
srp_generate_ephemeral_server, srp_derive_session_server,
SrpEphemeral, SrpSession, SrpError,
};
-pub use crate::argon2::{argon2_hash_password, Argon2Error};
+pub use crate::argon2::{argon2_derive_key, argon2_derive_key_from_settings, Argon2Error, Argon2Params};
// WASM bindings
#[cfg(feature = "wasm")]
diff --git a/core/rust/src/uniffi_api.rs b/core/rust/src/uniffi_api.rs
index c4ddc0145..6d116908e 100644
--- a/core/rust/src/uniffi_api.rs
+++ b/core/rust/src/uniffi_api.rs
@@ -335,31 +335,31 @@ pub fn vault_codec_extract_encryption_key_for_public_key(manifest_json: String,
}
// ═══════════════════════════════════════════════════════════════════════════════
-// SRP (Secure Remote Password) Functions
+// Argon2id Key Derivation Functions
// ═══════════════════════════════════════════════════════════════════════════════
-pub use crate::srp::{SrpEphemeral, SrpSession, SrpError};
+pub use crate::argon2::Argon2Error;
-/// Derive a key from a password using Argon2Id.
-///
-/// Uses the AliasVault default parameters:
-/// - Iterations: 2
-/// - Memory: 19456 KiB
-/// - Parallelism: 1
-/// - Output length: 32 bytes
+/// Derive a key from a password using Argon2id.
///
/// # Arguments
-/// * `password` - The password to hash
-/// * `salt` - Salt as a string (will be UTF-8 encoded)
+/// * `password` - The password, hashed as its UTF-8 bytes
+/// * `salt` - The salt, hashed as its UTF-8 bytes, at least 8 bytes long
+/// * `encryption_settings` - The `EncryptionSettings` JSON, or an empty string for the defaults
///
/// # Returns
-/// Derived key as uppercase hex string (64 characters = 32 bytes)
+/// The derived key as 32 bytes
#[uniffi::export]
-pub fn argon2_hash_password(password: String, salt: String) -> Result<String, SrpError> {
- crate::argon2::argon2_hash_password(&password, &salt)
- .map_err(|e| SrpError::InvalidParameter(e.to_string()))
+pub fn argon2_derive_key(password: String, salt: String, encryption_settings: String) -> Result<Vec<u8>, Argon2Error> {
+ crate::argon2::argon2_derive_key_from_settings(&password, &salt, &encryption_settings)
}
+// ═══════════════════════════════════════════════════════════════════════════════
+// SRP (Secure Remote Password) Functions
+// ═══════════════════════════════════════════════════════════════════════════════
+
+pub use crate::srp::{SrpEphemeral, SrpSession, SrpError};
+
/// Generate a cryptographic salt for SRP.
/// Returns a 32-byte random salt as an uppercase hex string.
#[uniffi::export]
diff --git a/core/rust/src/wasm.rs b/core/rust/src/wasm.rs
index ec40c925a..ecbb0110d 100644
--- a/core/rust/src/wasm.rs
+++ b/core/rust/src/wasm.rs
@@ -444,6 +444,25 @@ pub fn get_identity_age_ranges_js() -> Vec<String> {
crate::identity_generator::available_age_ranges()
}
+// ═══════════════════════════════════════════════════════════════════════════════
+// Argon2id Key Derivation WASM Bindings
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/// Derive a key from a password using Argon2id.
+///
+/// # Arguments
+/// * `password` - The password, hashed as its UTF-8 bytes
+/// * `salt` - The salt, hashed as its UTF-8 bytes, at least 8 bytes long
+/// * `encryption_settings` - The `EncryptionSettings` JSON, or an empty string for the defaults
+///
+/// # Returns
+/// The derived key as 32 bytes
+#[wasm_bindgen(js_name = argon2DeriveKey)]
+pub fn argon2_derive_key_js(password: &str, salt: &str, encryption_settings: &str) -> Result<Vec<u8>, JsValue> {
+ crate::argon2::argon2_derive_key_from_settings(password, salt, encryption_settings)
+ .map_err(|e| JsValue::from_str(&format!("Argon2 error: {}", e)))
+}
+
// ═══════════════════════════════════════════════════════════════════════════════
// SRP (Secure Remote Password) WASM Bindings
// ═══════════════════════════════════════════════════════════════════════════════