or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aead.mdauth.mdbox.mdhash.mdindex.mdkey-derivation.mdsecretbox.mdsign.mdstreaming.mdutilities.md
tile.json

tessl/npm-libsodium-wrappers-sumo

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/libsodium-wrappers-sumo@0.7.x

To install, run

npx @tessl/cli install tessl/npm-libsodium-wrappers-sumo@0.7.0

index.mddocs/

libsodium-wrappers-sumo

The Sodium cryptographic library compiled to pure JavaScript with comprehensive WASM support. This is the "sumo" variant that includes the complete libsodium API with 188 functions across 18 categories, providing high-performance cryptographic operations for both browser and Node.js environments.

Package Information

  • Package Name: libsodium-wrappers-sumo
  • Package Type: npm
  • Version: 0.7.15
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install libsodium-wrappers-sumo

Core Imports

The library uses an asynchronous initialization pattern with a .ready promise:

import _sodium from 'libsodium-wrappers-sumo';

// Wait for library initialization
await _sodium.ready;
const sodium = _sodium;

// Now all functions are available
const key = sodium.crypto_secretbox_keygen();

For CommonJS:

const _sodium = require('libsodium-wrappers-sumo');

(async () => {
  await _sodium.ready;
  const sodium = _sodium;
  // Use sodium functions here
})();

Basic Usage

import _sodium from 'libsodium-wrappers-sumo';

await _sodium.ready;
const sodium = _sodium;

// Generate a random key
const key = sodium.crypto_secretbox_keygen();

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

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

Architecture

libsodium-wrappers-sumo is built around several key components:

  • WebAssembly Core: High-performance cryptographic operations compiled from C libsodium
  • JavaScript Wrappers: Type-safe API wrappers with automatic memory management
  • Utility Functions: Data conversion and manipulation helpers for seamless integration
  • Constant Definitions: All cryptographic constants and parameters
  • Error Handling: Comprehensive error checking and clear error messages

The library provides:

  • Memory Safety: Automatic management of cryptographic memory
  • Type Consistency: Standardized Uint8Array inputs/outputs
  • Cross-Platform: Works in browsers, Node.js, and web workers
  • Performance: WASM-based implementation with pure JS fallback

Library Constants

The library provides access to version information and all cryptographic constants:

// Version information
const SODIUM_LIBRARY_VERSION_MAJOR: number;
const SODIUM_LIBRARY_VERSION_MINOR: number; 
const SODIUM_VERSION_STRING: string;

// Example: crypto_secretbox constants
const crypto_secretbox_KEYBYTES: number;     // 32
const crypto_secretbox_NONCEBYTES: number;   // 24
const crypto_secretbox_MACBYTES: number;     // 16

Capabilities

Authenticated Encryption with Associated Data (AEAD)

High-performance authenticated encryption supporting multiple algorithms including ChaCha20-Poly1305, XChaCha20-Poly1305, AES-256-GCM, and AEGIS variants. Provides both confidentiality and authenticity in a single operation.

// XChaCha20-Poly1305 (recommended for most use cases)
const key = sodium.crypto_aead_xchacha20poly1305_ietf_keygen();
const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(
  message, additionalData, null, nonce, key
);

// AEGIS-256 (high performance)
const key = sodium.crypto_aead_aegis256_keygen();
const ciphertext = sodium.crypto_aead_aegis256_encrypt(message, ad, null, nonce, key);

AEAD Documentation

Message Authentication

HMAC-based message authentication with SHA-256, SHA-512, and SHA-512/256 variants. Provides cryptographic proof of message authenticity and integrity.

// HMAC-SHA256 authentication
const key = sodium.crypto_auth_hmacsha256_keygen();
const tag = sodium.crypto_auth_hmacsha256(message, key);
const isValid = sodium.crypto_auth_hmacsha256_verify(tag, message, key);

// Generic auth (defaults to HMAC-SHA512/256)
const tag = sodium.crypto_auth(message, key);

Message Authentication Documentation

Public-Key Encryption (Box)

Curve25519-based public-key encryption supporting multiple cipher variants. Enables secure communication between parties with public key infrastructure.

// Generate keypair
const { publicKey, privateKey } = sodium.crypto_box_keypair();

// Encrypt (authenticated encryption)
const nonce = sodium.randombytes_buf(sodium.crypto_box_NONCEBYTES);
const ciphertext = sodium.crypto_box_easy(message, nonce, recipientPublicKey, senderPrivateKey);

// Sealed box (anonymous encryption)
const sealed = sodium.crypto_box_seal(message, recipientPublicKey);

Public-Key Encryption Documentation

Secret-Key Encryption (SecretBox)

Fast symmetric encryption with XSalsa20 and XChaCha20 stream ciphers combined with Poly1305 authentication. Ideal for encrypting data with shared secrets.

// Generate key
const key = sodium.crypto_secretbox_keygen();

// Encrypt
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
const ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);

// Decrypt
const plaintext = sodium.crypto_secretbox_open_easy(ciphertext, nonce, key);

Secret-Key Encryption Documentation

Digital Signatures

Ed25519-based digital signatures providing message authentication, integrity, and non-repudiation. Supports both attached and detached signature modes.

// Generate signing keypair
const { publicKey, privateKey } = sodium.crypto_sign_keypair();

// Create detached signature
const signature = sodium.crypto_sign_detached(message, privateKey);

// Verify signature
const isValid = sodium.crypto_sign_verify_detached(signature, message, publicKey);

Digital Signatures Documentation

Hashing

Comprehensive hashing functions including BLAKE2b (generic hash), SHA-256, and SHA-512. Supports both one-shot and streaming operations.

// BLAKE2b generic hash
const hash = sodium.crypto_generichash(32, message);
const hash_with_key = sodium.crypto_generichash(32, message, key);

// SHA-256 and SHA-512
const sha256 = sodium.crypto_hash_sha256(message);
const sha512 = sodium.crypto_hash_sha512(message);

Hashing Documentation

Key Derivation and Exchange

Key derivation functions (KDF) and key exchange (KX) protocols for generating multiple keys from a master key and establishing shared secrets between parties.

// Key derivation
const masterKey = sodium.crypto_kdf_keygen();
const subkey = sodium.crypto_kdf_derive_from_key(32, 1, 'context_', masterKey);

// Key exchange
const client = sodium.crypto_kx_keypair();
const server = sodium.crypto_kx_keypair();
const { sharedRx, sharedTx } = sodium.crypto_kx_client_session_keys(
  client.publicKey, client.privateKey, server.publicKey
);

Key Derivation and Exchange Documentation

Streaming Operations

Streaming encryption and stream cipher operations for handling large data efficiently or implementing custom protocols.

// Secret stream (XChaCha20-Poly1305)
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
const { state, header } = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);

// Stream cipher  
const key = sodium.crypto_stream_chacha20_keygen();
const stream = sodium.crypto_stream_chacha20(64, key, nonce);

Streaming Operations Documentation

Utilities and Helpers

Random number generation, data conversion utilities, memory operations, and various helper functions for cryptographic operations.

// Random generation
const randomBytes = sodium.randombytes_buf(32);
const randomInt = sodium.randombytes_uniform(100);

// Data conversion
const bytes = sodium.from_string('hello');
const hex = sodium.to_hex(bytes);
const base64 = sodium.to_base64(bytes);

// Memory operations
const isEqual = sodium.memcmp(buffer1, buffer2);
sodium.memzero(sensitiveData);

Utilities Documentation