tessl/npm-sodium-native

Low level bindings for libsodium cryptographic library

—

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

Sodium Native

Name: tessl/npm-sodium-native
Author: tessl

Sodium Native provides low-level Node.js bindings for the libsodium cryptographic library. It offers direct access to libsodium's C API for high-performance cryptographic operations with a focus on buffer-based operations and manual memory management.

Package Information

Package Name: sodium-native
Package Type: npm
Language: JavaScript (with native C++ bindings)
Installation: npm install sodium-native

Core Imports

const sodium = require('sodium-native');

All functions and constants are available as properties of the sodium module:

const { 
  crypto_secretbox_easy,
  crypto_secretbox_KEYBYTES,
  crypto_secretbox_NONCEBYTES,
  randombytes_buf
} = require('sodium-native');

Basic Usage

const sodium = require('sodium-native');

// Generate random key and nonce
const key = sodium.sodium_malloc(sodium.crypto_secretbox_KEYBYTES);
const nonce = Buffer.alloc(sodium.crypto_secretbox_NONCEBYTES);

sodium.randombytes_buf(key);
sodium.randombytes_buf(nonce);

// Encrypt a message
const message = Buffer.from('Hello, World!');
const ciphertext = Buffer.alloc(message.length + sodium.crypto_secretbox_MACBYTES);

sodium.crypto_secretbox_easy(ciphertext, message, nonce, key);

// Decrypt the message
const plaintext = Buffer.alloc(ciphertext.length - sodium.crypto_secretbox_MACBYTES);
if (sodium.crypto_secretbox_open_easy(plaintext, ciphertext, nonce, key)) {
  console.log('Decrypted:', plaintext.toString());
}

// Clean up secure memory
sodium.sodium_free(key);

Architecture

Sodium Native is built around several key principles:

Buffer-based API: All data types are Buffer objects, requiring manual memory management
Direct C API mapping: Functions closely mirror libsodium's C interface for maximum performance
Secure memory utilities: Built-in support for secure memory allocation and protection
Inline operations: Support for in-place encryption/decryption to minimize memory allocation
Multi-runtime support: Compatible with both Node.js and Bare runtime environments

Capabilities

Memory Management

Secure memory allocation, protection, and cleanup utilities for handling sensitive cryptographic data.

function sodium_malloc(size: number): Buffer;
function sodium_free(buf: Buffer): void;
function sodium_memzero(buf: Buffer): void;

Memory Management

Random Number Generation

Cryptographically secure random number generation for keys, nonces, and other random values.

function randombytes_buf(buffer: Buffer): void;
function randombytes_buf_deterministic(buffer: Buffer, seed: Buffer): void;

Random Number Generation

Secret Key Encryption

Symmetric encryption using authenticated encryption schemes for protecting data with shared keys.

function crypto_secretbox_easy(c: Buffer, m: Buffer, n: Buffer, k: Buffer): void;
function crypto_secretbox_open_easy(m: Buffer, c: Buffer, n: Buffer, k: Buffer): boolean;

Secret Key Encryption

Public Key Encryption

Asymmetric encryption using Curve25519 elliptic curve cryptography for secure communication between parties.

function crypto_box_keypair(pk: Buffer, sk: Buffer): void;
function crypto_box_easy(c: Buffer, m: Buffer, n: Buffer, pk: Buffer, sk: Buffer): void;

Public Key Encryption

Digital Signatures

Ed25519 digital signatures for message authentication and non-repudiation.

function crypto_sign_keypair(pk: Buffer, sk: Buffer): void;
function crypto_sign_detached(sig: Buffer, m: Buffer, sk: Buffer): void;
function crypto_sign_verify_detached(sig: Buffer, m: Buffer, pk: Buffer): boolean;

Digital Signatures

Hash Functions

Cryptographic hash functions including BLAKE2b, SHA-256, and SHA-512 for data integrity and key derivation.

function crypto_generichash(output: Buffer, input: Buffer, key?: Buffer): void;
function crypto_hash_sha256(out: Buffer, input: Buffer): void;
function crypto_hash_sha512(out: Buffer, input: Buffer): void;

Hash Functions

Password Hashing

Secure password hashing using Argon2 and scrypt for password verification and key derivation.

