From a69b9dc88abe0c053dd9900426852ff3c11cacae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Duquette?= Date: Wed, 27 May 2026 13:33:50 -0400 Subject: [PATCH] feat(derivation): Document the key derivation module in the readmes --- CHANGELOG.md | 4 +++- README.md | 13 +++++++++++-- README_RUST.md | 29 +++++++++++++++++++++++++++++ 3 files changed, 43 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c775f84f..53cffd96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,9 @@ if your code depends on the iterations to stay the same : `derive_key_pbkdf2`, ` - Multiple functions, such as `generate_key` and `hash_password`, now return a `Result` due to the `rand` library upgrade. -## Added +### Added + +- Added a managed `key_derivation` module to derive `SecretKey` values from passwords and serialize the derivation parameters for later reuse. - C#: Nullable annotations were added for nullable reference types. diff --git a/README.md b/README.md index da1e91dd..279b3651 100644 --- a/README.md +++ b/README.md @@ -22,13 +22,15 @@ Note that the Javascript version of the library is compiled using WebAssembly, s # Underlying algorithms As of the current version: * Symmetric cryptography uses XChaCha20Poly1305 - * Asymmetric cryptography uses Curve25519. + * Asymmetric cryptography uses Curve25519 * Asymmetric encryption uses ECIES. * Key exchange uses x25519, or ECDH over Curve25519 + * Key derivation uses Argon2id or PBKDF2-HMAC-SHA2-256 * Password Hashing uses PBKDF2-HMAC-SHA2-256 * Secret Sharing uses Shamir Secret sharing over GF256 * Online Ciphertext uses XChaCha20-Poly1305 + # License This project is licensed under either of @@ -79,7 +81,8 @@ A Curve25519 private key from Devolutions Crypto | Share | 0x40 | A wrapped share. Used for secret sharing scheme. | | SigningKey | 0x50 | A wrapped key used to sign data. | | Signature | 0x60 | A wrapped signature. | -| OnlineCiphertext | 0x70 | A wrapped online ciphertext that can be encrypted/decrypted chunk by chunk | +| OnlineCiphertext | 0x70 | A wrapped online ciphertext that can be encrypted/decrypted chunk by chunk | +| KeyDerivation | 0x80 | Serialized key derivation parameters used to reproduce a derived secret key. | ## Sub types @@ -143,6 +146,12 @@ A Curve25519 private key from Devolutions Crypto | Latest | 0x00 | Uses the latest version. | | V1 | 0x10 | Uses version 1: ed25519. | +| Key Derivation Version | Value | Description | +|------------------------|--------|---------------------------------------------| +| Latest | 0x00 | Uses the latest version. | +| V1 | 0x10 | Uses version 1: PBKDF2-HMAC-SHA256. | +| V2 | 0x20 | Uses version 2: Argon2id. | + | Online Ciphertext Version | Value | Description | |---------------------------|--------|----------------------------------------------------------------------| | Latest | 0x00 | Uses the latest version. | diff --git a/README_RUST.md b/README_RUST.md index 3337eabd..5c52fd3c 100644 --- a/README_RUST.md +++ b/README_RUST.md @@ -11,6 +11,7 @@ Cryptographic library used in Devolutions products. It is made to be fast, easy * [Key Module](#key) * [Key Generation/Derivation](#generationderivation) * [Key Exchange](#key-exchange) +* [Key Derivation Module](#key-derivation-module) * [PasswordHash Module](#passwordhash) * [SecretSharing Module](#secretsharing) * [Signature Module](#signature) @@ -138,6 +139,33 @@ let alice_shared = mix_key_exchange(&alice_keypair.private_key, &bob_keypair.pub assert_eq!(bob_shared, alice_shared); ``` +## Key Derivation Module + +This module derives a managed `SecretKey` from a password or passphrase and returns serializable `DerivationParameters` that can be reused later to derive the same key again. + +By default, `KeyDerivationVersion::Latest` uses Argon2id. PBKDF2-HMAC-SHA256 is also available through `KeyDerivationVersion::V1`. + +```rust +use devolutions_crypto::key_derivation::{derive_key, DerivationParameters}; +use devolutions_crypto::KeyDerivationVersion; + +let password = b"a very strong password"; +let (secret_key, params) = derive_key(password, KeyDerivationVersion::Latest) + .expect("derivation should not fail"); + +let params_bytes: Vec = params.into(); +``` + +You can also select a concrete derivation algorithm directly. + +```rust +use devolutions_crypto::key_derivation::{Argon2, Pbkdf2}; + +let password = b"a very strong password"; +let (argon2_key, argon2_params) = Argon2::new().derive(password).expect("derivation should not fail"); +let (pbkdf2_key, pbkdf2_params) = Pbkdf2::new().derive(password).expect("derivation should not fail"); +``` + ## PasswordHash You can use this module to hash a password and validate it afterward. This is the recommended way to verify a user password on login. @@ -229,6 +257,7 @@ As of the current version: * Asymmetric cryptography uses Curve25519 * Asymmetric encryption uses ECIES * Key exchange uses x25519, or ECDH over Curve25519 + * Key derivation uses Argon2id by default and also supports PBKDF2-HMAC-SHA2-256 for compatibility * Password Hashing uses PBKDF2-HMAC-SHA2-256 * Secret Sharing uses Shamir Secret sharing over GF256