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

Authenticated Encryption (AEAD)

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

Authenticated Encryption with Associated Data (AEAD) provides both confidentiality and authenticity in a single operation. libsodium-wrappers supports multiple AEAD cipher suites optimized for different use cases.

Capabilities

ChaCha20-Poly1305 IETF (Recommended)

The recommended AEAD construction using ChaCha20 stream cipher with Poly1305 authenticator, following the IETF specification.

/**
 * Encrypts a message using ChaCha20-Poly1305 IETF
 * @param message - The plaintext message to encrypt
 * @param additional_data - Optional additional data to authenticate (but not encrypt)
 * @param secret_nonce - Optional secret nonce (usually null)
 * @param public_nonce - 12-byte public nonce
 * @param key - 32-byte encryption key
 * @returns Encrypted ciphertext with authentication tag
 */
function crypto_aead_chacha20poly1305_ietf_encrypt(message, additional_data, secret_nonce, public_nonce, key);

/**
 * Decrypts a message using ChaCha20-Poly1305 IETF
 * @param secret_nonce - Optional secret nonce (usually null)
 * @param ciphertext - The ciphertext to decrypt
 * @param additional_data - Additional data that was authenticated during encryption
 * @param public_nonce - 12-byte public nonce used during encryption
 * @param key - 32-byte encryption key
 * @returns Decrypted plaintext message
 * @throws Error if authentication fails or ciphertext is invalid
 */
function crypto_aead_chacha20poly1305_ietf_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);

/**
 * Generates a random 32-byte key for ChaCha20-Poly1305 IETF
 * @returns 32-byte encryption key
 */
function crypto_aead_chacha20poly1305_ietf_keygen();

/**
 * Encrypts a message using ChaCha20-Poly1305 IETF with detached authentication tag
 * @param message - The plaintext message to encrypt
 * @param additional_data - Optional additional data to authenticate
 * @param secret_nonce - Optional secret nonce (usually null)
 * @param public_nonce - 12-byte public nonce
 * @param key - 32-byte encryption key
 * @returns Object with separate ciphertext and mac properties
 */
function crypto_aead_chacha20poly1305_ietf_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);

/**
 * Decrypts a message using ChaCha20-Poly1305 IETF with detached authentication tag
 * @param secret_nonce - Optional secret nonce (usually null)
 * @param ciphertext - The ciphertext to decrypt
 * @param mac - The detached authentication tag
 * @param additional_data - Additional data that was authenticated during encryption
 * @param public_nonce - 12-byte public nonce used during encryption
 * @param key - 32-byte encryption key
 * @returns Decrypted plaintext message
 */
function crypto_aead_chacha20poly1305_ietf_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);

Usage Example:

// Generate key and nonce
const key = sodium.crypto_aead_chacha20poly1305_ietf_keygen();
const nonce = sodium.randombytes_buf(sodium.crypto_aead_chacha20poly1305_ietf_NPUBBYTES);

// Encrypt with additional authenticated data
const message = sodium.from_string("Secret message");
const additionalData = sodium.from_string("public metadata");
const ciphertext = sodium.crypto_aead_chacha20poly1305_ietf_encrypt(
  message, additionalData, null, nonce, key
);

// Decrypt
const decrypted = sodium.crypto_aead_chacha20poly1305_ietf_decrypt(
  null, ciphertext, additionalData, nonce, key
);
console.log(sodium.to_string(decrypted)); // "Secret message"

XChaCha20-Poly1305 IETF

Extended nonce version of ChaCha20-Poly1305 with 24-byte nonces, providing better resistance to nonce reuse.

/**
 * Encrypts a message using XChaCha20-Poly1305 IETF
 * @param message - The plaintext message to encrypt
 * @param additional_data - Optional additional data to authenticate
 * @param secret_nonce - Optional secret nonce (usually null)
 * @param public_nonce - 24-byte public nonce
 * @param key - 32-byte encryption key
 * @returns Encrypted ciphertext with authentication tag
 */
