tessl/npm-sodium-native

Low level bindings for libsodium cryptographic library

—

Pending

Overview

Eval results

Files

Hash Functions

Name: tessl/npm-sodium-native
Author: tessl

Cryptographic hash functions including BLAKE2b, SHA-256, and SHA-512 for data integrity, key derivation, and digital fingerprints.

Capabilities

BLAKE2b Generic Hash

High-performance cryptographic hash function with optional keying support.

/**
 * Compute BLAKE2b hash (one-shot)
 * @param output - Output buffer for hash (length determines hash size)
 * @param input - Input buffer to hash
 * @param key - Optional key buffer for keyed hashing (can be null/undefined)
 * @throws Error if buffer sizes are invalid or hashing fails
 */
function crypto_generichash(output: Buffer, input: Buffer, key?: Buffer): void;

Usage Example:

const sodium = require('sodium-native');

// Basic hashing
const message = Buffer.from('Hello, World!');
const hash = Buffer.alloc(32); // 256-bit hash
sodium.crypto_generichash(hash, message);

// Keyed hashing (HMAC-like)
const key = Buffer.alloc(sodium.crypto_generichash_KEYBYTES);
sodium.randombytes_buf(key);
const keyedHash = Buffer.alloc(64); // 512-bit hash
sodium.crypto_generichash(keyedHash, message, key);

BLAKE2b Batch Hashing

Efficiently hash multiple buffers in a single operation.

/**
 * Compute BLAKE2b hash of multiple buffers
 * @param output - Output buffer for hash
 * @param batch - Array of buffers to hash
 * @param key - Optional key buffer for keyed hashing
 * @throws Error if hashing fails
 */
function crypto_generichash_batch(output: Buffer, batch: Buffer[], key?: Buffer): void;

BLAKE2b Streaming Hash

Initialize, update, and finalize BLAKE2b hash computation for large data.

/**
 * Generate random key for BLAKE2b
 * @param key - Output buffer for key (must be KEYBYTES long)
 * @throws Error if key generation fails
 */
function crypto_generichash_keygen(key: Buffer): void;

/**
 * Initialize BLAKE2b streaming hash
 * @param state - State buffer (must be STATEBYTES long)
 * @param key - Optional key buffer for keyed hashing
 * @param outputLength - Desired output hash length in bytes
 * @throws Error if initialization fails or parameters invalid
 */
function crypto_generichash_init(state: Buffer, key?: Buffer, outputLength?: number): void;

/**
 * Update BLAKE2b streaming hash with more data
 * @param state - State buffer from init
 * @param input - Input buffer to add to hash
 * @throws Error if update fails
 */
function crypto_generichash_update(state: Buffer, input: Buffer): void;

/**
 * Finalize BLAKE2b streaming hash and get result
 * @param state - State buffer from init/update
 * @param output - Output buffer for final hash
 * @throws Error if finalization fails
 */
function crypto_generichash_final(state: Buffer, output: Buffer): void;

Usage Example:

const sodium = require('sodium-native');

// Streaming hash for large data
const state = Buffer.alloc(sodium.crypto_generichash_STATEBYTES);
const key = Buffer.alloc(sodium.crypto_generichash_KEYBYTES);
sodium.crypto_generichash_keygen(key);

sodium.crypto_generichash_init(state, key, 32);

// Process data in chunks
const chunk1 = Buffer.from('First part ');
const chunk2 = Buffer.from('of large message');
sodium.crypto_generichash_update(state, chunk1);
sodium.crypto_generichash_update(state, chunk2);

const finalHash = Buffer.alloc(32);
sodium.crypto_generichash_final(state, finalHash);

SHA-512 Hash

Standard SHA-512 cryptographic hash function.

/**
 * Compute SHA-512 hash (one-shot)
 * @param out - Output buffer for hash (must be BYTES long)
 * @param input - Input buffer to hash
 * @throws Error if hashing fails
 */
function crypto_hash(out: Buffer, input: Buffer): void;

/**
 * Compute SHA-512 hash (one-shot, explicit function)
 * @param out - Output buffer for hash (must be BYTES long)
 * @param input - Input buffer to hash
 * @throws Error if hashing fails
 */
function crypto_hash_sha512(out: Buffer, input: Buffer): void;

SHA-512 Streaming Hash

Initialize, update, and finalize SHA-512 hash computation.

/**
 * Initialize SHA-512 streaming hash
 * @param state - State buffer (must be STATEBYTES long)
 * @throws Error if initialization fails
 */
function crypto_hash_sha512_init(state: Buffer): void;

/**
 * Update SHA-512 streaming hash with more data
 * @param state - State buffer from init
 * @param input - Input buffer to add to hash
 * @throws Error if update fails
 */
function crypto_hash_sha512_update(state: Buffer, input: Buffer): void;

/**
 * Finalize SHA-512 streaming hash and get result
 * @param state - State buffer from init/update
 * @param out - Output buffer for final hash (must be BYTES long)
 * @throws Error if finalization fails
 */
function crypto_hash_sha512_final(state: Buffer, out: Buffer): void;

SHA-256 Hash

