Uses Libsodium 1.0.3
Port of the lib sodium Encryption Library to Node.js.
This is a work in progress but most of Lib Sodium has been ported already.
Missing are the generichash functions, and the alternative primitives, like crypto_box_curve25519xsalsa20poly1305, or crypto_stream_aes128ctr.
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/ported-functions.md for a list of all lib sodium functions included in node-sodium.
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);
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 = new Buffer(sodium.crypto_box_NONCEBYTES);
sodium.randombytes_buf(nonce);
// Encrypt
var plainText = new Buffer('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.
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 is documented here. Node-Sodium follows the same structure and I will keep documenting it as fast as possible.
Tested on Mac, Linux and IllumOS Systems
npm install sodium
node-sodium depends on lib sodium, so if lib sodium does not compile on your platform chances are npm install sodium will fail.
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 configure
make sodium
Please check the fully documented code samples in test/test_sodium.js.
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
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
sudo npm install -g mocha mocha-istanbul
You need to have mocha test suite installed globally then you can run the node-sodium unit tests by
make test
You need to have mocha and mocha-istanbul installed globally then you can run the node-sodium coverage reports by
make test-cov
This software is licensed through the MIT License. Please read the LICENSE file for more details.
Built and maintained by Pedro Paixao