sodium-hmac

library2.1.0jsnpmunverified

sodium-hmac is a JavaScript utility library for creating Hash-based Message Authentication Codes (HMAC). Currently at stable version 2.1.0, this package provides both a streaming API for processing data in chunks and a simplified one-shot API for common SHA256 and SHA512 HMAC operations. Its key differentiator is the flexibility to integrate custom hash functions, provided they adhere to a specific interface (init, update, final, BYTES, STATEBYTES), allowing users to leverage various cryptographic primitives like Blake2b via external libraries such as `sodium`. Maintained by the Holepunch ecosystem, it focuses on reliable cryptographic primitives for secure data integrity and authentication. The library does not enforce specific external dependencies for its hash functions, making it adaptable to different environments and cryptographic backends.

auth-security serialization

npm install sodium-hmac

github ↗package ↗

INSTALL

IMPORT

SIG · SODIUM-HMAC

sodium-hmac

auth-securityjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HMAC

✓ import { HMAC } from 'sodium-hmac'

✗ const HMAC = require('sodium-hmac').HMAC

While CommonJS `require` is shown in examples and is functional, prefer named ESM imports for modern JavaScript environments.

sha256

✓ import { sha256 } from 'sodium-hmac'

✗ const sha256 = require('sodium-hmac').sha256

The `sha256` hash function is exported directly for use with the `HMAC` class or as a standalone utility.

HMAC.sha256 (static method)

✓ import { HMAC } from 'sodium-hmac'; const result = HMAC.sha256(data, key);

✗ const result = require('sodium-hmac').HMAC.sha256(data, key)

This provides a convenient one-shot API for HMAC-SHA256, abstracting the streaming interface.

This quickstart demonstrates both the streaming and one-shot HMAC APIs, using built-in SHA256/SHA512 and conceptually showing how to integrate a custom hash function.

import { HMAC, sha256, sha512 } from 'sodium-hmac'; import b4a from 'b4a'; // A common Buffer-compatible utility for universal environments const key = b4a.from('a-very-secret-key-of-at-least-32-bytes'); const dataPart1 = b4a.from('This is the first part '); const dataPart2 = b4a.from('and this is the second part of the message.'); // 1. Using the streaming API with SHA256 const hmacSha256 = new HMAC(sha256); hmacSha256.init(key); hmacSha256.update(dataPart1); hmacSha256.update(dataPart2); const outputSha256 = hmacSha256.final(); console.log('HMAC-SHA256 (streaming):', outputSha256.toString('hex')); // 2. Using the simple one-shot API with SHA512 const fullData = b4a.concat([dataPart1, dataPart2]); const outputSha512 = HMAC.sha512(fullData, key); console.log('HMAC-SHA512 (one-shot):', outputSha512.toString('hex')); // 3. Demonstrating custom hash function integration (conceptual, requires 'sodium' or similar) // Assuming 'sodium' is installed and provides a compatible blake2b hash interface. /* import sodium from 'sodium-native'; // or 'libsodium-wrappers' const blake2b = { init: (state, key) => sodium.crypto_generichash_init(state, key, 64), // 64 bytes for BLAKE2b update: sodium.crypto_generichash_update, final: (state, out) => sodium.crypto_generichash_final(state, out, 64), BYTES: 64, STATEBYTES: sodium.crypto_generichash_STATEBYTES }; const hmacBlake2b = new HMAC(blake2b); hmacBlake2b.init(key); hmacBlake2b.update(fullData); const outputBlake2b = hmacBlake2b.final(b4a.alloc(blake2b.BYTES)); console.log('HMAC-BLAKE2b (custom hash):', outputBlake2b.toString('hex')); */

Debug

Known issues

gotchaWhen using the streaming HMAC API (HMAC class instance), `hmac.init(key)` must always be called before any calls to `hmac.update(data)`. Failing to initialize will result in runtime errors.

fix

Ensure `hmac.init(key)` is invoked once after creating the HMAC instance and before processing any data chunks.

affects: >=1.0.0

gotchaThe `HMAC` constructor expects the `hash` argument to be an object conforming to a specific interface (`init`, `update`, `final`, `BYTES`, `STATEBYTES`). Providing an object that lacks any of these properties will lead to a `TypeError`.

fix

When supplying a custom hash function (e.g., from `libsodium` or other crypto libraries), ensure it exposes all required methods and properties. Refer to the `sha256` or `sha512` exports as examples.

affects: >=1.0.0

gotchaThe `final()` method returns the HMAC digest. If you intend to use the HMAC result, you must capture the return value of `hmac.final()`.

fix

Always assign the result of `hmac.final()` to a variable, e.g., `const output = hmac.final();`.

affects: >=1.0.0

gotchaAll data inputs (`key`, `data` in `update`, `data` in static methods) are expected to be `Buffer` instances or `Uint8Array`s. While Node.js `Buffer` works, in browser environments, `Uint8Array` or a universal buffer polyfill like `b4a` should be used.

fix

Convert all string or other data types to `Buffer.from('your-data')` or `b4a.from('your-data')` before passing them to HMAC functions.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'init')

The `HMAC` constructor was provided with a `hash` object that is missing the `init` method, or the object structure is incorrect.

fix

Verify that the custom hash object passed to `new HMAC(hash)` includes all required methods: `init`, `update`, `final`, and properties: `BYTES`, `STATEBYTES`. Use `sha256` or `sha512` exports as a reference.

Error: HMAC not initialized

An `HMAC` instance's `update()` method was called before `init()` was invoked to set the secret key.

fix

Call `hmac.init(Buffer.from('your-key'))` immediately after creating the `HMAC` instance and before calling `hmac.update(data)`.

TypeError: Data must be a Buffer or Uint8Array

A non-Buffer/Uint8Array value was passed to `hmac.update()` or a static HMAC method (`HMAC.sha256`, `HMAC.sha512`).

fix

Ensure all input data, including the key and message parts, are converted to `Buffer` or `Uint8Array` instances, for example, using `Buffer.from('string')` or `b4a.from('string')`.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/holepunchto/sodium-hmac ↗

packagehttps://www.npmjs.com/package/sodium-hmac ↗