tessl/npm-libsodium-wrappers-sumo

The Sodium cryptographic library compiled to pure JavaScript (wrappers, sumo variant)

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Message Authentication

Name: tessl/npm-libsodium-wrappers-sumo
Author: tessl

Message authentication functions provide cryptographic proof of message authenticity and integrity using HMAC (Hash-based Message Authentication Code) with various hash functions.

Supported Algorithms

HMAC-SHA256: Fast, widely supported, 32-byte output
HMAC-SHA512: Higher security margin, 64-byte output
HMAC-SHA512/256: SHA-512 truncated to 32 bytes for performance
Generic Auth: Defaults to HMAC-SHA512/256, recommended for new applications

Generic Authentication (Recommended)

The generic authentication functions use HMAC-SHA512/256 and are recommended for new applications.

Key Generation

/**
 * Generate a random key for message authentication
 * @returns Uint8Array - 32-byte authentication key
 */
function crypto_auth_keygen(): Uint8Array;

Authentication

/**
 * Compute authentication tag for a message
 * @param message - Data to authenticate
 * @param key - 32-byte authentication key
 * @returns Uint8Array - 32-byte authentication tag
 */
function crypto_auth(message: Uint8Array, key: Uint8Array): Uint8Array;

Verification

/**
 * Verify authentication tag for a message
 * @param tag - Authentication tag to verify
 * @param message - Original message data
 * @param key - 32-byte authentication key
 * @returns boolean - True if tag is valid
 */
function crypto_auth_verify(
  tag: Uint8Array, 
  message: Uint8Array, 
  key: Uint8Array
): boolean;

Constants

const crypto_auth_BYTES: number;      // 32 (tag length)
const crypto_auth_KEYBYTES: number;   // 32 (key length)

HMAC-SHA256

Fast HMAC implementation using SHA-256 hash function.

Key Generation

/**
 * Generate a random key for HMAC-SHA256
 * @returns Uint8Array - 32-byte key
 */
function crypto_auth_hmacsha256_keygen(): Uint8Array;

One-Shot Operations

/**
 * Compute HMAC-SHA256 authentication tag
 * @param message - Data to authenticate
 * @param key - 32-byte HMAC key
 * @returns Uint8Array - 32-byte authentication tag
 */
function crypto_auth_hmacsha256(
  message: Uint8Array, 
  key: Uint8Array
): Uint8Array;

/**
 * Verify HMAC-SHA256 authentication tag
 * @param tag - Tag to verify
 * @param message - Original message
 * @param key - 32-byte HMAC key
 * @returns boolean - True if tag is valid
 */
function crypto_auth_hmacsha256_verify(
  tag: Uint8Array, 
  message: Uint8Array, 
  key: Uint8Array
): boolean;

Streaming Operations

/**
 * Initialize HMAC-SHA256 streaming state
 * @param key - HMAC key (can be null for keyless operation)
 * @returns Uint8Array - State object for streaming
 */
function crypto_auth_hmacsha256_init(key: Uint8Array | null): Uint8Array;

/**
 * Update HMAC-SHA256 state with data chunk
 * @param state_address - State from init function
 * @param message_chunk - Data chunk to process
 */
function crypto_auth_hmacsha256_update(
  state_address: any, 
  message_chunk: Uint8Array
): void;

/**
 * Finalize HMAC-SHA256 and return authentication tag
 * @param state_address - State from init/update functions
 * @returns Uint8Array - Final authentication tag
 */
function crypto_auth_hmacsha256_final(state_address: any): Uint8Array;

Constants

const crypto_auth_hmacsha256_BYTES: number;      // 32
const crypto_auth_hmacsha256_KEYBYTES: number;   // 32

HMAC-SHA512

HMAC implementation using SHA-512 hash function for maximum security.

Key Generation

/**
 * Generate a random key for HMAC-SHA512
 * @returns Uint8Array - 32-byte key
 */
function crypto_auth_hmacsha512_keygen(): Uint8Array;

One-Shot Operations

/**
 * Compute HMAC-SHA512 authentication tag
 * @param message - Data to authenticate
 * @param key - 32-byte HMAC key
 * @returns Uint8Array - 64-byte authentication tag
 */
function crypto_auth_hmacsha512(
  message: Uint8Array, 
  key: Uint8Array
): Uint8Array;

/**
 * Verify HMAC-SHA512 authentication tag
 * @param tag - Tag to verify
 * @param message - Original message
 * @param key - 32-byte HMAC key
 * @returns boolean - True if tag is valid
 */
function crypto_auth_hmacsha512_verify(
  tag: Uint8Array, 
  message: Uint8Array, 
  key: Uint8Array
): boolean;

Streaming Operations

function crypto_auth_hmacsha512_init(key: Uint8Array | null): Uint8Array;
function crypto_auth_hmacsha512_update(state_address: any, message_chunk: Uint8Array): void;
function crypto_auth_hmacsha512_final(state_address: any): Uint8Array;

Constants

const crypto_auth_hmacsha512_BYTES: number;      // 64
const crypto_auth_hmacsha512_KEYBYTES: number;   // 32

HMAC-SHA512/256

HMAC using SHA-512 internally but truncated to 256 bits for better performance with security equivalent to SHA-256.

Key Generation

