Nine Pomeranian Monsters

futoin-hkdf

1.0.2 • Public • Published

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 Buffer | string length of output keying material in octets
info Buffer | string Optional context (safe to skip)

install

npm i futoin-hkdf

Downloadsweekly downloads

68

version

1.0.2

license

Apache-2.0

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability