feat: configurable default KDF type for new user registrations #42

New Issue

MrUnknownDE · 2026-04-05T20:29:03+02:00

MrUnknownDE commented

2026-04-05 20:29:03 +02:00

Originally created by @dnplkndll on 3/21/2026

Summary

Adds CLIENT_KDF_TYPE, CLIENT_KDF_ITERATIONS, CLIENT_KDF_MEMORY, and CLIENT_KDF_PARALLELISM environment variables to allow server admins to configure the default KDF for new user registrations.

Closes #6982

Motivation

The default KDF is currently hardcoded to PBKDF2 with 600,000 iterations. Argon2id is memory-hard and significantly more resistant to GPU-based brute-force attacks, but admins have no way to set it as the default without modifying source code. This is particularly important for self-hosted family/team instances where users are unlikely to change their KDF settings manually.

Changes

src/config.rs — Add 4 config entries with input validation matching existing Argon2id parameter validation
src/db/models/user.rs — Replace hardcoded CLIENT_KDF_TYPE_DEFAULT / CLIENT_KDF_ITER_DEFAULT constants with config-backed functions. Automatically uses sensible Argon2id defaults (3 iterations, 64MB, 4 parallelism) when CLIENT_KDF_TYPE=1
src/api/core/accounts.rs — Use config values for prelogin response when email is not found (previously hardcoded to PBKDF2)
.env.template — Document new variables

Backwards Compatibility

Default values produce identical behavior to current hardcoded constants
Existing users are not affected — only new account creation and the prelogin response for unknown emails

Testing

Tested on a self-hosted instance with CLIENT_KDF_TYPE=1:

Prelogin endpoint returns {"kdf": 1, "kdfIterations": 3, "kdfMemory": 64, "kdfParallelism": 4} for unknown emails
New account registration creates accounts with Argon2id KDF
Existing accounts retain their current KDF settings
Validation rejects invalid parameters (e.g., memory < 15MB, parallelism > 16)

Example

CLIENT_KDF_TYPE=1

That's it — sensible Argon2id defaults are applied automatically.

*Originally created by @dnplkndll on 3/21/2026* ## Summary Adds `CLIENT_KDF_TYPE`, `CLIENT_KDF_ITERATIONS`, `CLIENT_KDF_MEMORY`, and `CLIENT_KDF_PARALLELISM` environment variables to allow server admins to configure the default KDF for new user registrations. Closes #6982 ## Motivation The default KDF is currently hardcoded to PBKDF2 with 600,000 iterations. Argon2id is memory-hard and significantly more resistant to GPU-based brute-force attacks, but admins have no way to set it as the default without modifying source code. This is particularly important for self-hosted family/team instances where users are unlikely to change their KDF settings manually. ## Changes - **`src/config.rs`** — Add 4 config entries with input validation matching existing Argon2id parameter validation - **`src/db/models/user.rs`** — Replace hardcoded `CLIENT_KDF_TYPE_DEFAULT` / `CLIENT_KDF_ITER_DEFAULT` constants with config-backed functions. Automatically uses sensible Argon2id defaults (3 iterations, 64MB, 4 parallelism) when `CLIENT_KDF_TYPE=1` - **`src/api/core/accounts.rs`** — Use config values for prelogin response when email is not found (previously hardcoded to PBKDF2) - **`.env.template`** — Document new variables ## Backwards Compatibility - Default values produce identical behavior to current hardcoded constants - Existing users are not affected — only new account creation and the prelogin response for unknown emails ## Testing Tested on a self-hosted instance with `CLIENT_KDF_TYPE=1`: - Prelogin endpoint returns `{"kdf": 1, "kdfIterations": 3, "kdfMemory": 64, "kdfParallelism": 4}` for unknown emails - New account registration creates accounts with Argon2id KDF - Existing accounts retain their current KDF settings - Validation rejects invalid parameters (e.g., memory < 15MB, parallelism > 16) ## Example ```env CLIENT_KDF_TYPE=1 ``` That's it — sensible Argon2id defaults are applied automatically.

Sign in to join this conversation.

No Label

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/vaultwarden#42