tessl/npm-libsodium-wrappers

The Sodium cryptographic library compiled to pure JavaScript providing comprehensive cryptographic operations including encryption, digital signatures, key exchange, password hashing, and random number generation for web browsers and Node.js environments.

—

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
Author: tessl

Message Authentication Code (MAC) functions for verifying message integrity and authenticity. These functions ensure that messages have not been tampered with and confirm the identity of the sender.

Capabilities

Generic Authentication

HMAC-SHA512-256 based authentication providing strong security with reasonable performance.

/**
 * Computes an authentication tag for a message
 * @param message - The message to authenticate
 * @param key - 32-byte authentication key
 * @returns 32-byte authentication tag
 */
function crypto_auth(message, key);

/**
 * Verifies an authentication tag
 * @param tag - 32-byte authentication tag to verify
 * @param message - The original message
 * @param key - 32-byte authentication key used for tagging
 * @returns true if tag is valid, false otherwise
 */
function crypto_auth_verify(tag, message, key);

/**
 * Generates a random authentication key
 * @returns 32-byte authentication key
 */
function crypto_auth_keygen();

HMAC-SHA256

function crypto_auth_hmacsha256(message, key);
function crypto_auth_hmacsha256_verify(tag, message, key);
function crypto_auth_hmacsha256_keygen();

// Streaming operations
function crypto_auth_hmacsha256_init(key);
function crypto_auth_hmacsha256_update(state_address, message_chunk);
function crypto_auth_hmacsha256_final(state_address);

HMAC-SHA512

function crypto_auth_hmacsha512(message, key);
function crypto_auth_hmacsha512_verify(tag, message, key);
function crypto_auth_hmacsha512_keygen();

// Streaming operations
function crypto_auth_hmacsha512_init(key);
function crypto_auth_hmacsha512_update(state_address, message_chunk);
function crypto_auth_hmacsha512_final(state_address);

HMAC-SHA512-256

function crypto_auth_hmacsha512256(message, key);
function crypto_auth_hmacsha512256_verify(tag, message, key);
function crypto_auth_hmacsha512256_keygen();

// Streaming operations
function crypto_auth_hmacsha512256_init(key);
function crypto_auth_hmacsha512256_update(state_address, message_chunk);
function crypto_auth_hmacsha512256_final(state_address);

One-Time Authentication

Poly1305-based one-time authentication for high-speed applications.

/**
 * Computes a Poly1305 authentication tag
 * @param message - The message to authenticate
 * @param key - 32-byte one-time key (must never be reused)
 * @returns 16-byte authentication tag
 */
function crypto_onetimeauth(message, key);

/**
 * Verifies a Poly1305 authentication tag
 * @param hash - 16-byte authentication tag to verify
 * @param message - The original message
 * @param key - 32-byte one-time key used for tagging
 * @returns true if tag is valid, false otherwise
 */
function crypto_onetimeauth_verify(hash, message, key);

/**
 * Generates a random one-time authentication key
 * @returns 32-byte one-time key
 */
function crypto_onetimeauth_keygen();

// Streaming operations
function crypto_onetimeauth_init(key);
function crypto_onetimeauth_update(state_address, message_chunk);
function crypto_onetimeauth_final(state_address);

Usage Examples

Basic Authentication:

// Generate key and authenticate message
const key = sodium.crypto_auth_keygen();
const message = sodium.from_string("Important message");
const tag = sodium.crypto_auth(message, key);

// Verify authentication
const isValid = sodium.crypto_auth_verify(tag, message, key);
console.log(isValid); // true

// Tampered message fails verification
const tamperedMessage = sodium.from_string("Tampered message");
const stillValid = sodium.crypto_auth_verify(tag, tamperedMessage, key);
console.log(stillValid); // false

Streaming Authentication:

// Authenticate large message in chunks
const key = sodium.crypto_auth_hmacsha256_keygen();
let state = sodium.crypto_auth_hmacsha256_init(key);

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

const tag = sodium.crypto_auth_hmacsha256_final(state);

Constants

// Generic Auth
const crypto_auth_BYTES = 32;           // Tag size
const crypto_auth_KEYBYTES = 32;        // Key size

// HMAC-SHA256
const crypto_auth_hmacsha256_BYTES = 32;
const crypto_auth_hmacsha256_KEYBYTES = 32;

// HMAC-SHA512
const crypto_auth_hmacsha512_BYTES = 64;
const crypto_auth_hmacsha512_KEYBYTES = 32;

// HMAC-SHA512-256
const crypto_auth_hmacsha512256_BYTES = 32;
const crypto_auth_hmacsha512256_KEYBYTES = 32;

// One-time Auth (Poly1305)
const crypto_onetimeauth_BYTES = 16;
const crypto_onetimeauth_KEYBYTES = 32;

Security Considerations

Key Management: Authentication keys must be kept secret and generated securely
One-time Keys: Poly1305 keys must never be reused - each message needs a fresh key
Verification: Always use constant-time verification functions to prevent timing attacks
Key Derivation: Don't use passwords directly as keys - derive them using proper KDF functions
Algorithm Choice: Use generic auth (HMAC-SHA512-256) for new applications unless specific requirements dictate otherwise