Repository navigation
Proposal: generic key derivation function for crypto #50391
Description
What is the problem this feature will solve?
The crypto library currently lacks a generic key derivation function similar to OpenSSL's EVP_KDF methods and resembling WebCrypto's deriveKey. This proposal aims to introduce a generic key derivation function to the crypto library, enabling developers to derive keys for various cryptographic purposes with simplicity.
The current situation, with separate functions for each supported KDF, can lead to inconsistencies in the API. Each KDF function might have its unique set of parameters and usage patterns, making it challenging for developers to work seamlessly with different key derivation methods.
What is the feature you are proposing to solve the problem?
I propose the addition of a new function named kdf to the crypto library. This function will take the following parameters:
algorithm: An object specifying the key derivation algorithm to use. This object should contain information about the algorithm's name, mode, parameters, and any other necessary details, allowing developers to choose from a variety of key derivation algorithms, including those available in OpenSSL 3.0. This object is akin to the first parameter of Web Crypto'sderiveKey.baseKey: The base key from which the derived key will be generated (e.g. the password to be hashed). This base key can be of any type supported by the Crypto library, such as an ArrayBuffer, Buffer, or other relevant types.salt: A Buffer containing the salt to be used in the key derivation process, enhancing the security of the derived key.callback: An optional function to be run with the key after the derivation is complete. If undefined, run the job synchronously (as suggested by @panva).
Example Usage
Here is an example of how the crypto.kdf function might be used in Node.js:
const { kdf } = require('node:crypto');
const baseKey = 'hunter2';
const algorithm = {
name: 'scrypt',
cost: 32768,
};
/**
* Using PBKDF2 instead:
*
* const algorithm = {
* name: 'pbkdf2',
* iterations: 100000,
* digest: 'sha-512',
* };
*/
try {
const derivedKey = kdf(algorithm, baseKey, crypto.randomBytes(16));
// derivedKey is a Buffer
} catch (err) {
console.err('An error has occurred!', err);
}What alternatives have you considered?
It is possible to keep adding functions to the crypto library as new KDF algorithms are supported, but the more options there are, the more duplication there will be as apart from the parameters available, KDF functions are quite similar in interface and behavior: you pass a key and a salt and it returns a hash.
Activity
bnoordhuis commentedon Oct 25, 2023
I don't think that's a good idea - and I'm the one who introduced that pattern in the crypto module when I added
randomBytes(). Mistake in hindsight, synchronous code should stand out like a sore thumb.Also, there's a good counter example:
randomFill()vs.randomFillSync().ranisalt commentedon Oct 25, 2023
@bnoordhuis would
kdfandkdfSync, doing the obvious work, be a good option instead? I'm fine with either.How about returning a Promise? It seems to be the new standard, and there's
callbackifyfor anyone running legacy code.panva commentedon Oct 25, 2023
For the sake of consistency in the crypto module -> callbacks.
bnoordhuis commentedon Oct 25, 2023
Yes. People can call
util.promisify(...)to get a promise-based version.For the record, I'm not vehemently opposed but I'm lukewarm about introducing a general multiplexing KDF API. The thing is you're almost always interested in a single concrete KDF. Once you've picked one, you don't switch lightly.
From that perspective a general API just doesn't seem that useful, only a source of potential confusion.
khaosdoctor commentedon Oct 25, 2023
While I fully support the easiness of changing and creating different hashes using different KDFs, I also agree with @bnoordhuis on that it's going to create confusion. So I'm proposing a new approach, adding the generic KDF function internally only.
In this use case the idea would be to have a single internal entrypoint for all KDFs like @ranisalt mentioned, but we have different facades for which algorithm is supported or not. In my POV this would have the following pros:
But, on the other hand, this could (and potentially will) be a big refactor in the code base since we would need to fiddle with all the KDFs for the sake of consistency as well, but it can be done one by one after the initial implementation.
What do you think?
tniessen commentedon Oct 26, 2023
I don't disagree @bnoordhuis. However, with the current direction OpenSSL 3 is taking, I wouldn't be surprised if there were some KDFs implemented through OpenSSL providers at some point, and a generic KDF API might allow users to interface with those in Node.js, similar to how we resolve ciphers, hash functions, etc.
github-actions commentedon Apr 24, 2024
There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-staleIssues and PRs exempt from automated stale handling.
label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.
ranisalt commentedon Apr 24, 2024
If I understand it correctly, that's already how they are implemented. #50353 uses generic KDF facilities
github-actions commentedon Oct 22, 2024
There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-staleIssues and PRs exempt from automated stale handling.
label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.
ranisalt commentedon Nov 4, 2024
This may be more interesting/consistent now that
crypto.hashis a thinggithub-actions commentedon May 5, 2025
There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-staleIssues and PRs exempt from automated stale handling.
label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.
ranisalt commentedon May 5, 2025
#57824
github-actions commentedon Nov 2, 2025
There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-staleIssues and PRs exempt from automated stale handling.
label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.
github-actions commentedon Dec 2, 2025
There has been no activity on this feature request and it is being closed. If you feel closing this issue is not the right thing to do, please leave a comment.
For more information on how the project manages feature requests, please consult the feature request management document.