Password Unlock, Derivation, and Recovery

Working case

Reviewer 47 unlocks offline notes on a shared tablet with a passphrase. The app generates a random data key for the draft collection and wraps it under a key derived from that passphrase, a 16-byte salt, and versioned derivation parameters. The server stores only the encrypted envelope for this workflow. If the reviewer changes the passphrase, the app rewraps the data key after successful unlock. If the reviewer forgets the passphrase and has no recovery factor, the notes remain unreadable; a normal account password reset cannot decrypt them by itself.

Implementation boundary

function canUnlockEnvelope(envelope, supportedVersions) {
  return envelope.saltBytes >= 16 && envelope.iterations > 0 && supportedVersions.has(envelope.kdfVersion);
}
console.log(canUnlockEnvelope({ saltBytes: 16, iterations: 240000, kdfVersion: 3 }, new Set([2, 3])));
// Output: true

Choose a supported password KDF and calibrate its work factor on target devices, recording algorithm, salt, iteration count, and version beside the wrapped key. Web Crypto supports PBKDF2; a product may use a carefully reviewed stronger password-hardening scheme through a maintained implementation if its deployment supports it. Generate salts with a secure random source and never reuse a fixed salt for every reviewer. Derive an unlock key in a secure context, unwrap only the needed data key, and clear references on logout as far as the application can. Require a deliberate recovery or no-recovery decision before storing sole-copy drafts. A server authentication password should not silently become the local encryption secret.

Cost and boundaries

A higher KDF work factor slows offline guessing but also delays every legitimate unlock. Derive once per unlock session, not per keystroke or per record. Store wrapped data keys so a passphrase change costs O(number of keys), not O(total note bytes), if the threat model permits that structure. Browser memory can still contain passphrase strings or decrypted notes beyond an application's precise control. Measure unlock time on low-end devices and document support costs for forgotten secrets. Avoid logging salts with user identifiers when that metadata is unnecessary for operations.

Failure trace

The app raises its KDF iteration count in release 29 but fails to record the old value with existing envelopes. After upgrade, every old draft appears corrupt. Another build resets the account password and tells the reviewer local encrypted notes are restored, although the old unwrap secret is gone. Reproduce both cases. Test wrong passphrase, corrupted wrapped key, missing salt, outdated parameters, browser restart during rewrap, and a device with low memory. Preserve the original envelope until the new wrapping is fully verified.

Verification

Each envelope records its KDF parameters.
Password reset does not claim to recover unavailable local keys.
Interrupted rewrap retains a readable previous envelope.

Practice drill

Create a collection key for 29 local notes and wrap it under derivation version 3. Change the passphrase and produce a new wrap without rewriting the note ciphertext. Verify the old passphrase no longer unlocks the new wrap after the change is committed, while an interrupted change can still restore the old envelope. Simulate a forgotten passphrase and show the user the stated recovery or permanent-loss path before accepting more offline-only work.

Decision note

A password unlock is a versioned key-custody system with measurable delay and an explicit loss policy.

Common Mistakes

Using a fixed salt for every account.
Changing derivation cost without versioning old envelopes.
Deriving a key for every note when a wrapped collection key suffices.

Connected practice

Build Project: encrypted local draft lifecycle and review Web Development: offline and browser-key decisions quiz.