feat(derivation): Add a key derivation module

[Sébastien Duquette (sduquette-devolutions)]

This change introduces a new key_derivation module that provides a managed API for deriving a SecretKey from a password or passphrase. The module exposes two high-level builders, Pbkdf2 and Argon2, each returning both the derived SecretKey and a serializable DerivationParameters struct that can be stored and reused to reproduce the same derivation. Two versioned implementations back the module: KeyDerivationV1 using PBKDF2-HMAC-SHA256 and KeyDerivationV2 using Argon2id via the existing Argon2Parameters type.

New KeyDerivation (subtype 8) and KeyDerivationVersion / KeyDerivationSubtype enum variants are added to the headers. Conformity tests for both PBKDF2 and Argon2id derivation are added to tests/conformity.rs.

The lib.rs documentation is updated to reflect the new module alongside reworked symmetric encryption examples that use encrypt_with_secret_key and SecretKey instead of raw byte slices.

The CLI is updated to remove the --length option from generate and derive-key commands, replacing the raw byte output with structured Key and DerivationParameters base64 output, and adding a detect_dc_type helper for friendlier error messages.

[Copilot]

Pull request overview

Adds a new managed key-derivation API to devolutions_crypto, including serializable derivation parameter blobs (with headers/versioning) and CLI support for emitting/consuming these structured types.

Changes:

• Introduces src/key_derivation with Pbkdf2 (V1) and Argon2 (V2/Latest) builders returning (SecretKey, DerivationParameters).
• Extends the header/type system with DataType::KeyDerivation + KeyDerivationVersion/KeyDerivationSubtype, and updates utils::validate_header accordingly.
• Updates documentation/tests and refreshes the CLI to output structured keys/parameters and provide friendlier type-mismatch errors.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/conformity.rs	Adds conformity tests covering the new managed PBKDF2/Argon2 derivation builders.
src/utils.rs	Extends validate_header to recognize KeyDerivation and updates rustdoc snippets/links.
src/lib.rs	Documents the new key_derivation module and updates symmetric encryption examples to use SecretKey.
src/key/mod.rs	Adds an internal helper to construct SecretKey from raw derived bytes with zeroization.
src/key_derivation/mod.rs	New module wiring: DerivationParameters type + version dispatch + unit tests.
src/key_derivation/key_derivation_v1.rs	PBKDF2-HMAC-SHA256 (V1) implementation and builder API.
src/key_derivation/key_derivation_v2.rs	Argon2id (V2) implementation and builder API.
src/enums.rs	Adds DataType::KeyDerivation and new version/subtype enums for derivation headers.
cli/src/main.rs	Updates CLI commands to use SecretKey + DerivationParameters outputs and adds header-based type detection.

Comments suppressed due to low confidence (2)

src/lib.rs:233

• Typo in docs: "PKBDF2" should be "PBKDF2" (algorithm list).

//!  * Asymmetric cryptography uses Curve25519.
//!  * Asymmetric encryption uses ECIES.
//!  * Key derivation uses Argon2 or PKBDF2
//!  * Key exchange uses x25519, or ECDH over Curve25519
//!  * Password Hashing uses PBKDF2-HMAC-SHA2-256

src/utils.rs:101

• The validate_header rustdoc "Example" section is currently not a valid, copy-pastable snippet: it isn't wrapped in a fenced code block and contains invalid Rust (backticks inside a type annotation, key is a Result that isn't unwrapped, and the assert! calls are missing closing parentheses). Please wrap it in a proper code block and fix the snippet so it compiles and reflects the current encryption API.

/// let ciphertext: `Vec<u8>` = encrypt(b"test", &key, CiphertextVersion::Latest).unwrap().into();
///
/// assert!(validate_header(&ciphertext, DataType::Ciphertext);
/// assert!(!validate_header(&ciphertext, DataType::PasswordHash);
/// assert!(!validate_header(&key, DataType::Ciphertext);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.