futoin-hkdf

What is futoin-hkdf?

The futoin-hkdf npm package is a JavaScript implementation of the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869. It is used to derive one or more cryptographic keys from a source key material in a secure manner.

What are futoin-hkdf's main functionalities?

Basic HKDF Derivation

This code demonstrates the basic usage of the futoin-hkdf package to derive a cryptographic key from initial keying material (IKM) using optional salt and info parameters.

const hkdf = require('futoin-hkdf');
const crypto = require('crypto');

const ikm = crypto.randomBytes(32); // Initial Keying Material
const salt = crypto.randomBytes(16); // Optional salt
const info = Buffer.from('info'); // Optional context and application specific information
const length = 32; // Length of the derived key
const hash = 'sha256'; // Hash function to use

const derivedKey = hkdf(ikm, length, { salt, info, hash });
console.log(derivedKey.toString('hex'));

HKDF with Different Hash Functions

This code demonstrates how to use different hash functions (SHA-512 and SHA-1) with the futoin-hkdf package to derive cryptographic keys.

const hkdf = require('futoin-hkdf');
const crypto = require('crypto');

const ikm = crypto.randomBytes(32); // Initial Keying Material
const salt = crypto.randomBytes(16); // Optional salt
const info = Buffer.from('info'); // Optional context and application specific information
const length = 32; // Length of the derived key

// Using SHA-512 hash function
const derivedKeySHA512 = hkdf(ikm, length, { salt, info, hash: 'sha512' });
console.log(derivedKeySHA512.toString('hex'));

// Using SHA-1 hash function
const derivedKeySHA1 = hkdf(ikm, length, { salt, info, hash: 'sha1' });
console.log(derivedKeySHA1.toString('hex'));

Other packages similar to futoin-hkdf

futoin-hkdf

The futoin-hkdf package is a JavaScript implementation of the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869. It is used to derive one or more cryptographic keys from a source key material in a secure manner.

crypto

The crypto module in Node.js provides cryptographic functionality that includes a set of wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions. It includes an implementation of HKDF, but it is more general-purpose and not as focused on HKDF as futoin-hkdf.

hkdf

The hkdf package is another implementation of the HKDF algorithm in JavaScript. It provides similar functionality to futoin-hkdf but with a different API. It is also focused solely on HKDF and provides a simple and straightforward interface for key derivation.

README

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(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

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)