CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-tweetnacl

Port of TweetNaCl cryptographic library to JavaScript providing comprehensive cryptographic primitives

—

Pending
Overview
Eval results
Files

lowlevel.mddocs/

Low-Level API

Advanced low-level cryptographic primitives exposed for custom protocol implementation and performance optimization. These functions provide direct access to the underlying cryptographic operations without the convenience wrappers of the high-level API.

⚠️ Warning: These functions are intended for advanced users who understand the underlying cryptographic protocols. Most applications should use the high-level API instead.

Capabilities

Stream Ciphers

Core stream cipher operations for encryption and key stream generation.

/**
 * HSalsa20 core function - fundamental building block for XSalsa20
 * @param {Uint8Array} out - Output array (32 bytes)
 * @param {Uint8Array} inp - Input array (16 bytes)
 * @param {Uint8Array} k - Key (32 bytes)
 * @param {Uint8Array} c - Constants (16 bytes)
 */
nacl.lowlevel.crypto_core_hsalsa20(out, inp, k, c): number

/**
 * XOR data with stream cipher output
 * @param {Uint8Array} c - Ciphertext output
 * @param {number} cpos - Position in ciphertext array
 * @param {Uint8Array} m - Message input  
 * @param {number} mpos - Position in message array
 * @param {number} d - Number of bytes to process
 * @param {Uint8Array} n - Nonce (24 bytes)
 * @param {Uint8Array} k - Key (32 bytes)
 * @returns {number} 0 on success
 */
nacl.lowlevel.crypto_stream_xor(c, cpos, m, mpos, d, n, k): number

/**
 * Generate stream cipher output
 * @param {Uint8Array} c - Output stream
 * @param {number} cpos - Position in output array
 * @param {number} d - Number of bytes to generate
 * @param {Uint8Array} n - Nonce (24 bytes)
 * @param {Uint8Array} k - Key (32 bytes)
 * @returns {number} 0 on success
 */
nacl.lowlevel.crypto_stream(c, cpos, d, n, k): number

/**
 * Salsa20 stream cipher XOR operation
 * @param {Uint8Array} c - Ciphertext output
 * @param {number} cpos - Position in ciphertext array
 * @param {Uint8Array} m - Message input
 * @param {number} mpos - Position in message array
 * @param {number} b - Number of bytes to process
 * @param {Uint8Array} n - Nonce (8 bytes)
 * @param {Uint8Array} k - Key (32 bytes)
 * @returns {number} 0 on success
 */
nacl.lowlevel.crypto_stream_salsa20_xor(c, cpos, m, mpos, b, n, k): number

/**
 * Generate Salsa20 stream cipher output
 * @param {Uint8Array} c - Output stream
 * @param {number} cpos - Position in output array
 * @param {number} b - Number of bytes to generate
 * @param {Uint8Array} n - Nonce (8 bytes)
 * @param {Uint8Array} k - Key (32 bytes)
 * @returns {number} 0 on success
 */
nacl.lowlevel.crypto_stream_salsa20(c, cpos, b, n, k): number

One-Time Authentication

Poly1305 one-time authentication for message integrity.

/**
 * Compute Poly1305 one-time authentication code
 * @param {Uint8Array} out - Authentication code output (16 bytes)
 * @param {number} outpos - Position in output array
 * @param {Uint8Array} m - Message input
 * @param {number} mpos - Position in message array
 * @param {number} n - Number of bytes to authenticate
 * @param {Uint8Array} k - Key (32 bytes)
 * @returns {number} 0 on success
 */
nacl.lowlevel.crypto_onetimeauth(out, outpos, m, mpos, n, k): number

/**
 * Verify Poly1305 one-time authentication code
 * @param {Uint8Array} h - Authentication code to verify (16 bytes)
 * @param {number} hpos - Position in authentication code array
 * @param {Uint8Array} m - Message input
 * @param {number} mpos - Position in message array
 * @param {number} n - Number of bytes to verify
 * @param {Uint8Array} k - Key (32 bytes)
 * @returns {number} 0 if verification succeeds, -1 if it fails
 */
