jedisct1/libsodium.js

libsodium.js

Overview

The sodium crypto library compiled to WebAssembly and pure JavaScript using Emscripten, with automatically generated wrappers to make it easy to use in web applications.

The standard version weighs about 290 KB and the sumo version about 375 KB (minified, gzipped, includes pure JS + WebAssembly versions). Both can run in a web browser as well as server-side.

Compatibility

Supported browsers/JS engines:

• Chrome >= 16
• Edge >= 0.11
• Firefox >= 21
• Mobile Safari on iOS >= 8.0 (older versions produce incorrect results)
• NodeJS
• Bun
• Opera >= 15
• Safari >= 6 (older versions produce incorrect results)

This is comparable to the WebCrypto API, which is compatible with a similar number of browsers.

Signatures and other Edwards25519-based operations are compatible with WasmCrypto.

Installation

The dist directory contains pre-built scripts. Copy the files from one of its subdirectories to your application:

• browsers includes a single-file script that can be included in web pages. It contains code for commonly used functions.
• browsers-sumo is a superset of the previous script, that contains all functions, including rarely used ones and undocumented ones.
• modules includes commonly used functions, and is designed to be loaded as a CommonJS module. libsodium-wrappers is the module your application should load, which will in turn automatically load libsodium as a dependency.
• modules-sumo contains sumo variants of the previous modules.
• modules-esm contains ESM (ES modules) versions with .mjs extensions.
• modules-sumo-esm contains sumo ESM variants.

The modules are also available on npm:

• libsodium-wrappers
• libsodium-wrappers-sumo

Usage (as a module)

Load the libsodium-wrappers module. The returned object contains a .ready property: a promise that must be resolved before the sodium functions can be used.

Example:

import sodium from 'libsodium-wrappers';

await sodium.ready;

let key = sodium.crypto_secretstream_xchacha20poly1305_keygen();

let { state: state_out, header } =
  sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
let c1 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
  sodium.from_string('message 1'), null,
  sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE);
let c2 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
  sodium.from_string('message 2'), null,
  sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL);

let state_in = sodium.crypto_secretstream_xchacha20poly1305_init_pull(header, key);
let r1 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c1);
let { message: m1_bytes, tag: tag1 } = r1;
let m1 = sodium.to_string(m1_bytes);
let r2 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c2);
let { message: m2_bytes, tag: tag2 } = r2;
let m2 = sodium.to_string(m2_bytes);

sodium.free(state_out);
sodium.free(state_in);

console.log(m1);
console.log(m2);

Named exports: The ESM modules also provide named exports for helper functions:

import { ready, free, from_hex, to_hex, from_string, to_string } from 'libsodium-wrappers';

await ready;
const bytes = from_hex('deadbeef');
console.log(to_hex(bytes));

Note: Cryptographic functions (like crypto_secretbox_easy) and constants (like crypto_secretbox_KEYBYTES) are dynamically added to the module at runtime after ready resolves. They cannot be imported as named exports and must be accessed via the default export:

import sodium from 'libsodium-wrappers';

await sodium.ready;
// Now crypto functions and constants are available on the sodium object
const key = sodium.crypto_secretbox_keygen();
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);

Usage (in a web browser, via a callback)

The sodium.js file includes both the core libsodium functions, as well as the higher-level JavaScript wrappers. It can be loaded asynchronously.

A sodium object should be defined in the global namespace, with the following property:

• onload: the function to call after the wrapper is initialized.

Example:

<script>
    window.sodium = {
        onload: function (sodium) {
            let h = sodium.crypto_generichash(64, sodium.from_string('test'));
            console.log(sodium.to_hex(h));
        }
    };
</script>
<script src="sodium.js" async></script>

Important: If you inline the library directly into your HTML (rather than loading it from a separate file), make sure your page declares UTF-8 encoding:

<meta charset="utf-8">

Without this, browsers may corrupt the embedded WebAssembly binary data during HTML parsing, leading to errors like "failed to match magic number" or "HEAPU8 is undefined". Also ensure your server sends the charset=utf-8 header.

Additional helpers

