Introduction
ehmac is a cryptographic library designed to implement the Hash-Based Message Authentication Code (HMAC) algorithm in JavaScript environments. The library provides a pure‑JavaScript implementation that can operate both in Node.js and in web browsers, making it suitable for applications that require HMAC functionality across multiple platforms without relying on native bindings. The primary goal of ehmac is to offer a lightweight, dependable, and standards‑conforming HMAC implementation that can serve as a drop‑in replacement for native cryptographic modules when those are unavailable or unsuitable.
Unlike many cryptographic libraries that depend on native extensions or external binaries, ehmac is written entirely in JavaScript. This design choice promotes portability, simplifies deployment, and reduces the attack surface associated with native code. The library is licensed under a permissive open‑source license, allowing it to be freely used, modified, and distributed in both commercial and non‑commercial projects.
In the following sections, the article explores the historical context that gave rise to ehmac, delves into its architectural design and key concepts, and examines the practical aspects of its usage and integration.
History and Development
Origins
The HMAC algorithm, standardized in RFC 2104 and later refined in RFC 2104, is widely used in protocols such as TLS, SSH, and OAuth. Prior to the release of ehmac, most JavaScript developers relied on Node.js's built‑in crypto module or on external native bindings to achieve HMAC functionality. While the Node.js crypto module is efficient, it requires a compiled environment, which can be problematic on platforms where native compilation is restricted or where the target environment does not support Node.js.
The need for a pure‑JavaScript HMAC implementation became apparent as the ecosystem shifted toward serverless functions, client‑side web applications, and environments such as Cloudflare Workers that impose strict restrictions on native code. ehmac emerged as a response to this need, offering an implementation that adheres closely to the HMAC specification while remaining lightweight and easy to integrate.
Development Milestones
- Version 0.1 – Initial release featuring support for SHA‑1 and SHA‑256 hash functions. The implementation was derived from the Node.js crypto module's source code, reimplemented in JavaScript.
- Version 0.3 – Added support for SHA‑512 and the SHA‑3 family (SHA‑3 224, 256, 384, and 512). Introduced a modular design that allows developers to import only the desired hash functions, reducing the final bundle size.
- Version 1.0 – Marked the transition to a fully documented API. Added unit tests for edge cases, improved error handling, and introduced an optional stream API for large data sets.
- Version 1.2 – Enhanced performance by leveraging typed arrays and optimized padding logic. Updated documentation to include detailed usage examples and performance benchmarks.
- Version 2.0 – Implemented support for WebCrypto API integration, allowing the library to delegate hashing to native implementations when available, thereby improving performance on modern browsers.
The project has been actively maintained since its inception, with contributions from a community of developers focused on cryptographic correctness and performance optimization.
Architecture and Design
Modular Structure
ehmac adopts a modular architecture. The core library consists of a set of modules, each responsible for a specific hash function. The modules expose a uniform interface that accepts a key, data, and optional options such as output encoding. This modularity allows developers to import only the hash functions they require, minimizing the footprint of the final application bundle.
Pure‑JavaScript Implementation
All cryptographic operations are performed in JavaScript, without reliance on native bindings. The library uses typed arrays (Uint8Array, Uint32Array) to represent binary data. Operations such as bitwise XOR, byte concatenation, and padding are implemented using standard JavaScript constructs, ensuring compatibility across all environments that support ECMAScript 2015 and later.
Compatibility Layer
To provide a seamless developer experience, ehmac implements a small compatibility layer that mimics the Node.js crypto API's interface. Functions such as createHmac and Hmac.update are available, enabling developers to migrate code from Node.js to environments that only support pure JavaScript. The library also exposes a Hmac.digest method that accepts an optional encoding parameter, returning the HMAC in formats such as hexadecimal, base64, or a raw buffer.
Performance Optimizations
- Typed Arrays – Utilized for efficient manipulation of binary data.
- Padding Optimization – The library precomputes the padded key once per instance, avoiding repeated padding for each update.
- Chunked Processing – For large inputs, the library processes data in fixed‑size blocks, preventing excessive memory usage.
- WebCrypto Integration – When running in browsers that support the WebCrypto API, the library can delegate the hashing step to native implementations, gaining performance benefits.
Error Handling
ehmac validates input parameters such as key type, data type, and encoding options. Errors are thrown as standard JavaScript Error objects, providing descriptive messages that aid in debugging. The library also guards against insecure usage patterns, such as supplying an empty key, and emits warnings accordingly.
Key Concepts
HMAC Algorithm
HMAC is defined by the following procedure:
- Ensure the key length is equal to the hash block size. If the key is longer, hash it first; if shorter, pad with zeros.
- Compute the inner hash: hash( (key XOR ipad) || message ).
- Compute the outer hash: hash( (key XOR opad) || inner_hash ).
- Return the outer hash as the HMAC result.
Where ipad is a byte of 0x36 repeated to match the block size, and opad is a byte of 0x5c repeated similarly.
Supported Hash Functions
ehmac supports the following hash algorithms:
- SHA‑1 – 160‑bit digest, 64‑byte block size.
- SHA‑256 – 256‑bit digest, 64‑byte block size.
- SHA‑512 – 512‑bit digest, 128‑byte block size.
- SHA‑3 family – SHA‑3 224, 256, 384, 512, each with block sizes defined by the SHA‑3 specification.
Each hash module implements the corresponding compression function and initialization vectors as specified by the RFCs.
Key and Data Formats
Keys and data can be supplied in various formats:
- Buffer or Uint8Array – Raw binary data.
- String – If a string is provided, the library interprets it as UTF‑8 encoded text unless an alternative encoding is specified.
- Encoding options – Developers can specify input encodings (e.g., 'utf8', 'hex', 'base64') and output encodings in the API calls.
Streaming API
For scenarios where the input data is large or received incrementally, ehmac offers a streaming API. The Hmac.update method accepts data chunks sequentially, updating internal state without storing the entire message. After all data has been processed, the Hmac.digest method finalizes the computation and returns the HMAC.
API Reference
createHmac(algorithm, key[, options])
Creates an HMAC object using the specified algorithm and key. The algorithm parameter is a string identifying the hash function (e.g., 'sha256'). The key can be a Buffer, Uint8Array, or string. Optional options may include an encoding field indicating how to interpret a string key.
Hmac.update(data[, encoding])
Feeds data into the HMAC instance. The data parameter can be a Buffer, Uint8Array, or string. If a string is provided, the encoding argument specifies its character encoding. Multiple calls to update are permitted.
Hmac.digest([encoding])
Finalizes the HMAC computation and returns the result. If an encoding is specified, the output is returned as a string encoded accordingly; otherwise, a Uint8Array is returned.
Hmac.hexDigest()
Convenience method that returns the HMAC as a hexadecimal string.
Hmac.base64Digest()
Convenience method that returns the HMAC as a base64‑encoded string.
Hmac.reset()
Resets the internal state of the HMAC instance, allowing it to be reused with the same key for a new message.
Hmac.key
Read‑only property exposing the original key used to initialize the HMAC.
Usage Examples
Node.js Environment
In a Node.js application, ehmac can replace the native crypto module when native bindings are undesirable.
javascript
const { createHmac } = require('ehmac');
const key = Buffer.from('supersecretkey', 'utf8');
const hmac = createHmac('sha256', key);
hmac.update('Message to sign');
const digest = hmac.hexDigest();
console.log('HMAC:', digest);
Browser Environment
When running in a browser, the library can be bundled using a tool such as Webpack or Rollup.
javascript
import { createHmac } from 'ehmac';
const key = new TextEncoder().encode('browserKey');
const hmac = createHmac('sha512', key);
hmac.update('Hello, world!');
hmac.digest('base64');
Streaming Data
For large payloads, the streaming API allows incremental updates.
javascript
const hmac = createHmac('sha256', 'key');
fetch('https://example.com/largefile').then(response => response.body)
.then(stream => {
const reader = stream.getReader();
function read() {
return reader.read().then(({ done, value }) => {
if (done) {
console.log('HMAC:', hmac.hexDigest());
return;
}
hmac.update(value);
return read();
});
}
return read();
});
Security Considerations
Key Management
HMAC security depends critically on key secrecy. The library provides no built‑in key management facilities; developers must secure keys using environment variables, secure key stores, or hardware security modules. Keys should be stored in a manner that prevents accidental exposure and should be rotated according to organizational policies.
Algorithm Selection
Although HMAC can be used with various hash functions, not all are equally secure. SHA‑1 is considered weak due to collision vulnerabilities. It is recommended to use SHA‑256, SHA‑512, or SHA‑3 variants for production systems. The library warns developers when using SHA‑1 and encourages the use of stronger algorithms.
Timing Attacks
The comparison of HMAC outputs should be performed using constant‑time comparison functions to mitigate timing attacks. The library does not provide a dedicated comparison routine; developers should use established utilities or the WebCrypto API's subtle.verify method when available.
Padding and Block Size
Correct handling of key padding is essential for HMAC correctness. The library implements padding according to the RFC specifications and ensures that keys longer than the block size are hashed before padding. Incorrect padding can lead to reduced security.
Input Validation
The library validates inputs and throws descriptive errors for unsupported encodings or null values. This defensive programming approach reduces the likelihood of silent failures that could compromise security.
Performance Evaluation
Benchmark Methodology
Benchmarks were conducted in a controlled environment using Node.js v20.x and a modern web browser. Test vectors included small messages (less than 1 KB) and large streams (10 MB). The library was compared against the native crypto module and the WebCrypto API.
Results Summary
- Small Messages – ehmac achieves performance close to native crypto, with a slight overhead (~5–10%) due to pure‑JavaScript execution.
- Large Streams – The streaming API maintains low memory consumption and processes data at a rate comparable to native implementations.
- Browser Environment – When WebCrypto is available, the library delegates hashing, resulting in performance similar to native browsers. Without WebCrypto, pure‑JavaScript HMAC is about twice as slow as native implementations.
Optimization Opportunities
Potential future optimizations include: WebAssembly integration for faster hash computations, further minimization of typed array allocations, and improved chunking logic for streaming scenarios.
Compatibility and Integration
Node.js
Compatible with Node.js versions 12 and above. The library can be installed via npm and imported using CommonJS or ES modules.
Browser
ES module support is provided. The library can be bundled with tools such as Rollup, Webpack, or Vite. It includes shims for environments lacking typed arrays.
Serverless Platforms
Because the library is pure JavaScript, it can be deployed on serverless platforms like AWS Lambda, Azure Functions, or Google Cloud Functions without requiring native build steps.
Integration with Existing Frameworks
Frameworks such as Express.js or Koa can use ehmac for request signing or token generation. In authentication libraries, developers can incorporate HMAC verification into middleware or security hooks.
Contributing
Repository
Source code is maintained on GitHub. Contributors are encouraged to submit pull requests and report issues.
Testing
Unit tests cover all hash modules and the streaming API. Developers can run tests using npm test after cloning the repository.
Documentation
Documentation is generated automatically from source comments using JSDoc. The README file serves as a quick start guide.
License
The library is released under the MIT License. See the LICENSE file for full terms.
No comments yet. Be the first to comment!