nacl.lowlevel.crypto_onetimeauth_verify(h, hpos, m, mpos, n, k): number

Verification

Constant-time comparison functions for different lengths.

/**
 * Constant-time verification of 16-byte values
 * @param {Uint8Array} x - First value
 * @param {number} xi - Offset in first array
 * @param {Uint8Array} y - Second value
 * @param {number} yi - Offset in second array
 */
nacl.lowlevel.crypto_verify_16(x, xi, y, yi): number

/**
 * Constant-time verification of 32-byte values
 * @param {Uint8Array} x - First value
 * @param {number} xi - Offset in first array
 * @param {Uint8Array} y - Second value
 * @param {number} yi - Offset in second array
 */
nacl.lowlevel.crypto_verify_32(x, xi, y, yi): number

Secret-Key Operations

Low-level secret-key encryption and decryption.

/**
 * Low-level secret-key authenticated encryption
 * @param {Uint8Array} c - Ciphertext output
 * @param {Uint8Array} m - Message input
 * @param {number} mlen - Message length
 * @param {Uint8Array} n - Nonce (24 bytes)
 * @param {Uint8Array} k - Key (32 bytes)
 */
nacl.lowlevel.crypto_secretbox(c, m, mlen, n, k): number

/**
 * Low-level secret-key authenticated decryption
 * @param {Uint8Array} m - Message output
 * @param {Uint8Array} c - Ciphertext input
 * @param {number} clen - Ciphertext length
 * @param {Uint8Array} n - Nonce (24 bytes)
 * @param {Uint8Array} k - Key (32 bytes)
 */
nacl.lowlevel.crypto_secretbox_open(m, c, clen, n, k): number

Public-Key Operations

Low-level public-key cryptographic operations.

/**
 * Low-level scalar multiplication
 * @param {Uint8Array} q - Output point (32 bytes)
 * @param {Uint8Array} n - Scalar (32 bytes)
 * @param {Uint8Array} p - Input point (32 bytes)
 */
nacl.lowlevel.crypto_scalarmult(q, n, p): number

/**
 * Low-level scalar multiplication with base point
 * @param {Uint8Array} q - Output point (32 bytes)
 * @param {Uint8Array} n - Scalar (32 bytes)
 */
nacl.lowlevel.crypto_scalarmult_base(q, n): number

/**
 * Precompute shared key for box operations
 * @param {Uint8Array} k - Shared key output (32 bytes)
 * @param {Uint8Array} pk - Public key (32 bytes)
 * @param {Uint8Array} sk - Secret key (32 bytes)
 */
nacl.lowlevel.crypto_box_beforenm(k, pk, sk): number

/**
 * Box operation using precomputed shared key
 * @param {Uint8Array} c - Ciphertext output
 * @param {Uint8Array} m - Message input
 * @param {number} mlen - Message length
 * @param {Uint8Array} n - Nonce (24 bytes)
 * @param {Uint8Array} k - Precomputed shared key (32 bytes)
 */
nacl.lowlevel.crypto_box_afternm(c, m, mlen, n, k): number

/**
 * Low-level public-key authenticated encryption
 * @param {Uint8Array} c - Ciphertext output
 * @param {Uint8Array} m - Message input
 * @param {number} mlen - Message length
 * @param {Uint8Array} n - Nonce (24 bytes)
 * @param {Uint8Array} pk - Public key (32 bytes)
 * @param {Uint8Array} sk - Secret key (32 bytes)
 */
nacl.lowlevel.crypto_box(c, m, mlen, n, pk, sk): number

/**
 * Low-level public-key authenticated decryption
 * @param {Uint8Array} m - Message output
 * @param {Uint8Array} c - Ciphertext input
 * @param {number} clen - Ciphertext length
 * @param {Uint8Array} n - Nonce (24 bytes)
 * @param {Uint8Array} pk - Public key (32 bytes)
 * @param {Uint8Array} sk - Secret key (32 bytes)
 */
nacl.lowlevel.crypto_box_open(m, c, clen, n, pk, sk): number

/**
 * Generate key pair for box operations
 * @param {Uint8Array} pk - Public key output (32 bytes)
 * @param {Uint8Array} sk - Secret key output (32 bytes)
 */
