tessl/npm-sodium-native
Low level bindings for libsodium cryptographic library
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-sodium-native@5.0.0index.mddocs/
Sodium Native
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;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;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;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;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;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;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;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;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;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;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;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;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;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;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;