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

Advanced Cryptographic Operations

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

Low-level cryptographic operations for advanced users implementing custom protocols, zero-knowledge proofs, and elliptic curve cryptography. These functions provide direct access to curve operations and should be used with caution.

Capabilities

Ed25519 Curve Operations

Direct elliptic curve operations on the Ed25519 curve for advanced cryptographic protocols.

/**
 * Adds two Ed25519 curve points
 * @param p - First curve point (32 bytes)
 * @param q - Second curve point (32 bytes) 
 * @returns Sum of the two points (32 bytes)
 */
function crypto_core_ed25519_add(p, q);

/**
 * Subtracts two Ed25519 curve points
 * @param p - First curve point (32 bytes)
 * @param q - Second curve point (32 bytes)
 * @returns Difference of the two points (32 bytes)
 */
function crypto_core_ed25519_sub(p, q);

/**
 * Converts hash to Ed25519 curve point
 * @param hash - 64-byte hash input
 * @returns Ed25519 curve point (32 bytes)
 */
function crypto_core_ed25519_from_hash(hash);

/**
 * Converts uniform bytes to Ed25519 curve point
 * @param bytes - 32-byte uniform input
 * @returns Ed25519 curve point (32 bytes)
 */
function crypto_core_ed25519_from_uniform(bytes);

/**
 * Validates if bytes represent a valid Ed25519 curve point
 * @param point - Potential curve point (32 bytes)
 * @returns true if valid, false otherwise
 */
function crypto_core_ed25519_is_valid_point(point);

/**
 * Generates a random Ed25519 curve point
 * @returns Random curve point (32 bytes)
 */
function crypto_core_ed25519_random();

Ed25519 Scalar Operations

Scalar arithmetic operations for Ed25519 curve scalars.

/**
 * Adds two Ed25519 scalars
 * @param x - First scalar (32 bytes)
 * @param y - Second scalar (32 bytes)
 * @returns Sum of scalars (32 bytes)
 */
function crypto_core_ed25519_scalar_add(x, y);

/**
 * Subtracts two Ed25519 scalars
 * @param x - First scalar (32 bytes)
 * @param y - Second scalar (32 bytes)
 * @returns Difference of scalars (32 bytes)
 */
function crypto_core_ed25519_scalar_sub(x, y);

/**
 * Multiplies two Ed25519 scalars
 * @param x - First scalar (32 bytes)
 * @param y - Second scalar (32 bytes)
 * @returns Product of scalars (32 bytes)
 */
function crypto_core_ed25519_scalar_mul(x, y);

/**
 * Negates an Ed25519 scalar
 * @param scalar - Input scalar (32 bytes)
 * @returns Negated scalar (32 bytes)
 */
function crypto_core_ed25519_scalar_negate(scalar);

/**
 * Computes multiplicative inverse of Ed25519 scalar
 * @param scalar - Input scalar (32 bytes)
 * @returns Inverted scalar (32 bytes)
 */
function crypto_core_ed25519_scalar_invert(scalar);

/**
 * Computes complement of Ed25519 scalar
 * @param scalar - Input scalar (32 bytes)
 * @returns Complement scalar (32 bytes)
 */
function crypto_core_ed25519_scalar_complement(scalar);

/**
 * Generates a random Ed25519 scalar
 * @returns Random scalar (32 bytes)
 */
function crypto_core_ed25519_scalar_random();

/**
 * Reduces bytes modulo Ed25519 curve order
 * @param bytes - Input bytes (64 bytes)
 * @returns Reduced scalar (32 bytes)
 */
function crypto_core_ed25519_scalar_reduce(bytes);

Ed25519 Usage Example:

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

// Generate random curve points and scalars
const point1 = sodium.crypto_core_ed25519_random();
const point2 = sodium.crypto_core_ed25519_random();
const scalar1 = sodium.crypto_core_ed25519_scalar_random();
const scalar2 = sodium.crypto_core_ed25519_scalar_random();

// Point arithmetic
const pointSum = sodium.crypto_core_ed25519_add(point1, point2);
const pointDiff = sodium.crypto_core_ed25519_sub(point1, point2);

