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).

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
  • 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)
//-------------------

// As in underlying Node.js crypto library
const lhash = hash.toLowerCase().replace( '-', '' ); // 'sha256'

hkdf.hash_length(lhash); // get hash_len
hkdf.extract(lhash, hash_len, ikm, salt); // run only step #1
hkdf.expand(lhash, hash_len, prk, length, info); // run only step #2

// TLS v1.3+
//-------------------
const hkdf_tls = require('futoin-hkdf/tls');

const label = 'tls13 ...';
const context = Buffer.from( /* E.g some binary hash generation */ '' );

hkdf_tls(ikm, length, {salt, label, context, hash}); // Buffer(length) - derived key

// Advanced usage
hkdf_tls.expand_label(lhash, hash_len, prk, length, label, context);

// Same as:
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(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 (as in underlying Node.js crypto library)

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 (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(ikm, length, salt, label, info, hash) ⇒ Buffer
  • .info(length, label, context) ⇒ Buffer
  • .expand_label(hash, hash_len, prk, length, label, context) ⇒ Buffer

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