TweetNaCl.js

TweetNaCl.js is a JavaScript port of the TweetNaCl cryptographic library that provides comprehensive cryptographic primitives including public-key authenticated encryption, secret-key authenticated encryption, digital signatures, scalar multiplication, hashing, and secure random byte generation. The library offers two implementations: nacl.js (direct port) and nacl-fast.js (optimized version used by default).

Package Information

• Package Name: tweetnacl
• Package Type: npm
• Language: JavaScript
• Installation: npm install tweetnacl

Core Imports

const nacl = require('tweetnacl');

For ES modules:

import nacl from 'tweetnacl';

For TypeScript with types:

import * as nacl from 'tweetnacl';
// or
import nacl from 'tweetnacl';

Basic Usage

const nacl = require('tweetnacl');

// Generate a random key pair
const keyPair = nacl.box.keyPair();

// Create a message and nonce
const message = new Uint8Array([1, 2, 3, 4, 5]);
const nonce = nacl.randomBytes(nacl.box.nonceLength);

// Encrypt the message
const encrypted = nacl.box(message, nonce, keyPair.publicKey, keyPair.secretKey);

// Decrypt the message
const decrypted = nacl.box.open(encrypted, nonce, keyPair.publicKey, keyPair.secretKey);

console.log(decrypted); // [1, 2, 3, 4, 5]

Architecture

TweetNaCl.js is organized around five core cryptographic capabilities:

• Public-Key Cryptography: Key exchange and authenticated encryption using Curve25519 and XSalsa20-Poly1305
• Secret-Key Cryptography: Authenticated encryption using XSalsa20-Poly1305 for shared-key scenarios
• Digital Signatures: Message signing and verification using Ed25519
• Scalar Multiplication: Low-level Curve25519 operations for custom protocols
• Utility Functions: Hashing (SHA-512), random byte generation, and constant-time comparison

The library automatically detects the runtime environment (browser or Node.js) and initializes the appropriate cryptographically secure random number generator.

Capabilities

Public-Key Authenticated Encryption

Public-key authenticated encryption using x25519-xsalsa20-poly1305. Provides confidentiality and authenticity between two parties using their key pairs.

nacl.box(message, nonce, theirPublicKey, mySecretKey): Uint8Array
nacl.box.open(box, nonce, theirPublicKey, mySecretKey): Uint8Array | null
nacl.box.keyPair(): {publicKey: Uint8Array, secretKey: Uint8Array}

Public-Key Encryption

Secret-Key Authenticated Encryption

Secret-key authenticated encryption using xsalsa20-poly1305. Provides confidentiality and authenticity using a shared secret key.

nacl.secretbox(message, nonce, key): Uint8Array
nacl.secretbox.open(box, nonce, key): Uint8Array | null

Secret-Key Encryption

Digital Signatures

Digital signatures using ed25519. Create and verify cryptographic signatures for message authentication and non-repudiation.

nacl.sign(message, secretKey): Uint8Array
nacl.sign.open(signedMessage, publicKey): Uint8Array | null
nacl.sign.keyPair(): {publicKey: Uint8Array, secretKey: Uint8Array}

Digital Signatures

Scalar Multiplication

Low-level scalar multiplication using x25519. Enables custom cryptographic protocols and key derivation.

nacl.scalarMult(n, p): Uint8Array
nacl.scalarMult.base(n): Uint8Array

Scalar Multiplication

Hashing and Utilities

Core utility functions including SHA-512 hashing, secure random byte generation, and constant-time comparison.

nacl.hash(message): Uint8Array
nacl.randomBytes(length): Uint8Array
nacl.verify(x, y): boolean
nacl.setPRNG(fn): void

Utilities

Low-Level API

Advanced low-level cryptographic primitives for custom protocol implementation and performance optimization. These functions provide direct access to underlying operations.

nacl.lowlevel.crypto_box(c, m, mlen, n, pk, sk): number
nacl.lowlevel.crypto_secretbox(c, m, mlen, n, k): number
nacl.lowlevel.crypto_sign(sm, smlen_p, m, mlen, sk): number

Low-Level API