CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-libsodium-wrappers-sumo

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

aead.mddocs/

Authenticated Encryption with Associated Data (AEAD)

AEAD functions provide encryption that ensures both confidentiality and authenticity. They encrypt the plaintext and authenticate both the encrypted data and optional associated data in a single operation.

Supported Algorithms

  • XChaCha20-Poly1305: Extended nonce variant, recommended for most applications
  • ChaCha20-Poly1305: Fast, secure cipher with good cross-platform performance
  • AEGIS-128L/256: High-performance AEAD ciphers with hardware acceleration
  • AES-256-GCM: Hardware-accelerated cipher on supporting platforms

XChaCha20-Poly1305 (Recommended)

The extended nonce variant of ChaCha20-Poly1305, allowing for random nonce generation without collision concerns.

Key Generation

/**
 * Generate a random key for XChaCha20-Poly1305 AEAD
 * @returns Uint8Array - 32-byte key
 */
function crypto_aead_xchacha20poly1305_ietf_keygen(): Uint8Array;

Encryption

/**
 * Encrypt and authenticate data using XChaCha20-Poly1305
 * @param message - The plaintext data to encrypt
 * @param additional_data - Additional data to authenticate (not encrypted)
 * @param secret_nonce - Secret nonce (usually null)
 * @param public_nonce - 24-byte nonce (can be random)
 * @param key - 32-byte encryption key
 * @returns Uint8Array - Encrypted data with authentication tag
 */
