Skip to content
RFC5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF) for Node.js
JavaScript TypeScript
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
misc Updated README Jun 2, 2018
test
.eslintrc.js
.gitignore
.travis.yml
CHANGELOG.txt
Gruntfile.js
LICENSE
README.md
futoin.json Updated for release futoin-hkdf 1.2.0 Aug 1, 2019
hkdf.d.ts
hkdf.js Add TypeScript declaration file Aug 1, 2019
hkdf.test-d.ts
package.json Updated for release futoin-hkdf 1.2.0 Aug 1, 2019
yarn.lock Add TypeScript declaration file Aug 1, 2019

README.md

NPM Version NPM Downloads Build Status stable

NPM

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

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

hkdf.extract(hash, hash_len, ikm, salt) ⇒ Buffer

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)

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
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)
You can’t perform that action at this time.