Node.js HMAC Signing Module

A secure and flexible HMAC signing module for Node.js, offering message signing, verification, and hashing with support for multiple algorithms and encodings.

Features

• 🔐 Secure HMAC-based message signing and verification
• 🎯 Support for multiple hash algorithms (sha256, sha512, sha1, md5)
• 📝 Multiple output encodings (hex, base64, base64url, binary, utf8)
• ⚡ Timing-safe signature comparison
• ⚙️ Configurable default settings

Installation

npm install @weegl/signer

Usage

Basic Example

const signer = require('@weegl/signer');

// Sign a message
const message = "Hello, World!";
const secret = "your-secret-key";

async function example() {
    // Sign message
    const signed = await signer.sign(message, secret);
    // "Hello, World!.HMAC_SIGNATURE_HERE"
    
    // Verify signature
    const isValid = await signer.verify(signed, secret);
    // true
}

Direct Hashing

const signer = require('@weegl/signer');

// Generate HMAC hash
const hash = signer.hash("Hello, World!", "secret");

Configuration

Default Settings

The module comes with the following default settings:

• Algorithm: sha256
• Charset (encoding): base64
• Separator: "." (dot)

Customizing Defaults

You can modify the default settings globally:

const signer = require('@weegl/signer');

// Change default algorithm
signer.setDefaultAlgorithm(signer.Algorithms.sha512);

// Change default charset
signer.setDefaultCharset(signer.Charsets.hex);

// Change default separator
signer.setDefaultSeparator('::');

Available Options

Algorithms

const { Algorithms } = require('@weegl/signer');

// Available algorithms
Algorithms.sha256  // ✅ Secure
Algorithms.sha512  // ✅ Secure
Algorithms.sha1    // ⚠️ Deprecated - Vulnerable to collisions
Algorithms.md5     // ⚠️ Deprecated - Vulnerable to collisions

Charsets (Encodings)

const { Charsets } = require('@weegl/signer');

// Available charsets
Charsets.hex       // ⚠️ Less efficient; use base64 instead
Charsets.base64    // ✅ Recommended
Charsets.base64url // ✅ Recommended for URLs
Charsets.binary    // ⚠️ May cause interoperability issues
Charsets.utf8      // ✅ Commonly used, but ensure proper handling

Custom Options Per Operation

You can override default settings for individual operations:

const signed = await signer.sign(message, secret, {
    algorithm: 'sha512',
    charset: 'hex',
    separator: '::'
});

const isValid = await signer.verify(signed, secret, {
    algorithm: 'sha512',
    charset: 'hex',
    separator: '::'
});

Security Considerations

Key Management

• Keep your secret key secure and never expose it in your source code
• Use environment variables or secure key management solutions
• Use a strong, random secret key with sufficient entropy

Algorithm Choice

• SHA256 (default) is recommended for most use cases
• SHA512 provides additional security but with slightly higher computational cost
• Avoid MD5 and SHA1 for new implementations as they are considered cryptographically weak

Timing Attacks Protection

This module uses Node.js's crypto.timingSafeEqual() for signature comparison to prevent timing attacks. Always use the provided verify() function instead of implementing your own comparison.

API Reference

sign(message, secret[, options])

Signs a message using HMAC.

• message {string} - Message to sign
• secret {string} - Secret key
• options {Object} - Optional configuration
  • algorithm {string} - Hash algorithm to use
  • charset {string} - Output encoding
  • separator {string} - Separator between message and signature
• Returns: {Promise} - Signed message

verify(signed, secret[, options])

Verify a signed message.

• signed {string} - Signed message to verify
• secret {string} - Secret key
• options {Object} - Optional configuration (same as sign)
• Returns: {Promise} - True if signature is valid

hash(message, secret[, options])

Generates an HMAC hash.

• message {string} - Message to hash
• secret {string} - Secret key
• options {Object} - Optional configuration
  • algorithm {string} - Hash algorithm
  • charset {string} - Output encoding
• Returns: {string} - Generated hash

📄 Licence

License MIT

Copyright (c) 2024 Weegl