function crypto_aead_xchacha20poly1305_ietf_encrypt(message, additional_data, secret_nonce, public_nonce, key);

/**
 * Decrypts a message using XChaCha20-Poly1305 IETF
 * @param secret_nonce - Optional secret nonce (usually null)
 * @param ciphertext - The ciphertext to decrypt
 * @param additional_data - Additional data that was authenticated during encryption
 * @param public_nonce - 24-byte public nonce used during encryption
 * @param key - 32-byte encryption key
 * @returns Decrypted plaintext message
 */
function crypto_aead_xchacha20poly1305_ietf_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);

/**
 * Generates a random 32-byte key for XChaCha20-Poly1305 IETF
 * @returns 32-byte encryption key
 */
function crypto_aead_xchacha20poly1305_ietf_keygen();

function crypto_aead_xchacha20poly1305_ietf_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);
function crypto_aead_xchacha20poly1305_ietf_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);

ChaCha20-Poly1305 (Original)

Original ChaCha20-Poly1305 construction with 8-byte nonces.

function crypto_aead_chacha20poly1305_encrypt(message, additional_data, secret_nonce, public_nonce, key);
function crypto_aead_chacha20poly1305_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
function crypto_aead_chacha20poly1305_keygen();
function crypto_aead_chacha20poly1305_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);
function crypto_aead_chacha20poly1305_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);

AEGIS-128L

High-performance AEAD cipher optimized for modern CPUs with AES acceleration.

function crypto_aead_aegis128l_encrypt(message, additional_data, secret_nonce, public_nonce, key);
function crypto_aead_aegis128l_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
function crypto_aead_aegis128l_keygen();
function crypto_aead_aegis128l_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);
function crypto_aead_aegis128l_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);

AEGIS-256

Higher security version of AEGIS with 256-bit keys.

function crypto_aead_aegis256_encrypt(message, additional_data, secret_nonce, public_nonce, key);
function crypto_aead_aegis256_decrypt(secret_nonce, ciphertext, additional_data, public_nonce, key);
function crypto_aead_aegis256_keygen();
function crypto_aead_aegis256_encrypt_detached(message, additional_data, secret_nonce, public_nonce, key);
function crypto_aead_aegis256_decrypt_detached(secret_nonce, ciphertext, mac, additional_data, public_nonce, key);

Constants

// ChaCha20-Poly1305 IETF
const crypto_aead_chacha20poly1305_ietf_KEYBYTES = 32;
const crypto_aead_chacha20poly1305_ietf_NPUBBYTES = 12;
const crypto_aead_chacha20poly1305_ietf_ABYTES = 16;

// XChaCha20-Poly1305 IETF  
const crypto_aead_xchacha20poly1305_ietf_KEYBYTES = 32;
const crypto_aead_xchacha20poly1305_ietf_NPUBBYTES = 24;
const crypto_aead_xchacha20poly1305_ietf_ABYTES = 16;

// ChaCha20-Poly1305 (Original)
const crypto_aead_chacha20poly1305_KEYBYTES = 32;
const crypto_aead_chacha20poly1305_NPUBBYTES = 8;
const crypto_aead_chacha20poly1305_ABYTES = 16;

// AEGIS-128L
const crypto_aead_aegis128l_KEYBYTES = 16;
const crypto_aead_aegis128l_NPUBBYTES = 16;
const crypto_aead_aegis128l_ABYTES = 32;

// AEGIS-256
const crypto_aead_aegis256_KEYBYTES = 32;
const crypto_aead_aegis256_NPUBBYTES = 16;
const crypto_aead_aegis256_ABYTES = 32;

Security Considerations

Nonce Reuse: Never reuse the same nonce with the same key. Use random nonces or a counter-based approach.
Key Management: Generate keys using the provided keygen functions or a cryptographically secure random source.
Additional Data: Additional data is authenticated but not encrypted. Use for metadata that needs integrity but not confidentiality.
Algorithm Choice: ChaCha20-Poly1305 IETF is recommended for most applications. Use XChaCha20-Poly1305 IETF when you need larger nonces or better nonce misuse resistance.