function crypto_aead_xchacha20poly1305_ietf_encrypt(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

Decryption

/**
 * Decrypt and verify data using XChaCha20-Poly1305
 * @param secret_nonce - Secret nonce (usually null)
 * @param ciphertext - Encrypted data with authentication tag
 * @param additional_data - Additional authenticated data
 * @param public_nonce - 24-byte nonce used for encryption
 * @param key - 32-byte decryption key
 * @returns Uint8Array - Decrypted plaintext
 * @throws Error if authentication fails
 */
function crypto_aead_xchacha20poly1305_ietf_decrypt(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

Detached Operations

/**
 * Encrypt data with detached authentication tag
 * @param message - Plaintext to encrypt
 * @param additional_data - Additional authenticated data
 * @param secret_nonce - Secret nonce (usually null)
 * @param public_nonce - 24-byte nonce
 * @param key - 32-byte encryption key
 * @returns Object with ciphertext and mac properties
 */
function crypto_aead_xchacha20poly1305_ietf_encrypt_detached(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): { ciphertext: Uint8Array; mac: Uint8Array };

/**
 * Decrypt data with separate authentication tag
 * @param secret_nonce - Secret nonce (usually null)
 * @param ciphertext - Encrypted data (without tag)
 * @param mac - Authentication tag
 * @param additional_data - Additional authenticated data
 * @param public_nonce - 24-byte nonce
 * @param key - 32-byte decryption key
 * @returns Uint8Array - Decrypted plaintext
 * @throws Error if authentication fails
 */
function crypto_aead_xchacha20poly1305_ietf_decrypt_detached(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  mac: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

Constants

const crypto_aead_xchacha20poly1305_ietf_KEYBYTES: number;     // 32
const crypto_aead_xchacha20poly1305_ietf_NPUBBYTES: number;    // 24
const crypto_aead_xchacha20poly1305_ietf_ABYTES: number;       // 16
const crypto_aead_xchacha20poly1305_ietf_NSECBYTES: number;    // 0
const crypto_aead_xchacha20poly1305_ietf_MESSAGEBYTES_MAX: number; // Large value

ChaCha20-Poly1305 IETF

Standard ChaCha20-Poly1305 with IETF-compatible nonce size.

Key Generation

function crypto_aead_chacha20poly1305_ietf_keygen(): Uint8Array;

Encryption and Decryption

function crypto_aead_chacha20poly1305_ietf_encrypt(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,  // 12 bytes
  key: Uint8Array
): Uint8Array;

function crypto_aead_chacha20poly1305_ietf_decrypt(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,  // 12 bytes
  key: Uint8Array
): Uint8Array;

Detached Operations

function crypto_aead_chacha20poly1305_ietf_encrypt_detached(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): { ciphertext: Uint8Array; mac: Uint8Array };

function crypto_aead_chacha20poly1305_ietf_decrypt_detached(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  mac: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

Constants

const crypto_aead_chacha20poly1305_ietf_KEYBYTES: number;      // 32
const crypto_aead_chacha20poly1305_ietf_NPUBBYTES: number;     // 12
const crypto_aead_chacha20poly1305_ietf_ABYTES: number;        // 16
const crypto_aead_chacha20poly1305_ietf_NSECBYTES: number;     // 0

AEGIS-256

High-performance AEAD cipher with excellent security properties.

Key Generation

function crypto_aead_aegis256_keygen(): Uint8Array;

Encryption and Decryption

function crypto_aead_aegis256_encrypt(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,  // 32 bytes
  key: Uint8Array
): Uint8Array;

function crypto_aead_aegis256_decrypt(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

Detached Operations

function crypto_aead_aegis256_encrypt_detached(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): { ciphertext: Uint8Array; mac: Uint8Array };

function crypto_aead_aegis256_decrypt_detached(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  mac: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

Constants

const crypto_aead_aegis256_KEYBYTES: number;      // 32
const crypto_aead_aegis256_NPUBBYTES: number;     // 32
const crypto_aead_aegis256_ABYTES: number;        // 32
const crypto_aead_aegis256_NSECBYTES: number;     // 0

AEGIS-128L

Faster variant of AEGIS with 128-bit security level.

API Functions

function crypto_aead_aegis128l_keygen(): Uint8Array;

function crypto_aead_aegis128l_encrypt(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,  // 16 bytes
  key: Uint8Array
): Uint8Array;

function crypto_aead_aegis128l_decrypt(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

function crypto_aead_aegis128l_encrypt_detached(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): { ciphertext: Uint8Array; mac: Uint8Array };

function crypto_aead_aegis128l_decrypt_detached(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  mac: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

Constants

const crypto_aead_aegis128l_KEYBYTES: number;      // 16
const crypto_aead_aegis128l_NPUBBYTES: number;     // 16
const crypto_aead_aegis128l_ABYTES: number;        // 32
const crypto_aead_aegis128l_NSECBYTES: number;     // 0

ChaCha20-Poly1305 (Original)

Original ChaCha20-Poly1305 with 8-byte nonce.

API Functions

function crypto_aead_chacha20poly1305_keygen(): Uint8Array;

function crypto_aead_chacha20poly1305_encrypt(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,  // 8 bytes
  key: Uint8Array
): Uint8Array;

function crypto_aead_chacha20poly1305_decrypt(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

function crypto_aead_chacha20poly1305_encrypt_detached(
  message: Uint8Array,
  additional_data: Uint8Array | null,
  secret_nonce: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): { ciphertext: Uint8Array; mac: Uint8Array };

function crypto_aead_chacha20poly1305_decrypt_detached(
  secret_nonce: Uint8Array | null,
  ciphertext: Uint8Array,
  mac: Uint8Array,
  additional_data: Uint8Array | null,
  public_nonce: Uint8Array,
  key: Uint8Array
): Uint8Array;

Constants

const crypto_aead_chacha20poly1305_KEYBYTES: number;       // 32
const crypto_aead_chacha20poly1305_NPUBBYTES: number;      // 8
const crypto_aead_chacha20poly1305_ABYTES: number;         // 16
const crypto_aead_chacha20poly1305_NSECBYTES: number;      // 0

Usage Examples

Basic AEAD Encryption

import _sodium from 'libsodium-wrappers-sumo';
await _sodium.ready;
const sodium = _sodium;

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

// Prepare data
const message = sodium.from_string('Confidential message');
const additionalData = sodium.from_string('public header');
const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);

// Encrypt
const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(
  message, additionalData, null, nonce, key
);

// Decrypt
const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(
  null, ciphertext, additionalData, nonce, key
);

console.log(sodium.to_string(plaintext)); // "Confidential message"

Detached Authentication

// Encrypt with separate MAC
const { ciphertext, mac } = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt_detached(
  message, additionalData, null, nonce, key
);

// Store ciphertext and MAC separately
console.log('Ciphertext:', sodium.to_hex(ciphertext));
console.log('MAC:', sodium.to_hex(mac));

// Decrypt with separate MAC
const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt_detached(
  null, ciphertext, mac, additionalData, nonce, key
);

AEGIS High Performance

// For high-throughput applications
const key = sodium.crypto_aead_aegis256_keygen();
const nonce = sodium.randombytes_buf(sodium.crypto_aead_aegis256_NPUBBYTES);

const ciphertext = sodium.crypto_aead_aegis256_encrypt(
  message, additionalData, null, nonce, key
);

const plaintext = sodium.crypto_aead_aegis256_decrypt(
  null, ciphertext, additionalData, nonce, key
);

Algorithm Selection Guide

  • XChaCha20-Poly1305: Best general choice, safe random nonces
  • ChaCha20-Poly1305 IETF: Standards compliance, be careful with nonce reuse
  • AEGIS-256: Maximum performance for high-throughput applications
  • AEGIS-128L: Good performance with smaller keys and tags

All algorithms provide strong security when used correctly with unique nonces per key.

docs

aead.md

auth.md

box.md

hash.md

index.md

key-derivation.md

secretbox.md

sign.md

streaming.md

utilities.md

tile.json