crypto: add a generic MAC API

[panva]

Add getMacs() and createMac() to node:crypto as a layer on top of OpenSSL EVP_MAC. Support incremental and streaming operations with provider parameter validation and configurable output sizes.

import { createMac, getMacs, randomBytes } from 'node:crypto';

console.log(getMacs());
// [
//   'blake2bmac', 'blake2smac',
//   'cmac',       'gmac',
//   'hmac',       'kmac-128',
//   'kmac-256',   'kmac128',
//   'kmac256',    'poly1305',
//   'siphash'
// ]

const key = randomBytes(16);
const mac = createMac('CMAC', key, {
  cipher: 'AES-128-CBC',
});

mac.update('some data to authenticate');
console.log(mac.final('hex'));
// 326190b586621ebd6bcb2955c456794d

Refs: #32433
Refs: #40921
Refs: #48314
Refs: #32448
Refs: #32477

Possible followups:

• mac.copy([options]) to get a new Mac instance with a copied state, not for GMAC and Poly1305
• crypto.mac(algorithm, key, data[, options]) one-shot akin to crypto.hash()

[nodejs-github-bot]

Review requested:

• @nodejs/crypto
• @nodejs/gyp
• @nodejs/performance
• @nodejs/security-wg

[gurgunday]

lgtm

[panva]

Compared createMac('HMAC', key, { digest: 'SHA256' }) against createHmac('SHA256', key), i.e. 🍏s to 🍏s, using the same binary, a 32-byte key, and 30 interleaved runs. Positive improvement favors createMac().

Operation	Length	Iterations	Confidence	Improvement	Accuracy (*)	(**)	(***)
constructor	0	100,000	***	+13.50%	±1.73%	±2.30%	±3.00%
empty lifecycle	0	250,000	***	+12.35%	±1.82%	±2.43%	±3.18%
lifecycle	0	250,000	***	+14.10%	±1.56%	±2.08%	±2.71%
lifecycle	64	250,000	***	+13.79%	±1.53%	±2.04%	±2.66%
lifecycle	4,096	100,000	***	+5.86%	±1.41%	±1.88%	±2.46%
stream lifecycle	0	100,000	***	+6.56%	±1.44%	±1.92%	±2.50%
stream lifecycle	64	100,000	***	+6.73%	±1.83%	±2.43%	±3.17%
stream lifecycle	4,096	100,000	***	+3.29%	±1.33%	±1.77%	±2.30%
update	64	5,000,000	***	+35.86%	±1.29%	±1.72%	±2.24%
final (Buffer)	64	50,000		-0.36%	±2.08%	±2.77%	±3.61%
final (hex)	64	50,000	***	-13.11%	±1.72%	±2.28%	±2.97%

benchmark/crypto/mac-api-compare.js

'use strict';

const common = require('../common.js');
const assert = require('node:assert');
const {
  createHmac,
  createMac,
} = require('node:crypto');

const implementation = process.env.NODE_MAC_COMPARE_IMPLEMENTATION;
assert(['createHmac', 'createMac'].includes(implementation));

const useMac = implementation === 'createMac';
const key = Buffer.alloc(32, 0x42);
const macOptions = { digest: 'SHA256' };

const bench = common.createBenchmark(main, {
  operation: [
    'constructor',
    'empty-lifecycle',
    'lifecycle',
    'stream-lifecycle',
    'update',
    'final-buffer',
    'final-hex',
  ],
  length: [0, 64, 4096],
  n: [50_000, 100_000, 250_000, 5_000_000],
}, {
  combinationFilter({ operation, length, n }) {
    if (operation === 'constructor')
      return length === 0 && n === 100_000;
    if (operation === 'empty-lifecycle')
      return length === 0 && n === 250_000;
    if (operation === 'lifecycle')
      return n === (length === 4096 ? 100_000 : 250_000);
    if (operation === 'stream-lifecycle')
      return n === 100_000;
    if (operation === 'update')
      return length === 64 && n === 5_000_000;
    if (operation === 'final-buffer' || operation === 'final-hex')
      return length === 64 && n === 50_000;
    return false;
  },
});

