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

Stream Ciphers

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

Stream cipher encryption provides fast encryption/decryption without authentication. Unlike authenticated encryption, stream ciphers only provide confidentiality and are vulnerable to bit-flipping attacks if used without additional authentication. Use authenticated encryption (AEAD) unless you have specific requirements for stream ciphers.

Capabilities

ChaCha20 Stream Cipher

High-speed stream cipher providing encryption without authentication. Suitable for applications requiring maximum performance where authentication is handled separately.

/**
 * Generate ChaCha20 stream cipher key
 * @returns Uint8Array - 32-byte key for ChaCha20
 */
function crypto_stream_chacha20_keygen();

/**
 * Encrypt/decrypt data using ChaCha20 stream cipher
 * @param input_message - Data to encrypt or decrypt
 * @param nonce - 8-byte nonce (must be unique for each message with same key)
 * @param key - 32-byte ChaCha20 key
 * @returns Uint8Array - Encrypted/decrypted data (same length as input)
 */
function crypto_stream_chacha20_xor(input_message, nonce, key);

/**
 * Encrypt/decrypt data using ChaCha20 with counter
 * @param input_message - Data to encrypt or decrypt
 * @param nonce - 8-byte nonce
 * @param counter - Starting counter value
 * @param key - 32-byte ChaCha20 key
 * @returns Uint8Array - Encrypted/decrypted data
 */
function crypto_stream_chacha20_xor_ic(input_message, nonce, counter, key);

/**
 * Generate ChaCha20 keystream
 * @param length - Length of keystream to generate
 * @param nonce - 8-byte nonce
 * @param key - 32-byte ChaCha20 key
 * @returns Uint8Array - Generated keystream
 */
function crypto_stream_chacha20(length, nonce, key);

Usage Example:

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

// Generate key and nonce
const key = sodium.crypto_stream_chacha20_keygen();
const nonce = sodium.randombytes_buf(8); // ChaCha20 uses 8-byte nonce

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

// Decrypt message (same operation)
const decrypted = sodium.crypto_stream_chacha20_xor(ciphertext, nonce, key);
const plaintext = sodium.to_string(decrypted);
console.log(plaintext); // "Hello, World!"

ChaCha20 IETF Stream Cipher

IETF variant of ChaCha20 with 12-byte nonce and 32-bit counter, compatible with RFC 8439.

/**
 * Encrypt/decrypt data using ChaCha20-IETF with 12-byte nonce
 * @param input_message - Data to encrypt or decrypt
 * @param nonce - 12-byte nonce (IETF standard)
 * @param key - 32-byte ChaCha20 key
 * @returns Uint8Array - Encrypted/decrypted data
 */
function crypto_stream_chacha20_ietf_xor(input_message, nonce, key);

/**
 * Encrypt/decrypt data using ChaCha20-IETF with counter
 * @param input_message - Data to encrypt or decrypt  
 * @param nonce - 12-byte nonce
 * @param counter - Starting counter value
 * @param key - 32-byte ChaCha20 key
 * @returns Uint8Array - Encrypted/decrypted data
 */
function crypto_stream_chacha20_ietf_xor_ic(input_message, nonce, counter, key);

XChaCha20 Stream Cipher

Extended ChaCha20 with 24-byte nonce, providing better security margins for random nonce generation.

/**
 * Generate XChaCha20 stream cipher key
 * @returns Uint8Array - 32-byte key for XChaCha20
 */
function crypto_stream_xchacha20_keygen();

/**
 * Encrypt/decrypt data using XChaCha20 stream cipher
 * @param input_message - Data to encrypt or decrypt
 * @param nonce - 24-byte nonce (can be randomly generated)
 * @param key - 32-byte XChaCha20 key
 * @returns Uint8Array - Encrypted/decrypted data
 */
function crypto_stream_xchacha20_xor(input_message, nonce, key);

/**
 * Encrypt/decrypt data using XChaCha20 with counter
 * @param input_message - Data to encrypt or decrypt
 * @param nonce - 24-byte nonce
 * @param counter - Starting counter value
 * @param key - 32-byte XChaCha20 key
 * @returns Uint8Array - Encrypted/decrypted data
 */
function crypto_stream_xchacha20_xor_ic(input_message, nonce, counter, key);

Usage Example:

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

// XChaCha20 with 24-byte nonce (can be random)
const key = sodium.crypto_stream_xchacha20_keygen();
const nonce = sodium.randombytes_buf(24); // XChaCha20 uses 24-byte nonce

const message = sodium.from_string('Secure message');
const encrypted = sodium.crypto_stream_xchacha20_xor(message, nonce, key);
const decrypted = sodium.crypto_stream_xchacha20_xor(encrypted, nonce, key);

Generic Stream Cipher

Generic stream cipher interface providing default algorithm selection.

/**
 * Generate generic stream cipher key
 * @returns Uint8Array - Key for default stream cipher
 */
function crypto_stream_keygen();

Constants

Stream cipher constants for buffer sizes and parameters:

// ChaCha20 constants
const crypto_stream_chacha20_KEYBYTES; // 32
const crypto_stream_chacha20_NONCEBYTES; // 8
const crypto_stream_chacha20_ietf_NONCEBYTES; // 12

// XChaCha20 constants  
const crypto_stream_xchacha20_KEYBYTES; // 32
const crypto_stream_xchacha20_NONCEBYTES; // 24

// Generic stream constants
const crypto_stream_KEYBYTES; // 32
const crypto_stream_NONCEBYTES; // 24

Security Considerations

Important Security Notes:

No Authentication: Stream ciphers provide only encryption, not authentication
Nonce Reuse: Never reuse a nonce with the same key - this breaks security completely
Bit-Flipping Attacks: Attackers can flip bits in ciphertext to modify plaintext
Use AEAD Instead: For most applications, use authenticated encryption (ChaCha20-Poly1305) instead

When to Use Stream Ciphers:

Performance-critical applications where authentication is handled separately
Protocols that implement authentication at a higher layer
Compatibility with existing systems that require raw stream ciphers
Bulk encryption where separate authentication is more efficient

Best Practices:

Generate nonces randomly for XChaCha20 (24-byte nonce provides sufficient collision resistance)
Use counters or sequential nonces for ChaCha20 (8-byte nonce requires careful nonce management)
Always authenticate encrypted data using separate MAC or signature
Consider using authenticated encryption (AEAD) unless you have specific requirements