Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
N

node-sodium

> 编程语言
Open source

Port of the lib sodium encryption library to Node.js

353 stars0 likes1 views
WebsiteGitHub

About

Port of the lib sodium encryption library to Node.js

node-sodium

Version 3.0 has been refactored to use N-API, instead of NaN, so it should be more resistent to node version upgrades.

Versions 2.0 and above are no longer compatible with Node 0.x. If you're still using an old version of node please use an older version of node-sodium.

Uses Libsodium 1.0.16

Port of the lib sodium Encryption Library to Node.js.

As of libsodium 1.0.11 all functions except memory allocation have been implemented. Missing functions are listed in docs/not implemented.md.

There's a "low level" native module that gives you access directly to Lib Sodium, and a friendlier high level API that makes the library a bit easier to use.

Check docs/low-level-api.md for a list of all lib sodium functions included in node-sodium.

Usage

Just a quick example that uses the same public/secret key pair to encrypt and then decrypt the message.

var sodium = require('sodium');
var box = new sodium.Box();     // random key pair, and nonce generated automatically

var cipherText = box.encrypt("This is a secret message", "utf8");
var plainText = box.decrypt(cipherText);

Low Level API

A low level API is provided for advanced users. The functions available through the low level API have the exact same names as in lib sodium, and are available via the sodium.api object. Here is one example of how to use some of the low level API functions to encrypt/decrypt a message:

var sodium = require('sodium').api;

// Generate keys
var sender = sodium.crypto_box_keypair();
var receiver = sodium.crypto_box_keypair();

// Generate random nonce
var nonce = Buffer.allocUnsafe(sodium.crypto_box_NONCEBYTES);
sodium.randombytes_buf(nonce);

// Encrypt
var plainText = Buffer.from('this is a message');
var cipherMsg = sodium.crypto_box(plainText, nonce, receiver.publicKey, sender.secretKey);

// Decrypt
var plainBuffer = sodium.crypto_box_open(cipherMsg,nonce,sender.publicKey, receiver.secretKey);

// We should get the same plainText!
if (plainBuffer.toString() == plainText) {
    console.log("Message decrypted correctly");
}

As you can see the high level API implementation is easier to use, but the low level API will feel just right for those experienced with the C version of lib sodium. It also allows you to bypass any bugs in the high level APIs.

You can find this code sample in examples\low-level-api.js.

Documentation

Please read the work in progress documentation found under docs/.

You should also review the unit tests as most of the high level API is "documented" there. Don't forget to check out the examples as well.

The low level libsodium API documentation is now complete. All ported functions have been documented in low-level-api.md with code examples.

Please be patient as I document the rest of the APIs, or better still: help out! :)

Lib Sodium Documentation

Lib Sodium is documented here. Node-Sodium follows the same structure and I will keep documenting it as fast as possible.

Install

Tested on Mac, Linux, Windows and IllumOS Systems

bash
npm install sodium

node-sodium depends on libsodium, so if libsodium does not compile on your platform chances are npm install sodium will fail.

Install can fail in some Linux distros due to permission issues. If you see an error similar to the following:

bash
npm WARN lifecycle [email protected]~preinstall: cannot run in wd %s %s (wd=%s) [email protected] node install.js --preinstall

Try installing with

bash
npm install sodium --unsafe-perm

Installation will fail if node-gypis not installed on your system. Please run

bash
npm install node-gyp -g

Before you install node-sodium. If you run into permission errors while installing node-gyp run as Adminstrator on Windows or use sudo in other OSes.

bash
sudo npm install node-gyp -g

Compiling libsodium requires autoconf, automake and libtool so if you get an errors about these tools missing please install them. On Mac OS you can do so with:

bash
brew install libtool autoconf automake

If you cannot compile libsodium on Linux, try installing libtools with:

bash
sudo apt-get install libtool-bin

Windows Install

Windows installs will automatically attempt to download LibSodium binary distribution, and include files, from my repo. You MUST set the msvs_version npm config variable to the appropriate Microsoft Visual Studio version you have installed before you run npm install on Windows.

Example set msvs_version for your user only:

bash
npm config set msvs_version 2015

Example set msvs_version for all users:

bash
npm config set msvs_version 2015 --global

At the moment only 2010, 2012, 2013 and 2015 versions are supported.

Now run

bash
npm install

At the moment Windows only supports dynamic linking so you must have the libsodium.dll in the same directory as sodium.node. This is done automatically by the install script, but if you move things around manually please don't forget to copy the DLL file as well.

If you experience difficulty with the install even with a correctly set msvs_version, it may be worth trying:

bash
npm install npm -g

to upgrade npm and its bundled version of node-gyp.

Manual Build

Node Sodium includes the source of libsodium, so the normal install will try to compile libsodium directly from source, using libsodium's own build tools. This is the prefered method of compiling node sodium. If you can't compile libsodium from source in your platform you can download a pre-compiled binary and copy the libsodium.* library files to ./deps/build/lib folder. and copy all the include files to ./deps/build/include.

Before you run the manual build you must run the npm install once to install the required dependencies, like node-gyp that are needed to compile node-sodium. Please note that npm install will install the dependencies and compile node-sodium as well. After this initial step you can make changes to the source and run the following commands to manually build the module:

make sodium

You need to install autotools and check the version. For OSX you can do

bash
brew install libtool autoconf automake
autoconf --version
automake --version
libtool -V

SECURITY WARNING: Using a Binary LibSodium Library

Node Sodium is a strong encryption library, odds are that a lot of security functions of your application depend on it, so DO NOT use binary libsodium distributions that you haven't verified. If you use a pre-compiled version of libsodium you MUST be sure that nothing malicious was added to the compiled version you are using.

The Windows installation uses an official binary distribution that I maintain at my repo. The files in this repository correspond to the files for the MSVC libsodium build version supported by node-sodium. I will keep them updated as newer versions of libsodium become available and are supported by node-sodium.

These are provided in an attempt to simplify Windows installs and you should verify the file signatures against the originals, to make sure they haven't been tampered with. They are provided AS IS and I take no responsibility for their correctness.

Code Samples

Please check the fully documented code samples in test/test_sodium.js.

Installing Mocha Test Suite

To run the unit tests you need Mocha. If you'd like to run coverage reports you need mocha-istanbul. You can install both globally by doing

bash
npm install -g mocha mocha-istanbul

You may need to run it with sudo as only the root user has access to Node.js global directories

bash
sudo npm install -g mocha mocha-istanbul

Unit Tests

You need to have mocha test suite installed globally then you can run the node-sodium unit tests by

make test

Coverage Reports

You need to have mocha and mocha-istanbul installed globally then you can run the node-sodium coverage reports by

make test-cov

License

This software is licensed through the MIT License. Please read the LICENSE file for more details.

Author

Built and maintained by Pedro Paixao

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Cencryption-libraryjavascriptlibsodiumnode-sodium

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言