About
Node.js implementation of RFC5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF).
The implementation is fully compliant with test vectors provided in the RFC.
There are alternative modules, but they are:
- much less performing and/or
- have quite poor code quality at the moment and/or
- are not compliant with RFC (e.g. work only with string parameters) and/or
- not working with current Node.js versions and/or
- do not support arbitrary hash functions and/or
- not reliable dependency for FutoIn Security concept in general.
Standalone HKDF extract()
and expand()
actions are also available for advanced usage.
Documentation --> FutoIn Guide
Author: Andrey Galkin
Performance comparison
The figures in "derived keys per second".
- futoin-hkdf - 74 642
- fully compliant
node-hdkf
/hdkf
modules - 57 707 (~22% slower)- seems to be broken by design
- produces wrong results with RFC test vectors
ctrlpanel-hdkf
- 52 181 (~30% slower)- seems to be compliant
@stablelib/hkdf
- 39 808 (~46% slower)- seems to be compliant
Installation for Node.js
Command line:
$ npm install futoin-hkdf --save
or:
$ yarn add futoin-hkdf --save
Examples
const hkdf = require('futoin-hkdf');
// Parameter overview
//-------------------
// initial keying material
const ikm = 'string-or-buffer';
// required output length in bytes
const length = 16;
// can be empty string or false equivalent
const salt = 'strongly-encouraged';
// optional parameter
const info = 'optional-context';
// HMAC hashing algorithm to use
const hash = 'SHA-256';
// Generic derivation
//-------------------
hkdf(ikm, length, {salt, info, hash}); // Buffer(length) - derived key
hkdf(ikm, length, {salt, info, hash}).toString('hex'); // String(2*length)
// NOTE: all optional paramaters are passed in object
// With some parameters omitted
//-------------------
hkdf(ikm, length, {salt});
hkdf(ikm, length, {info});
hkdf(ikm, length, {hash});
hkdf(ikm, length);
// Advanced usage (only if you know what you are doing)
//-------------------
hkdf.hash_length(hash); // get hash_len
hkdf.extract(hash, hash_len, ikm, salt); // run only step #1
hkdf.expand(hash, hash_len. prk, length, info); // run only step #2
API documentation
Buffer
hkdf(ikm, length, salt, info, hash) ⇒ HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
Kind: global function
Returns: Buffer
- Raw buffer with derived key of @p length bytes
Param | Type | Default | Description |
---|---|---|---|
ikm | Buffer | string |
Initial Keying Material | |
length | integer |
Required byte length of output | |
salt | Buffer | string |
'' |
Optional salt (recommended) |
info | Buffer | string |
'' |
Optional context (safe to skip) |
hash | string |
"'SHA-256'" |
HMAC hash function to use |
- hkdf(ikm, length, salt, info, hash) ⇒
Buffer
- .hash_length(hash) ⇒
integer
- .extract(hash, hash_len, ikm, salt) ⇒
Buffer
- .expand(hash, hash_len, prk, length, info) ⇒
Buffer
- .hash_length(hash) ⇒
integer
hkdf.hash_length(hash) ⇒ Get expected hash length.
Kind: static method of hkdf
Returns: integer
- hash digest byte length
Note: Values are hardcoded with fallback for unknown algorithms.
Param | Type | Description |
---|---|---|
hash | string |
Hash algorithm |
Buffer
hkdf.extract(hash, hash_len, ikm, salt) ⇒ HKDF extract action.
Kind: static method of hkdf
Returns: Buffer
- A buffer with pseudorandom key
Note: Values are hardcoded with fallback for unknown algorithms.
Param | Type | Description |
---|---|---|
hash | string |
Hash algorithm |
hash_len | integer |
Hash digest length |
ikm | Buffer | string |
Initial Keying Material |
salt | Buffer | string |
Optional salt (recommended) |
Buffer
hkdf.expand(hash, hash_len, prk, length, info) ⇒ HKDF expand action.
Kind: static method of hkdf
Returns: Buffer
- A buffer with output keying material
Note: Values are hardcoded with fallback for unknown algorithms.
Param | Type | Description |
---|---|---|
hash | string |
Hash algorithm |
hash_len | integer |
Hash digest length |
prk | Buffer | string |
A buffer with pseudorandom key |
length | Buffer | string |
length of output keying material in octets |
info | Buffer | string |
Optional context (safe to skip) |