/**
 * Generate a random key for HMAC-SHA512/256
 * @returns Uint8Array - 32-byte key
 */
function crypto_auth_hmacsha512256_keygen(): Uint8Array;

One-Shot Operations

/**
 * Compute HMAC-SHA512/256 authentication tag
 * @param message - Data to authenticate
 * @param key - 32-byte HMAC key
 * @returns Uint8Array - 32-byte authentication tag
 */
function crypto_auth_hmacsha512256(
  message: Uint8Array, 
  key: Uint8Array
): Uint8Array;

/**
 * Verify HMAC-SHA512/256 authentication tag
 * @param tag - Tag to verify
 * @param message - Original message
 * @param key - 32-byte HMAC key
 * @returns boolean - True if tag is valid
 */
function crypto_auth_hmacsha512256_verify(
  tag: Uint8Array, 
  message: Uint8Array, 
  key: Uint8Array
): boolean;

Streaming Operations

function crypto_auth_hmacsha512256_init(key: Uint8Array | null): Uint8Array;
function crypto_auth_hmacsha512256_update(state_address: any, message_chunk: Uint8Array): void;
function crypto_auth_hmacsha512256_final(state_address: any): Uint8Array;

Constants

const crypto_auth_hmacsha512256_BYTES: number;      // 32
const crypto_auth_hmacsha512256_KEYBYTES: number;   // 32

Usage Examples

Basic Message Authentication

import _sodium from 'libsodium-wrappers-sumo';
await _sodium.ready;
const sodium = _sodium;

// Generate authentication key
const key = sodium.crypto_auth_keygen();

// Message to authenticate
const message = sodium.from_string('Important message');

// Create authentication tag
const tag = sodium.crypto_auth(message, key);

// Verify authentication tag
const isValid = sodium.crypto_auth_verify(tag, message, key);
console.log('Message is authentic:', isValid); // true

// Tampered message verification
const tamperedMessage = sodium.from_string('Tampered message');
const isValidTampered = sodium.crypto_auth_verify(tag, tamperedMessage, key);
console.log('Tampered message is authentic:', isValidTampered); // false

HMAC-SHA256 Authentication

// Use HMAC-SHA256 specifically
const key = sodium.crypto_auth_hmacsha256_keygen();
const message = sodium.from_string('Data to authenticate');

const tag = sodium.crypto_auth_hmacsha256(message, key);
const isValid = sodium.crypto_auth_hmacsha256_verify(tag, message, key);

console.log('Tag length:', tag.length); // 32 bytes
console.log('Is valid:', isValid); // true

Streaming Authentication for Large Data

// Initialize streaming HMAC
const key = sodium.crypto_auth_hmacsha256_keygen();
const state = sodium.crypto_auth_hmacsha256_init(key);

// Process data in chunks
const chunk1 = sodium.from_string('First chunk of ');
const chunk2 = sodium.from_string('large data file');

sodium.crypto_auth_hmacsha256_update(state, chunk1);
sodium.crypto_auth_hmacsha256_update(state, chunk2);

// Finalize and get tag
const tag = sodium.crypto_auth_hmacsha256_final(state);

// Verify with complete message
const completeMessage = sodium.from_string('First chunk of large data file');
const isValid = sodium.crypto_auth_hmacsha256_verify(tag, completeMessage, key);
console.log('Streaming authentication valid:', isValid); // true

API Token Authentication

// Create API authentication system
class APIAuth {
  constructor() {
    this.key = sodium.crypto_auth_keygen();
  }
  
  createToken(payload) {
    const message = sodium.from_string(JSON.stringify(payload));
    const tag = sodium.crypto_auth(message, this.key);
    return {
      payload,
      signature: sodium.to_base64(tag)
    };
  }
  
  verifyToken(token) {
    try {
      const message = sodium.from_string(JSON.stringify(token.payload));
      const tag = sodium.from_base64(token.signature);
      return sodium.crypto_auth_verify(tag, message, this.key);
    } catch (e) {
      return false;
    }
  }
}

// Usage
const auth = new APIAuth();
const token = auth.createToken({ user: 'alice', exp: Date.now() + 3600000 });
console.log('Token valid:', auth.verifyToken(token)); // true

Performance Comparison

const message = new Uint8Array(1024 * 1024); // 1MB of data
const key = sodium.crypto_auth_keygen();

console.time('HMAC-SHA256');
const tag256 = sodium.crypto_auth_hmacsha256(message, key);
console.timeEnd('HMAC-SHA256');

console.time('HMAC-SHA512');
const tag512 = sodium.crypto_auth_hmacsha512(message, key);
console.timeEnd('HMAC-SHA512');

console.time('HMAC-SHA512/256');
const tag512256 = sodium.crypto_auth_hmacsha512256(message, key);
console.timeEnd('HMAC-SHA512/256');

console.log('Tag lengths:', tag256.length, tag512.length, tag512256.length);
// Output: Tag lengths: 32 64 32

Security Considerations

Key Management: Keep authentication keys secret and use crypto_auth_keygen() for generation
Constant-Time Verification: All verify functions use constant-time comparison to prevent timing attacks
Algorithm Selection: Use generic crypto_auth() for new applications, specific variants for compatibility
Tag Storage: Authentication tags can be stored publicly but should not be modified
Message Integrity: Authentication provides integrity but not confidentiality - use AEAD for both