nacl.lowlevel.crypto_box_keypair(pk, sk): number

Digital Signatures

Low-level digital signature operations.

/**
 * Low-level message signing
 * @param {Uint8Array} sm - Signed message output
 * @param {Uint8Array} smlen_p - Pointer to signed message length
 * @param {Uint8Array} m - Message input
 * @param {number} mlen - Message length
 * @param {Uint8Array} sk - Secret key (64 bytes)
 */
nacl.lowlevel.crypto_sign(sm, smlen_p, m, mlen, sk): number

/**
 * Generate signing key pair
 * @param {Uint8Array} pk - Public key output (32 bytes)
 * @param {Uint8Array} sk - Secret key output (64 bytes)
 */
nacl.lowlevel.crypto_sign_keypair(pk, sk): number

/**
 * Low-level signature verification
 * @param {Uint8Array} m - Message output
 * @param {Uint8Array} mlen_p - Pointer to message length
 * @param {Uint8Array} sm - Signed message input
 * @param {number} smlen - Signed message length
 * @param {Uint8Array} pk - Public key (32 bytes)
 */
nacl.lowlevel.crypto_sign_open(m, mlen_p, sm, smlen, pk): number

Hashing

Low-level hashing operation.

/**
 * Low-level SHA-512 hash computation
 * @param {Uint8Array} out - Hash output (64 bytes)
 * @param {Uint8Array} m - Message input
 * @param {number} mlen - Message length
 */
nacl.lowlevel.crypto_hash(out, m, mlen): number

Constants

All low-level constants corresponding to the cryptographic parameters:

// Secret box constants
nacl.lowlevel.crypto_secretbox_KEYBYTES: number         // 32
nacl.lowlevel.crypto_secretbox_NONCEBYTES: number       // 24
nacl.lowlevel.crypto_secretbox_ZEROBYTES: number        // 32
nacl.lowlevel.crypto_secretbox_BOXZEROBYTES: number     // 16

// Scalar multiplication constants
nacl.lowlevel.crypto_scalarmult_BYTES: number           // 32
nacl.lowlevel.crypto_scalarmult_SCALARBYTES: number     // 32

// Box constants
nacl.lowlevel.crypto_box_PUBLICKEYBYTES: number         // 32
nacl.lowlevel.crypto_box_SECRETKEYBYTES: number         // 32
nacl.lowlevel.crypto_box_BEFORENMBYTES: number          // 32
nacl.lowlevel.crypto_box_NONCEBYTES: number             // 24
nacl.lowlevel.crypto_box_ZEROBYTES: number              // 32
nacl.lowlevel.crypto_box_BOXZEROBYTES: number           // 16

// Signature constants
nacl.lowlevel.crypto_sign_BYTES: number                 // 64
nacl.lowlevel.crypto_sign_PUBLICKEYBYTES: number        // 32
nacl.lowlevel.crypto_sign_SECRETKEYBYTES: number        // 64
nacl.lowlevel.crypto_sign_SEEDBYTES: number             // 32

// Hash constants
nacl.lowlevel.crypto_hash_BYTES: number                 // 64

Usage Considerations

Return Values

Low-level functions typically return 0 on success and non-zero on failure, following NaCl conventions.

Memory Management

These functions work directly with Uint8Array buffers and require careful attention to:

  • Buffer sizes and length parameters
  • Offset parameters for array operations
  • Proper initialization of output buffers

Performance

The low-level API avoids object creation and can be more efficient for performance-critical applications, but requires more careful programming.

Security

When using low-level functions:

  • Ensure proper buffer sizes to prevent overflows
  • Use constant-time comparison functions for security-sensitive data
  • Follow cryptographic protocol specifications exactly
  • Consider using high-level API unless performance is critical

Most applications should use the high-level API (nacl.box, nacl.secretbox, etc.) which provides the same security with better usability.

Install with Tessl CLI

npx tessl i tessl/npm-tweetnacl

docs

box.md

index.md

lowlevel.md

scalarmult.md

secretbox.md

sign.md

utilities.md

tile.json