// Scalar arithmetic
const scalarSum = sodium.crypto_core_ed25519_scalar_add(scalar1, scalar2);
const scalarProduct = sodium.crypto_core_ed25519_scalar_mul(scalar1, scalar2);

// Validate points
const isValid = sodium.crypto_core_ed25519_is_valid_point(point1);
console.log('Point is valid:', isValid);

Ristretto255 Curve Operations

Ristretto255 is a prime-order group built on top of Curve25519, designed for cryptographic protocols requiring a prime-order group.

/**
 * Adds two Ristretto255 group elements
 * @param p - First group element (32 bytes)
 * @param q - Second group element (32 bytes)
 * @returns Sum of the elements (32 bytes)
 */
function crypto_core_ristretto255_add(p, q);

/**
 * Subtracts two Ristretto255 group elements
 * @param p - First group element (32 bytes)
 * @param q - Second group element (32 bytes)
 * @returns Difference of the elements (32 bytes)
 */
function crypto_core_ristretto255_sub(p, q);

/**
 * Converts hash to Ristretto255 group element
 * @param hash - 64-byte hash input
 * @returns Ristretto255 group element (32 bytes)
 */
function crypto_core_ristretto255_from_hash(hash);

/**
 * Validates if bytes represent a valid Ristretto255 element
 * @param element - Potential group element (32 bytes)
 * @returns true if valid, false otherwise
 */
function crypto_core_ristretto255_is_valid_point(element);

/**
 * Generates a random Ristretto255 group element
 * @returns Random group element (32 bytes)
 */
function crypto_core_ristretto255_random();

Ristretto255 Scalar Operations

Scalar arithmetic for Ristretto255 group scalars.

/**
 * Adds two Ristretto255 scalars
 * @param x - First scalar (32 bytes)
 * @param y - Second scalar (32 bytes)
 * @returns Sum of scalars (32 bytes)
 */
function crypto_core_ristretto255_scalar_add(x, y);

/**
 * Subtracts two Ristretto255 scalars
 * @param x - First scalar (32 bytes)
 * @param y - Second scalar (32 bytes)
 * @returns Difference of scalars (32 bytes)
 */
function crypto_core_ristretto255_scalar_sub(x, y);

/**
 * Multiplies two Ristretto255 scalars
 * @param x - First scalar (32 bytes)
 * @param y - Second scalar (32 bytes)
 * @returns Product of scalars (32 bytes)
 */
function crypto_core_ristretto255_scalar_mul(x, y);

/**
 * Negates a Ristretto255 scalar
 * @param scalar - Input scalar (32 bytes)
 * @returns Negated scalar (32 bytes)
 */
function crypto_core_ristretto255_scalar_negate(scalar);

/**
 * Computes multiplicative inverse of Ristretto255 scalar
 * @param scalar - Input scalar (32 bytes)
 * @returns Inverted scalar (32 bytes)
 */
function crypto_core_ristretto255_scalar_invert(scalar);

/**
 * Computes complement of Ristretto255 scalar
 * @param scalar - Input scalar (32 bytes)
 * @returns Complement scalar (32 bytes)
 */
function crypto_core_ristretto255_scalar_complement(scalar);

/**
 * Generates a random Ristretto255 scalar
 * @returns Random scalar (32 bytes)
 */
function crypto_core_ristretto255_scalar_random();

/**
 * Reduces bytes modulo Ristretto255 curve order
 * @param bytes - Input bytes (64 bytes)
 * @returns Reduced scalar (32 bytes)
 */
function crypto_core_ristretto255_scalar_reduce(bytes);

Ristretto255 Usage Example:

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

// Generate random elements and scalars
const element1 = sodium.crypto_core_ristretto255_random();
const element2 = sodium.crypto_core_ristretto255_random();
const scalar = sodium.crypto_core_ristretto255_scalar_random();

// Group operations
const sum = sodium.crypto_core_ristretto255_add(element1, element2);
const difference = sodium.crypto_core_ristretto255_sub(element1, element2);

// Hash to curve for deterministic point generation
const hash = sodium.crypto_hash_sha512(sodium.from_string('seed data'));
const hashedPoint = sodium.crypto_core_ristretto255_from_hash(hash);

