About
Node.js implementation of RFC5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF).
Additionally, it supports a HKDF-Expand-Label
variation based on RFC8446: The Transport Layer Security (TLS) Protocol Version 1.3, section 7.1. Key Schedule.
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
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)
@stablelib/hkdf
- 39 808 (~46% slower)
Installation for Node.js
Command line:
$ npm install futoin-hkdf --save
or:
$ yarn add futoin-hkdf --save
Examples
const hkdf = require('futoin-hkdf');
const ikm = 'string-or-buffer';
const length = 16;
const salt = 'strongly-encouraged';
const info = 'optional-context';
const hash = 'SHA-256';
hkdf(ikm, length, {salt, info, hash});
hkdf(ikm, length, {salt, info, hash}).toString('hex');
hkdf(ikm, length, {salt});
hkdf(ikm, length, {info});
hkdf(ikm, length, {hash});
hkdf(ikm, length);
const lhash = hash.toLowerCase().replace( '-', '' );
hkdf.hash_length(lhash);
hkdf.extract(lhash, hash_len, ikm, salt);
hkdf.expand(lhash, hash_len, prk, length, info);
const hkdf_tls = require('futoin-hkdf/tls');
const label = 'tls13 ...';
const context = Buffer.from( '' );
hkdf_tls(ikm, length, {salt, label, context, hash});
hkdf_tls.expand_label(lhash, hash_len, prk, length, label, context);
hkdf.expand(lhash, hash_len, prk, length, hkdf_tls.info(length, label, context));
API documentation
Functions
- hkdf(ikm, length, salt, info, hash) ⇒
Buffer
HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
- tls(ikm, length, salt, label, info, hash) ⇒
Buffer
TLS v1.3 HKDF-extract + HKFD-Expand-Label action
hkdf(ikm, length, salt, info, hash) ⇒ Buffer
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.hash_length(hash) ⇒ integer
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 (as in underlying Node.js crypto library) |
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 (as in underlying Node.js crypto library) |
hash_len | integer | Hash digest length |
ikm | Buffer | string | Initial Keying Material |
salt | Buffer | string | Optional salt (recommended) |
hkdf.expand(hash, hash_len, prk, length, info) ⇒ Buffer
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 (as in underlying Node.js crypto library) |
hash_len | integer | Hash digest length |
prk | Buffer | string | A buffer with pseudorandom key |
length | integer | length of output keying material in octets |
info | Buffer | string | Optional context (safe to skip) |
tls(ikm, length, salt, label, info, hash) ⇒ Buffer
TLS v1.3 HKDF-extract + HKFD-Expand-Label action
Kind: global function
Returns: Buffer
- Raw buffer with derived key of @p length bytes
Note: label and context are limited to 255 bytes!
Param | Type | Default | Description |
---|
ikm | Buffer | string | | Initial Keying Material |
length | integer | | Required byte length of output |
salt | Buffer | string | '' | Optional salt (required by fact) |
label | Buffer | string | '' | Optional label (required by fact) |
info | Buffer | string | '' | Optional context (safe to skip) |
hash | string | "'SHA-256'" | HMAC hash function to use |
tls.info(length, label, context) ⇒ Buffer
Encode HKDF context parameter in TLS v1.3 style based on RFC8446 TLS v1.3.
Kind: static method of tls
Returns: Buffer
- A buffer with encoded HKDF context
Note: label and context are limited to 255 bytes!
Param | Type | Description |
---|
length | integer | length of output keying material in octets |
label | string | ASCII label |
context | Buffer | string | Binary context or empty string |
tls.expand_label(hash, hash_len, prk, length, label, context) ⇒ Buffer
TLS-HKDF expand label action - a HKDF-Expand-Label variation based on RFC8446 TLS v1.3.
Kind: static method of tls
Returns: Buffer
- A buffer with output keying material
Note: label and context are limited to 255 bytes!
Param | Type | Description |
---|
hash | string | Hash algorithm (as in underlying Node.js crypto library) |
hash_len | integer | Hash digest length |
prk | Buffer | string | A buffer with pseudorandom key |
length | integer | length of output keying material in octets |
label | string | ASCII label |
context | Buffer | string | Binary context or empty string |