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

Key Exchange

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

Secure key exchange protocols for establishing shared secrets between parties using X25519 elliptic curve Diffie-Hellman. Supports both basic scalar multiplication and higher-level session key establishment.

Capabilities

Session Key Exchange

High-level interface for establishing separate transmission and reception keys between client and server.

/**
 * Generates a key pair for key exchange
 * @returns Object with publicKey, privateKey, and keyType properties
 */
function crypto_kx_keypair();

/**
 * Generates deterministic key pair from seed
 * @param seed - 32-byte seed for key generation
 * @returns Object with publicKey, privateKey, and keyType properties
 */
function crypto_kx_seed_keypair(seed);

/**
 * Computes client-side session keys
 * @param clientPublicKey - Client's 32-byte public key
 * @param clientSecretKey - Client's 32-byte secret key
 * @param serverPublicKey - Server's 32-byte public key
 * @returns Object with sharedRx and sharedTx session keys
 */
function crypto_kx_client_session_keys(clientPublicKey, clientSecretKey, serverPublicKey);

/**
 * Computes server-side session keys
 * @param serverPublicKey - Server's 32-byte public key
 * @param serverSecretKey - Server's 32-byte secret key
 * @param clientPublicKey - Client's 32-byte public key
 * @returns Object with sharedRx and sharedTx session keys
 */
function crypto_kx_server_session_keys(serverPublicKey, serverSecretKey, clientPublicKey);

Usage Example:

// Generate key pairs
const clientKeys = sodium.crypto_kx_keypair();
const serverKeys = sodium.crypto_kx_keypair();

// Client computes session keys
const clientSessionKeys = sodium.crypto_kx_client_session_keys(
  clientKeys.publicKey,
  clientKeys.privateKey,
  serverKeys.publicKey
);

// Server computes session keys
const serverSessionKeys = sodium.crypto_kx_server_session_keys(
  serverKeys.publicKey,
  serverKeys.privateKey,
  clientKeys.publicKey
);

// Keys are complementary:
// clientSessionKeys.sharedTx === serverSessionKeys.sharedRx
// clientSessionKeys.sharedRx === serverSessionKeys.sharedTx

// Use separate keys for each direction
const clientToServer = sodium.crypto_secretbox_easy(
  sodium.from_string("Hello server"),
  nonce1,
  clientSessionKeys.sharedTx
);

const serverToClient = sodium.crypto_secretbox_easy(
  sodium.from_string("Hello client"),
  nonce2,
  serverSessionKeys.sharedTx
);

Low-Level Scalar Multiplication

Direct Curve25519 operations for custom key exchange protocols.

/**
 * Performs scalar multiplication on Curve25519
 * @param privateKey - 32-byte scalar (private key)
 * @param publicKey - 32-byte curve point (public key)
 * @returns 32-byte shared secret
 * @throws Error if public key is weak or invalid
 */
function crypto_scalarmult(privateKey, publicKey);

/**
 * Computes public key from private key (scalar * base point)
 * @param privateKey - 32-byte private key
 * @returns 32-byte public key
 */
function crypto_scalarmult_base(privateKey);

Low-Level Usage Example:

// Generate private keys (random scalars)
const alicePrivate = sodium.randombytes_buf(32);
const bobPrivate = sodium.randombytes_buf(32);

// Compute public keys
const alicePublic = sodium.crypto_scalarmult_base(alicePrivate);
const bobPublic = sodium.crypto_scalarmult_base(bobPrivate);

// Both parties compute the same shared secret
const aliceShared = sodium.crypto_scalarmult(alicePrivate, bobPublic);
const bobShared = sodium.crypto_scalarmult(bobPrivate, alicePublic);

// aliceShared === bobShared

Ed25519 Scalar Operations

Advanced scalar arithmetic on the Ed25519 curve for cryptographic protocols.

// Scalar multiplication and base point operations
function crypto_scalarmult_ed25519(n, p);
function crypto_scalarmult_ed25519_base(scalar);
function crypto_scalarmult_ed25519_noclamp(n, p);
function crypto_scalarmult_ed25519_base_noclamp(scalar);

// Ristretto255 operations (for advanced protocols)
function crypto_scalarmult_ristretto255(scalar, element);
function crypto_scalarmult_ristretto255_base(scalar);

Key Pair Structure

interface KeyExchangeKeyPair {
  publicKey: Uint8Array;  // 32 bytes - share with other party
  privateKey: Uint8Array; // 32 bytes - keep secret
  keyType: string;        // "x25519"
}

interface SessionKeys {
  sharedRx: Uint8Array;   // 32 bytes - for receiving (decrypting) messages
  sharedTx: Uint8Array;   // 32 bytes - for transmitting (encrypting) messages
}

Constants

// Key Exchange
const crypto_kx_PUBLICKEYBYTES = 32;     // Public key size
const crypto_kx_SECRETKEYBYTES = 32;     // Secret key size
const crypto_kx_SEEDBYTES = 32;          // Seed size for deterministic keys
const crypto_kx_SESSIONKEYBYTES = 32;    // Session key size

// Scalar Multiplication
const crypto_scalarmult_BYTES = 32;      // Shared secret size
const crypto_scalarmult_SCALARBYTES = 32; // Private key size

// Ed25519 Scalars
const crypto_scalarmult_ed25519_BYTES = 32;
const crypto_scalarmult_ed25519_SCALARBYTES = 32;

// Ristretto255
const crypto_scalarmult_ristretto255_BYTES = 32;
const crypto_scalarmult_ristretto255_SCALARBYTES = 32;

Protocol Integration

With Secret Box Encryption:

// Establish session keys
const sessionKeys = sodium.crypto_kx_client_session_keys(
  clientPublic, clientSecret, serverPublic
);

// Encrypt message with transmission key
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
const encrypted = sodium.crypto_secretbox_easy(
  message, 
  nonce, 
  sessionKeys.sharedTx
);

// Decrypt received message with reception key
const decrypted = sodium.crypto_secretbox_open_easy(
  receivedCiphertext, 
  receivedNonce, 
  sessionKeys.sharedRx
);

Constants

// Key Exchange
const crypto_kx_PUBLICKEYBYTES = 32;    // Public key size
const crypto_kx_SECRETKEYBYTES = 32;    // Private key size  
const crypto_kx_SEEDBYTES = 32;         // Seed size for deterministic keys
const crypto_kx_SESSIONKEYBYTES = 32;   // Session key size

Security Considerations

Key Generation: Always use crypto_kx_keypair() or secure random generation for private keys
Public Key Validation: The library automatically validates public keys and rejects weak keys
Perfect Forward Secrecy: Generate new key pairs for each session to achieve forward secrecy
Key Confirmation: Consider implementing key confirmation to ensure both parties derived the same keys
Side-Channel Protection: Private keys should be handled securely to prevent side-channel attacks
Session Separation: Use separate keys for transmission and reception to prevent reflection attacks