// Validate elements
const isValid = sodium.crypto_core_ristretto255_is_valid_point(element1);

Low-Level Core Functions

Core primitive functions for advanced cryptographic operations.

/**
 * HChaCha20 core function for XChaCha20 construction
 * @param input - 16-byte input block
 * @param key - 32-byte key
 * @param constant - 16-byte constant (can be null for default)
 * @returns 32-byte output
 */
function crypto_core_hchacha20(input, key, constant);

/**
 * HSalsa20 core function for XSalsa20 construction
 * @param input - 16-byte input block
 * @param key - 32-byte key
 * @param constant - 16-byte constant (can be null for default)
 * @returns 32-byte output
 */
function crypto_core_hsalsa20(input, key, constant);

Low-Level Usage Example:

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

// Use HChaCha20 for key derivation in XChaCha20
const key = sodium.randombytes_buf(32);
const nonce = sodium.randombytes_buf(16);

// Derive subkey using HChaCha20
const subkey = sodium.crypto_core_hchacha20(nonce, key, null);

// subkey can now be used with ChaCha20 with remaining nonce bytes
console.log('Derived subkey length:', subkey.length); // 32

Constants

Advanced cryptography constants for buffer sizes and parameters:

// Ed25519 constants
const crypto_core_ed25519_BYTES = 32;          // Curve point size
const crypto_core_ed25519_UNIFORMBYTES = 32;   // Uniform bytes size
const crypto_core_ed25519_HASHBYTES = 64;      // Hash input size
const crypto_core_ed25519_SCALARBYTES = 32;    // Scalar size
const crypto_core_ed25519_NONREDUCEDSCALARBYTES = 64; // Non-reduced scalar size

// Ristretto255 constants
const crypto_core_ristretto255_BYTES = 32;     // Group element size
const crypto_core_ristretto255_HASHBYTES = 64; // Hash input size
const crypto_core_ristretto255_SCALARBYTES = 32; // Scalar size
const crypto_core_ristretto255_NONREDUCEDSCALARBYTES = 64; // Non-reduced scalar size

// Core function constants
const crypto_core_hchacha20_INPUTBYTES = 16;   // HChaCha20 input size
const crypto_core_hchacha20_KEYBYTES = 32;     // HChaCha20 key size
const crypto_core_hchacha20_CONSTBYTES = 16;   // HChaCha20 constant size
const crypto_core_hchacha20_OUTPUTBYTES = 32;  // HChaCha20 output size

const crypto_core_hsalsa20_INPUTBYTES = 16;    // HSalsa20 input size
const crypto_core_hsalsa20_KEYBYTES = 32;      // HSalsa20 key size
const crypto_core_hsalsa20_CONSTBYTES = 16;    // HSalsa20 constant size
const crypto_core_hsalsa20_OUTPUTBYTES = 32;   // HSalsa20 output size

Security Considerations

⚠️ Advanced Users Only: These functions are low-level primitives that can easily be misused. Incorrect usage can lead to serious security vulnerabilities.

Ed25519 Operations:

Point Validation: Always validate curve points before use - invalid points can break protocols
Scalar Reduction: Ensure scalars are properly reduced - unreduced scalars can leak information
Side-Channel Attacks: These operations may not be constant-time for all inputs
Protocol Design: Consult cryptographic literature before designing protocols with these primitives

Ristretto255 Operations:

Prime Order Group: Ristretto255 provides a prime-order group, avoiding cofactor issues of Ed25519
Hash-to-Curve: Use from_hash for deterministic point generation from arbitrary data
Element Validation: All Ristretto255 elements are valid by construction, but still validate untrusted inputs

Low-Level Core Functions:

Construction Only: HChaCha20/HSalsa20 are building blocks, not standalone encryption functions
Key Derivation: Primarily used for deriving subkeys in extended-nonce constructions
Constant Handling: Use null for default constants unless you need custom values

General Recommendations:

Use Higher-Level APIs: Prefer authenticated encryption and digital signatures over these primitives
Protocol Review: Have cryptographic experts review any protocol using these functions
Testing: Thoroughly test with known test vectors and edge cases
Documentation: Study the libsodium documentation and academic papers before implementation