function crypto_pwhash(
  out: Buffer, 
  passwd: Buffer, 
  salt: Buffer, 
  opslimit: number, 
  memlimit: number, 
  alg: number
): void;

Password Hashing

Stream Ciphers

High-performance stream ciphers including ChaCha20, XChaCha20, and Salsa20 for fast encryption.

function crypto_stream_chacha20_xor(c: Buffer, m: Buffer, n: Buffer, k: Buffer): void;
function crypto_stream_xchacha20_xor(c: Buffer, m: Buffer, n: Buffer, k: Buffer): void;

Stream Ciphers

Message Authentication

Message authentication codes (MAC) using HMAC-SHA512 and Poly1305 for data integrity verification.

function crypto_auth(out: Buffer, input: Buffer, k: Buffer): void;
function crypto_auth_verify(h: Buffer, input: Buffer, k: Buffer): boolean;

Message Authentication

Key Exchange

Diffie-Hellman key exchange using X25519 for establishing shared secrets between parties.

function crypto_kx_keypair(pk: Buffer, sk: Buffer): void;
function crypto_kx_client_session_keys(
  rx: Buffer, 
  tx: Buffer, 
  clientPk: Buffer, 
  clientSk: Buffer, 
  serverPk: Buffer
): void;

Key Exchange

Elliptic Curve Operations

Low-level elliptic curve operations on Ed25519 for advanced cryptographic protocols.

function crypto_core_ed25519_add(r: Buffer, p: Buffer, q: Buffer): void;
function crypto_core_ed25519_scalar_random(r: Buffer): void;
function crypto_scalarmult_ed25519_base(q: Buffer, n: Buffer): void;

Elliptic Curve Operations

Secret Streams

Streaming authenticated encryption using XChaCha20-Poly1305 for encrypting sequences of messages with automatic key rotation.

function crypto_secretstream_xchacha20poly1305_keygen(k: Buffer): void;
function crypto_secretstream_xchacha20poly1305_init_push(state: Buffer, header: Buffer, k: Buffer): void;
function crypto_secretstream_xchacha20poly1305_push(state: Buffer, c: Buffer, m: Buffer, ad: Buffer | null, tag: number): number;

Secret Streams

Authenticated Encryption with Additional Data

Modern authenticated encryption schemes using ChaCha20-Poly1305 and XChaCha20-Poly1305 for secure encryption with additional data.

function crypto_aead_xchacha20poly1305_ietf_encrypt(c: Buffer, m: Buffer, ad: Buffer | null, nsec: null, npub: Buffer, k: Buffer): number;
function crypto_aead_chacha20poly1305_ietf_encrypt(c: Buffer, m: Buffer, ad: Buffer | null, nsec: null, npub: Buffer, k: Buffer): number;

Authenticated Encryption (AEAD)

Key Derivation Functions

Key derivation functions for generating multiple keys from a single master key with proper domain separation.

function crypto_kdf_keygen(key: Buffer): void;
function crypto_kdf_derive_from_key(subkey: Buffer, subkeyId: number, ctx: Buffer, key: Buffer): void;

Key Derivation Functions

Short Hash Functions

Fast, non-cryptographic hash function (SipHash-2-4) optimized for hash tables and data structures.

function crypto_shorthash(out: Buffer, input: Buffer, k: Buffer): void;

Short Hash Functions

Types

// Buffer type represents a Node.js Buffer object
type Buffer = NodeJS.Buffer;

// Secure Buffer - created with sodium_malloc, has .secure property
interface SecureBuffer extends Buffer {
  secure: true;
}

// Constants are exported as numbers
const crypto_secretbox_KEYBYTES: number;
const crypto_secretbox_NONCEBYTES: number;
const crypto_secretbox_MACBYTES: number;

// Algorithm constants for password hashing
const crypto_pwhash_ALG_ARGON2I13: number;
const crypto_pwhash_ALG_ARGON2ID13: number;
const crypto_pwhash_ALG_DEFAULT: number;

// Stream tags for secret streams
const crypto_secretstream_xchacha20poly1305_TAG_MESSAGE: number;
const crypto_secretstream_xchacha20poly1305_TAG_PUSH: number;
const crypto_secretstream_xchacha20poly1305_TAG_REKEY: number;
const crypto_secretstream_xchacha20poly1305_TAG_FINAL: number;

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/sodium-native@5.0.x
Publish Source: CLI
Badge