feat(derivation): Document the key derivation module in the readmes

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.
 

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.                                             |

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<u8> = 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