Update "Improper Key Derivation Functions" in 0x04g-Testing-Cryptography.md

[cpholguera]

@sydseter proposed changes to "Improper Key Derivation Functions" in 0x04g-Testing-Cryptography.md in #3199 which are captured here for now so that they can be part of a new separate PR.

### Improper Key Derivation Functions

When discussing key derivation functions (KDFs) in the context of mobile applications, we are usually referring to cryptographic key derivation rather than password storage. This chapter focuses primarily on KDF in the context of cryptographic key derivation, rather than password storage. For general advice on password storage, please refer to the [OWASP Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html).
KDFs derive bytes suitable for cryptographic operations from passwords or other data sources using a pseudorandom function (PRF).

Different KDFs are suitable for different tasks such as:

- Cryptographic key derivation:
    - Together with a non-secret parameter to derive one or more keys from a common secret value. Also known as known as "key diversification"
    - As components of multiparty key-agreement protocols (e.g: [KDF1](https://en.wikipedia.org/wiki/IEEE_P1363)).
    - To derive keys from secret passwords or passphrases.
    - To derive keys of different length from the ones provided (e.g: [PBKDF2HMAC](https://en.wikipedia.org/wiki/PBKDF2) or [HKDF](https://en.wikipedia.org/wiki/HKDF)).
    - [Key stretching](https://en.wikipedia.org/wiki/Key_stretching) and [key strengthening](https://en.wikipedia.org/wiki/Key_derivation_function#Key_stretching_and_key_strengthening).

- Password storage:
    - In order to ensure attacker's can't use a stolen password even in the event of a data breach, passwords are stored as hashes computed through a computationally intensive KDF. The ideal password storage's KDF should be demanding on both computational and memory resources.

Source: ([Wikipedia, 2025.02.21"](https://en.wikipedia.org/wiki/Key_derivation_function "Key derivation function"))

When using a KDF for cryptographic operations always ensure to use a recommended and approved KDF properly according to the latest recommendations and the software provider's documentation. E.g Only using a key derivation functions that is constructed from hashes against which no non-trivial pre-image or length-extension attacks are known and where attacking the key derivation function directly is infeasible. Using user-supplied input together with HKDF will make it easy for password crackers to execute a preimage attack.

Choose a KDF that use an adaptive hash function that can be configured to change the amount of computational effort needed to compute the hash, such as the number of iterations ("stretching") or the amount of memory required. Some hash functions perform salting automatically. These functions can significantly increase the overhead for a brute force attack compared to intentionally-fast functions. For example, rainbow table attacks can become infeasible due to the high computing overhead. Finally, since computing power gets faster and cheaper over time, the technique can be reconfigured to increase the workload without forcing an entire replacement of the algorithm in use.

Some hash functions that have one or more of these desired properties include [scrypt](https://www.tarsnap.com/scrypt.html), and [PBKDF2](https://www.rfc-editor.org/rfc/rfc2898). While there is active debate about which of these is the most effective, they are all stronger than using salts with hash functions with very little computing overhead.

Note that using these functions can have an impact on performance, so they require special consideration to avoid denial-of-service attacks. However, their configurability provides finer control over how much CPU and memory is used, so it could be adjusted to suit the environment's needs. In the case where CPU and memory performance is a challenge try adjusting desired bit-length of the derived key instead of increasing the iteration account (e.g using HMAC-SHA512 instead of HMAC-SHA256). This might make the KDF more susceptible by brute-force attacks, but should be acceptable as long as you keep yourself within recommended guidelines.

Unfortunately, "brute-force" attacks are quite liable to succeed where users selects passwords and pins with none or with too little entropy than what is required for cryptographic keys. Therefore, ensure that passwords and pins aren't directly passed into a HKDF. The key that is input to a key-derivation function is called a key-derivation key (KDK). A KDK **shall** be a cryptographic key, but the KDK used as an input to a recommended key-derivation functions can, for example, be generated by an approved cryptographic random bit generator, e.g. by a deterministic random bit generator (see: [NIST 800-108, rev 1](https://csrc.nist.gov/pubs/sp/800/108/r1/upd1/final "NIST: Recommendation for Key Derivation Using Pseudorandom Functions")) ([NIST, 2022](https://csrc.nist.gov/pubs/sp/800/108/r1/upd1/final "NIST: Recommendation for Key Derivation Using Pseudorandom Functions")).
In cases where the input is user-controlled, use password hashing algorithm like Argon2, scrypt, bcrypt or PBKDF2 as a key derivation function to provide a sufficient level of computational effort.
When using a password hashing algorithm as a KDF, also ensure to choose an appropriate iteration count that can provide sufficient computational efforts. Meaning that they make password or secret cracking attacks infeasible or expensive. For example, [NIST recommends an iteration count of at least 10,000 for PBKDF2](https://pages.nist.gov/800-63-3/sp800-63b.html#sec5 "NIST Special Publication 800-63B") and [for critical keys where user-perceived performance is not critical at least 10,000,000](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf "NIST Special Publication 800-132"). For critical keys, it is recommended to implementation algorithms recognized by [Password Hashing Competition (PHC)](https://password-hashing.net/ "PHC") like [Argon2](https://github.com/p-h-c/phc-winner-argon2 "Argon2"). Also see ["OWASP Password Storage Cheat Sheet"](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#introduction "OWASP Cheat Sheet Series: Password Storage Cheat Sheet") for recommendation on iteration count when using key derivation functions using Argon2, scrypt, bcrypt or PBKDF2.

[Prasad-JB]

Thanks for capturing and consolidating these changes. The separation between cryptographic key derivation and password storage is much clearer now.

A couple of points that might help strengthen this section before it goes into a PR:

PBKDF2 is mentioned under both cryptographic key derivation and password storage. Maybe clarify that while it’s primarily used for password hashing, it can also be acceptable in certain cryptographic contexts when properly configured.

The performance trade-off section is very useful. Adding a short example configuration for Argon2 (e.g., memory cost, iterations, parallelism) or pointing to NIST/OWASP guidance could give implementers something more concrete.

Since HKDF misuse is common, a short “Do / Don’t” example would be a nice touch (e.g., don’t feed user passwords directly into HKDF, do use Argon2/scrypt/bcrypt first).

Overall, this looks solid and much more actionable for developers

[sydseter]

Thanks for capturing and consolidating these changes. The separation between cryptographic key derivation and password storage is much clearer now.

A couple of points that might help strengthen this section before it goes into a PR:

PBKDF2 is mentioned under both cryptographic key derivation and password storage. Maybe clarify that while it’s primarily used for password hashing, it can also be acceptable in certain cryptographic contexts when properly configured.

I am not sure whether password hashing is what key derivation is "primarily" used for. Hard to say, really. Both "key stretching", "key diversification", and using it as a component in multiparty key-agreement protocols, "Diffie-Hellman Key Exchange" are everyday use cases. I argue that key diversification and key stretching are the most common use cases in mobile cryptography, but I don't have any evidence to support that claim.

The performance trade-off section is very useful. Adding a short example configuration for Argon2 (e.g., memory cost, iterations, parallelism) or pointing to NIST/OWASP guidance could give implementers something more concrete.

Already mentioned in

mastg/Document/0x04g-Testing-Cryptography.md

Line 148 in 1d87380

When using a password hashing algorithm as a KDF, also ensure to choose an appropriate iteration count that can provide sufficient computational efforts. Meaning that they make password or secret cracking attacks infeasible or expensive. For example, [NIST recommends an iteration count of at least 10,000 for PBKDF2](https://pages.nist.gov/800-63-3/sp800-63b.html#sec5 "NIST Special Publication 800-63B") and [for critical keys where user-perceived performance is not critical at least 10,000,000](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf "NIST Special Publication 800-132"). For critical keys, it is recommended to implementation algorithms recognized by [Password Hashing Competition (PHC)](https://password-hashing.net/ "PHC") like [Argon2](https://github.com/p-h-c/phc-winner-argon2 "Argon2"). Also see ["OWASP Password Storage Cheat Sheet"](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#introduction "OWASP Cheat Sheet Series: Password Storage Cheat Sheet") for recommendation on iteration count when using key derivation functions using Argon2, scrypt, bcrypt or PBKDF2.

Since HKDF misuse is common, a short “Do / Don’t” example would be a nice touch (e.g., don’t feed user passwords directly into HKDF, do use Argon2/scrypt/bcrypt first).

Shouldn't that be part of the MASWE? See: https://github.com/OWASP/maswe/pull/1/files

Overall, this looks solid and much more actionable for developers

[Prasad-JB]

Thanks for the detailed clarifications! I get your point about it being tricky to say what KDFs are “primarily” used for without solid evidence - the examples around key diversification and stretching in mobile crypto definitely make sense.

On the HKDF misuse part, linking out to MASWE sounds like a good way to avoid duplication, but I still think even a short reference here (like “see MASWE for misuse examples”) would help developers who only come across this doc.

Another idea: since people often get stuck deciding when to use HKDF vs Argon2/scrypt/PBKDF2, maybe a short decision note could help (e.g. “password-based => Argon2/scrypt; key-based => HKDF”). It doesn’t need to be a full section, but it would make the guidance more actionable.

Overall, this section is looking really strong - the separation and added references make it much clearer than before.

[sydseter]

Added clarification regarding HKDF and Password based KDF: ea4cba8#diff-8f551893e4dae6b53af43cc3114bfa38065f623e122f9e1974c2e01c25880584R147

If the input is user-controlled, a password hashing algorithm like Argon2, scrypt, bcrypt, or PBKDF2 is used as a key derivation function to provide sufficient computational effort. Do not use an HKDF or any other integrity-based hashing algorithm like MD5, SHA-1, SHA-2, or SHA-3 for this purpose. HKDFs, like SHA-3, aren't designed for low-entropy inputs. In the context of key derivation, these should only be used for key stretching or key diversification of randomly generated keys.

[Prasad-JB]

Looks great now, the HKDF vs password-based KDF clarification really nails the distinction. This feels actionable and ready to go into the main PR.