function main({ operation, length, n }) {
  const data = Buffer.alloc(length, 0x61);

  switch (operation) {
    case 'constructor':
      measureConstructor(n);
      break;
    case 'empty-lifecycle':
      measureEmptyLifecycle(n);
      break;
    case 'lifecycle':
      measureLifecycle(data, n);
      break;
    case 'stream-lifecycle':
      measureStreamLifecycle(data, n);
      break;
    case 'update':
      measureUpdate(data, n);
      break;
    case 'final-buffer':
      measureFinal(data, n);
      break;
    case 'final-hex':
      measureFinal(data, n, 'hex');
      break;
  }
}

function measureConstructor(n) {
  const contexts = new Array(n);

  if (useMac) {
    createMac('HMAC', key, macOptions).final();
    bench.start();
    for (let i = 0; i < n; ++i)
      contexts[i] = createMac('HMAC', key, macOptions);
  } else {
    createHmac('SHA256', key).digest();
    bench.start();
    for (let i = 0; i < n; ++i)
      contexts[i] = createHmac('SHA256', key);
  }

  bench.end(n);
  assert.strictEqual(typeof contexts[n - 1], 'object');
}

function measureEmptyLifecycle(n) {
  let result;

  if (useMac) {
    createMac('HMAC', key, macOptions).final();
    bench.start();
    for (let i = 0; i < n; ++i)
      result = createMac('HMAC', key, macOptions).final();
  } else {
    createHmac('SHA256', key).digest();
    bench.start();
    for (let i = 0; i < n; ++i)
      result = createHmac('SHA256', key).digest();
  }

  bench.end(n);
  assert(Buffer.isBuffer(result));
}

function measureLifecycle(data, n) {
  let result;

  if (useMac) {
    createMac('HMAC', key, macOptions).update(data).final();
    bench.start();
    for (let i = 0; i < n; ++i)
      result = createMac('HMAC', key, macOptions).update(data).final();
  } else {
    createHmac('SHA256', key).update(data).digest();
    bench.start();
    for (let i = 0; i < n; ++i)
      result = createHmac('SHA256', key).update(data).digest();
  }

  bench.end(n);
  assert(Buffer.isBuffer(result));
}

function measureStreamLifecycle(data, n) {
  let result;

  if (useMac) {
    const warmup = createMac('HMAC', key, macOptions);
    warmup.end(data);
    warmup.read();

    bench.start();
    for (let i = 0; i < n; ++i) {
      const context = createMac('HMAC', key, macOptions);
      context.end(data);
      result = context.read();
    }
  } else {
    const warmup = createHmac('SHA256', key);
    warmup.end(data);
    warmup.read();

    bench.start();
    for (let i = 0; i < n; ++i) {
      const context = createHmac('SHA256', key);
      context.end(data);
      result = context.read();
    }
  }

  bench.end(n);
  assert(Buffer.isBuffer(result));
}

function measureUpdate(data, n) {
  if (useMac) {
    const warmup = createMac('HMAC', key, macOptions);
    warmup.update(data).final();

    const context = createMac('HMAC', key, macOptions);
    bench.start();
    for (let i = 0; i < n; ++i)
      context.update(data);
    bench.end(n);

    assert(Buffer.isBuffer(context.final()));
  } else {
    const warmup = createHmac('SHA256', key);
    warmup.update(data).digest();

    const context = createHmac('SHA256', key);
    bench.start();
    for (let i = 0; i < n; ++i)
      context.update(data);
    bench.end(n);

    assert(Buffer.isBuffer(context.digest()));
  }
}

function measureFinal(data, n, encoding) {
  const contexts = new Array(n);
  let result;

  if (useMac) {
    for (let i = 0; i < n; ++i)
      contexts[i] = createMac('HMAC', key, macOptions).update(data);

    bench.start();
    for (let i = 0; i < n; ++i)
      result = contexts[i].final(encoding);
  } else {
    for (let i = 0; i < n; ++i)
      contexts[i] = createHmac('SHA256', key).update(data);

    bench.start();
    for (let i = 0; i < n; ++i)
      result = contexts[i].digest(encoding);
  }

  bench.end(n);

  if (encoding === undefined)
    assert(Buffer.isBuffer(result));
  else
    assert.strictEqual(typeof result, 'string');
}

                                                                             confidence   improvement   accuracy (*)    (**)   (***)