Standard SHA-256 cryptographic hash function.

/**
 * Compute SHA-256 hash (one-shot)
 * @param out - Output buffer for hash (must be BYTES long)
 * @param input - Input buffer to hash
 * @throws Error if hashing fails
 */
function crypto_hash_sha256(out: Buffer, input: Buffer): void;

/**
 * Initialize SHA-256 streaming hash
 * @param state - State buffer (must be STATEBYTES long)
 * @throws Error if initialization fails
 */
function crypto_hash_sha256_init(state: Buffer): void;

/**
 * Update SHA-256 streaming hash with more data
 * @param state - State buffer from init
 * @param input - Input buffer to add to hash
 * @throws Error if update fails
 */
function crypto_hash_sha256_update(state: Buffer, input: Buffer): void;

/**
 * Finalize SHA-256 streaming hash and get result
 * @param state - State buffer from init/update
 * @param out - Output buffer for final hash (must be BYTES long)
 * @throws Error if finalization fails
 */
function crypto_hash_sha256_final(state: Buffer, out: Buffer): void;

Usage Example:

const sodium = require('sodium-native');

// SHA-256 one-shot
const message = Buffer.from('Hello, World!');
const sha256Hash = Buffer.alloc(sodium.crypto_hash_sha256_BYTES);
sodium.crypto_hash_sha256(sha256Hash, message);

// SHA-256 streaming
const sha256State = Buffer.alloc(sodium.crypto_hash_sha256_STATEBYTES);
sodium.crypto_hash_sha256_init(sha256State);
sodium.crypto_hash_sha256_update(sha256State, Buffer.from('Hello, '));
sodium.crypto_hash_sha256_update(sha256State, Buffer.from('World!'));

const streamedHash = Buffer.alloc(sodium.crypto_hash_sha256_BYTES);
sodium.crypto_hash_sha256_final(sha256State, streamedHash);

Constants

// BLAKE2b generic hash constants
const crypto_generichash_STATEBYTES: number;
const crypto_generichash_BYTES_MIN: number;
const crypto_generichash_BYTES_MAX: number;
const crypto_generichash_BYTES: number;
const crypto_generichash_KEYBYTES_MIN: number;
const crypto_generichash_KEYBYTES_MAX: number;
const crypto_generichash_KEYBYTES: number;

// SHA-512 constants
const crypto_hash_BYTES: number;
const crypto_hash_sha512_STATEBYTES: number;
const crypto_hash_sha512_BYTES: number;

// SHA-256 constants
const crypto_hash_sha256_STATEBYTES: number;
const crypto_hash_sha256_BYTES: number;

Common Patterns

File Hashing

const sodium = require('sodium-native');
const fs = require('fs');

function hashFile(filename, algorithm = 'blake2b') {
  const data = fs.readFileSync(filename);
  
  switch (algorithm) {
    case 'blake2b':
      const blake2bHash = Buffer.alloc(32);
      sodium.crypto_generichash(blake2bHash, data);
      return blake2bHash;
      
    case 'sha256':
      const sha256Hash = Buffer.alloc(sodium.crypto_hash_sha256_BYTES);
      sodium.crypto_hash_sha256(sha256Hash, data);
      return sha256Hash;
      
    case 'sha512':
      const sha512Hash = Buffer.alloc(sodium.crypto_hash_sha512_BYTES);
      sodium.crypto_hash_sha512(sha512Hash, data);
      return sha512Hash;
      
    default:
      throw new Error('Unsupported algorithm');
  }
}

Merkle Tree Implementation

const sodium = require('sodium-native');

class MerkleTree {
  constructor(leaves) {
    this.leaves = leaves.map(leaf => this.hash(leaf));
    this.tree = this.buildTree(this.leaves);
  }
  
  hash(data) {
    const hash = Buffer.alloc(32);
    sodium.crypto_generichash(hash, data);
    return hash;
  }
  
  buildTree(nodes) {
    if (nodes.length === 1) return nodes[0];
    
    const nextLevel = [];
    for (let i = 0; i < nodes.length; i += 2) {
      const left = nodes[i];
      const right = nodes[i + 1] || left;
      const combined = Buffer.concat([left, right]);
      nextLevel.push(this.hash(combined));
    }
    
    return this.buildTree(nextLevel);
  }
  
  getRoot() {
    return this.tree;
  }
}

Key Derivation Function

const sodium = require('sodium-native');

function deriveKey(password, salt, keyLength = 32) {
  // Simple key derivation using BLAKE2b
  const combined = Buffer.concat([password, salt]);
  const key = Buffer.alloc(keyLength);
  sodium.crypto_generichash(key, combined);
  return key;
}

function deriveMultipleKeys(masterKey, context, count) {
  const keys = [];
  for (let i = 0; i < count; i++) {
    const input = Buffer.concat([
      masterKey,
      Buffer.from(context),
      Buffer.from([i])
    ]);
    const derivedKey = Buffer.alloc(32);
    sodium.crypto_generichash(derivedKey, input);
    keys.push(derivedKey);
  }
  return keys;
}

Install with Tessl CLI