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

libsodium-wrappers

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

libsodium-wrappers is a comprehensive JavaScript cryptographic library that provides wrappers for the Sodium cryptographic library. It offers a complete cryptographic toolkit compiled to WebAssembly and pure JavaScript, enabling secure cryptographic operations in web browsers and Node.js environments with automatic fallback support.

Package Information

Package Name: libsodium-wrappers
Package Type: npm
Language: JavaScript
Installation: npm install libsodium-wrappers

Core Imports

// Wait for the library to be ready before use
const sodium = require('libsodium-wrappers');
await sodium.ready;

For ES modules:

import sodium from 'libsodium-wrappers';
await sodium.ready;

Basic Usage

const sodium = require('libsodium-wrappers');
await sodium.ready;

// Generate a key for secret-key encryption
const key = sodium.crypto_secretbox_keygen();
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);

// Encrypt a message
const message = sodium.from_string('Hello, World!');
const ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);

// Decrypt the message
const decrypted = sodium.crypto_secretbox_open_easy(ciphertext, nonce, key);
const plaintextString = sodium.to_string(decrypted);
console.log(plaintextString); // "Hello, World!"

Architecture

libsodium-wrappers is built around several key components:

WebAssembly Core: Primary implementation using WebAssembly for performance
JavaScript Fallback: Pure JavaScript implementation for compatibility
Automatic Format Conversion: Built-in utilities for string/binary/hex/base64 conversion
Memory Management: Automatic WebAssembly heap management
Type Safety: Consistent Uint8Array interface for all binary data
Cross-Platform: Full compatibility across browsers and Node.js environments

Capabilities

Authenticated Encryption (AEAD)

Modern authenticated encryption providing both confidentiality and authenticity. Supports multiple cipher suites including ChaCha20-Poly1305 and XChaCha20-Poly1305.

// ChaCha20-Poly1305 IETF (recommended)
function crypto_aead_chacha20poly1305_ietf_encrypt(message, additional_data, secret_nonce, public_nonce, key);
function crypto_aead_chacha20poly1305_ietf_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
function crypto_aead_chacha20poly1305_ietf_keygen();

Authenticated Encryption

Public-Key Encryption

Elliptic curve-based public-key encryption for secure communication between parties. Uses Curve25519 for key exchange and ChaCha20-Poly1305 for encryption.

function crypto_box_keypair();
function crypto_box_easy(message, nonce, publicKey, privateKey);
function crypto_box_open_easy(ciphertext, nonce, publicKey, privateKey);
function crypto_box_seal(message, publicKey);
function crypto_box_seal_open(ciphertext, publicKey, secretKey);

Public-Key Encryption

Digital Signatures

Ed25519-based digital signatures for message authentication and non-repudiation.

function crypto_sign_keypair();
function crypto_sign(message, privateKey);
function crypto_sign_open(signedMessage, publicKey);
function crypto_sign_detached(message, privateKey);
function crypto_sign_verify_detached(signature, message, publicKey);

Digital Signatures

Secret-Key Encryption

Fast symmetric encryption for encrypting data with a shared secret key. Uses XSalsa20 stream cipher with Poly1305 authentication.

function crypto_secretbox_keygen();
function crypto_secretbox_easy(message, nonce, key);
function crypto_secretbox_open_easy(ciphertext, nonce, key);

Secret-Key Encryption

Hashing and Key Derivation

Cryptographic hash functions and key derivation functions for data integrity and key management.

// Generic hash (BLAKE2b)
function crypto_generichash(hash_length, message, key);

// Key derivation
function crypto_kdf_derive_from_key(subkey_len, subkey_id, ctx, key);
function crypto_kdf_keygen();

// Standard hashes
function crypto_hash(message); // SHA-512
function crypto_hash_sha256(message);

Hashing and Key Derivation

Message Authentication

MAC (Message Authentication Code) functions for verifying message integrity and authenticity.

function crypto_auth(message, key);
function crypto_auth_verify(tag, message, key);
function crypto_auth_keygen();

Message Authentication

Password Hashing

Secure password hashing using Argon2 and Scrypt algorithms, designed to be resistant to brute-force attacks.

function crypto_pwhash_str(password, opsLimit, memLimit);
function crypto_pwhash_str_verify(hashed_password, password);
function crypto_pwhash_str_needs_rehash(hashed_password, opsLimit, memLimit);

Password Hashing

Key Exchange

Secure key exchange protocols for establishing shared secrets between parties.

function crypto_kx_keypair();
function crypto_kx_client_session_keys(clientPublicKey, clientSecretKey, serverPublicKey);
function crypto_kx_server_session_keys(serverPublicKey, serverSecretKey, clientPublicKey);

Key Exchange

Random Number Generation

Cryptographically secure random number generation for keys, nonces, and other security-critical values.

function randombytes_buf(length);
function randombytes_uniform(upper_bound);
function randombytes_random();

Random Number Generation

Stream Ciphers

Fast encryption without authentication for performance-critical applications and custom protocol implementations.

function crypto_stream_chacha20_keygen();
function crypto_stream_chacha20_xor(input_message, nonce, key);
function crypto_stream_xchacha20_keygen();
function crypto_stream_xchacha20_xor(input_message, nonce, key);

Stream Ciphers

Advanced Cryptographic Operations

Low-level elliptic curve operations and core primitives for advanced cryptographic protocols and zero-knowledge proofs.

function crypto_core_ed25519_add(p, q);
function crypto_core_ed25519_scalar_random();
function crypto_core_ristretto255_add(p, q);
function crypto_core_hchacha20(input, key, constant);

Advanced Cryptographic Operations

Data Utilities

Helper functions for data format conversion, binary operations, and memory management.

// Format conversion
function from_string(str);
function to_string(bytes);
function from_hex(hexString);
function to_hex(bytes);
function from_base64(base64String, variant);
function to_base64(bytes, variant);

// Binary operations
function compare(a, b);
function memcmp(a, b);
function increment(bytes);
function add(a, b);

Data Utilities

Global Constants

The library exposes numerous constants for buffer sizes, algorithm parameters, and configuration values. All constants follow the pattern crypto_[algorithm]_[PARAMETER].

// Example constants
const crypto_secretbox_KEYBYTES; // 32
const crypto_secretbox_NONCEBYTES; // 24
const crypto_box_PUBLICKEYBYTES; // 32
const crypto_sign_BYTES; // 64
const crypto_generichash_BYTES; // 32

Initialization

The library must be initialized before use:

const sodium = require('libsodium-wrappers');

// Wait for WebAssembly module to load
await sodium.ready;

// Now you can use all cryptographic functions
const key = sodium.crypto_secretbox_keygen();

Error Handling

Functions throw JavaScript Error objects for invalid inputs, cryptographic failures, or initialization problems:

try {
  const result = sodium.crypto_secretbox_open_easy(ciphertext, nonce, wrongkey);
} catch (error) {
  console.error('Decryption failed:', error.message);
  // Handle decryption failure
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/libsodium-wrappers@0.7.x
Publish Source: CLI
Badge