crypto/mac-api-compare.js n=100000 length=0 operation='constructor'          ***            +13.50 %   ±1.73%  ±2.30%  ±3.00%
crypto/mac-api-compare.js n=250000 length=0 operation='empty-lifecycle'      ***            +12.35 %   ±1.82%  ±2.43%  ±3.18%
crypto/mac-api-compare.js n=250000 length=0 operation='lifecycle'            ***            +14.10 %   ±1.56%  ±2.08%  ±2.71%
crypto/mac-api-compare.js n=250000 length=64 operation='lifecycle'           ***            +13.79 %   ±1.53%  ±2.04%  ±2.66%
crypto/mac-api-compare.js n=100000 length=4096 operation='lifecycle'         ***             +5.86 %   ±1.41%  ±1.88%  ±2.46%
crypto/mac-api-compare.js n=100000 length=0 operation='stream-lifecycle'     ***             +6.56 %   ±1.44%  ±1.92%  ±2.50%
crypto/mac-api-compare.js n=100000 length=64 operation='stream-lifecycle'    ***             +6.73 %   ±1.83%  ±2.43%  ±3.17%
crypto/mac-api-compare.js n=100000 length=4096 operation='stream-lifecycle'  ***             +3.29 %   ±1.33%  ±1.77%  ±2.30%
crypto/mac-api-compare.js n=5000000 length=64 operation='update'             ***            +35.86 %   ±1.29%  ±1.72%  ±2.24%
crypto/mac-api-compare.js n=50000 length=64 operation='final-buffer'                         -0.36 %   ±2.08%  ±2.77%  ±3.61%
crypto/mac-api-compare.js n=50000 length=64 operation='final-hex'            ***            -13.11 %   ±1.72%  ±2.28%  ±2.97%

[panva]

Based on the referenced issues and prior work: cc @bnoordhuis @mscdex @tniessen @paragonie-security

[codecov]

Codecov Report

❌ Patch coverage is 84.31105% with 115 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.06%. Comparing base (e7a69c4) to head (76541f0).
⚠️ Report is 31 commits behind head on main.

Files with missing lines	Patch %	Lines
src/crypto/crypto_mac.cc	78.72%	41 Missing and 49 partials ⚠️
lib/internal/crypto/provider_mac.js	91.60%	22 Missing ⚠️
src/crypto/crypto_mac.h	0.00%	2 Missing ⚠️
lib/internal/crypto/util.js	96.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65553      +/-   ##
==========================================
- Coverage   90.08%   90.06%   -0.03%     
==========================================
  Files         751      754       +3     
  Lines      254075   255607    +1532     
  Branches    47910    48281     +371     
==========================================
+ Hits       228882   230209    +1327     
- Misses      16412    16525     +113     
- Partials     8781     8873      +92     

Files with missing lines	Coverage Δ
lib/crypto.js	93.68% <100.00%> (+0.16%)	⬆️
lib/internal/errors.js	98.46% <100.00%> (+<0.01%)	⬆️
src/crypto/crypto_util.h	66.47% <ø> (ø)
src/env.cc	85.60% <100.00%> (+0.24%)	⬆️
src/env.h	98.21% <ø> (ø)
src/node_crypto.cc	81.81% <ø> (ø)
src/node_errors.h	86.95% <ø> (ø)
lib/internal/crypto/util.js	97.43% <96.66%> (-0.03%)	⬇️
src/crypto/crypto_mac.h	0.00% <0.00%> (ø)
lib/internal/crypto/provider_mac.js	91.60% <91.60%> (ø)
... and 1 more

... and 47 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @anonrig.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[github-actions]

Benchmark GHA (crypto / mac): https://github.com/nodejs/node/actions/runs/33089847500