• from_base64(), to_base64() with an optional second parameter whose value is one of: base64_variants.ORIGINAL, base64_variants.ORIGINAL_NO_PADDING, base64_variants.URLSAFE or base64_variants.URLSAFE_NO_PADDING. Default is base64_variants.URLSAFE_NO_PADDING.
• from_hex(), to_hex()
• from_string(), to_string()
• pad(<buffer>, <block size>), unpad(<buffer>, <block size>)
• memcmp() (constant-time check for equality, returns true or false)
• compare() (constant-time comparison. Values must have the same size. Returns -1, 0 or 1)
• memzero() (applies to Uint8Array objects)
• increment() (increments an arbitrary-long number stored as a little-endian Uint8Array - typically to increment nonces)
• add() (adds two arbitrary-long numbers stored as little-endian Uint8Array vectors)
• is_zero() (constant-time, checks Uint8Array objects for all zeros)

API

The API exposed by the wrappers is identical to the one of the C library, except that buffer lengths never need to be explicitly given.

Binary input buffers should be Uint8Array objects. However, if a string is given instead, the wrappers will automatically convert the string to an array containing a UTF-8 representation of the string.

Example:

var key = sodium.randombytes_buf(sodium.crypto_shorthash_KEYBYTES),
    hash1 = sodium.crypto_shorthash(new Uint8Array([1, 2, 3, 4]), key),
    hash2 = sodium.crypto_shorthash('test', key);

If the output is a unique binary buffer, it is returned as a Uint8Array object.

Example (secretbox):

let key = sodium.from_hex('724b092810ec86d7e35c9d067702b31ef90bc43a7b598626749914d6a3e033ed');

function encrypt_and_prepend_nonce(message) {
    let nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
    let ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);
    let result = new Uint8Array(nonce.length + ciphertext.length);
    result.set(nonce);
    result.set(ciphertext, nonce.length);
    return result;
}

function decrypt_after_extracting_nonce(nonce_and_ciphertext) {
    if (nonce_and_ciphertext.length < sodium.crypto_secretbox_NONCEBYTES + sodium.crypto_secretbox_MACBYTES) {
        throw "Short message";
    }
    let nonce = nonce_and_ciphertext.slice(0, sodium.crypto_secretbox_NONCEBYTES),
        ciphertext = nonce_and_ciphertext.slice(sodium.crypto_secretbox_NONCEBYTES);
    return sodium.crypto_secretbox_open_easy(ciphertext, nonce, key);
}

In addition, the from_hex, to_hex, from_string, and to_string functions are available to explicitly convert hexadecimal, and arbitrary string representations from/to Uint8Array objects.

Functions returning more than one output buffer are returning them as an object. For example, the sodium.crypto_box_keypair() function returns the following object:

{ publicKey: (Uint8Array), privateKey: (Uint8Array), keyType: 'x25519' }

This also applies to newer APIs such as:

{ state: (StateAddress), header: (Uint8Array) }
{ ciphertext: (Uint8Array), sharedSecret: (Uint8Array) }

for crypto_secretstream_xchacha20poly1305_init_push() and crypto_kem_enc().

A StateAddress is an opaque numeric handle to memory allocated in the WebAssembly heap. Streaming APIs with a *_final() function free their state automatically when finalizing. Streaming APIs without a final function, such as crypto_secretstream_xchacha20poly1305_* and crypto_xof_*, require callers to call sodium.free(state_address) once after the last operation. Do not use a state after calling sodium.free() or after passing it to a *_final() function.

Standard vs Sumo version

The standard version (in the dist/browsers, dist/modules, and dist/modules-esm directories) contains the high-level functions, and is the recommended one for most projects.

Alternatively, the "sumo" version, available in the dist/browsers-sumo, dist/modules-sumo, and dist/modules-sumo-esm directories contains all the symbols from the original library. This includes undocumented, untested, deprecated, low-level and easy to misuse functions.

The crypto_pwhash_* function set is only included in the sumo version.

The sumo version is slightly larger than the standard version, reserves more memory, and should be used only if you really need the extra symbols it provides.

Compilation

If you want to compile the files yourself, the following dependencies need to be installed on your system:

• Emscripten
• binaryen
• git
• bun
• make

Running make will install the dev dependencies if needed, build the standard and sumo distributions, regenerate API docs and TypeScript bindings, pack the generated outputs, and rebuild the browser test artifacts.

Benchmarks

Run make benchmark to measure the performance of the cryptographic functions. You can also run specific benchmarks with bun benchmark/index.ts --only <name> (use --list to see available benchmarks).

Related projects

• react-native-libsodium: React Native bindings to Libsodium matching the libsodium-wrappers package API

Authors

Built by Ahmad Ben Mrad, Frank Denis and Ryan Lester.

License

This wrapper is distributed under the ISC License.