JavaScript version of NaCl Cryptographic library
JavaScript TypeScript HTML
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
c sources

ecma-nacl: Pure JavaScript (ECMAScript) version of NaCl cryptographic library.

NaCl is a great crypto library that is not placing a burden of crypto-math choices onto developers, providing only solid high-level functionality (box - for public-key, and secret_box - for secret key authenticated encryption), in a let's stop blaming users of cryptographic library (e.g. end product developers, or us) manner. Take a look at details of NaCl's design "The security impact of a new cryptographic library".

ecma-nacl is a re-write of NaCl in TypeScript, which is ECMAScript with compile-time types. Library implements NaCl's box and secret box. Signing code comes from SUPERCOP version 2014-11-24.

TypeScript re-write of scrypt key derivation function has been added to ecma-nacl beyond NaCl. Scrypt is a highly valuable thing for services that allow users to have passwords, while doing proper work with crypto keys, derived from those passwords.

Re-writes are based on C sources, included in this repository. Tests are written to correspond those in C code, to make sure that output of this library is the same as that of C's version. Scrypt's tests a taken from an RFC draft. Besides this, we added comparison runs between ecma-nacl, and js-nacl with js-scrypt, which is an Emscripten-compilation of C respective libraries. These comparison runs can be done in both node and browsers.

Get ecma-nacl

NPM Package

This library is registered on To install it, do:

npm install ecma-nacl

Package comes with already compiled library code in dist/ folder. For testing, bring up a build environment (see below), and run necessary gulp tasks.

Browser Package

Browserified version can be found in dist/ folder, and is generated by one of gulp's tasks.


Once you get package, or this repo, do in the folder

npm install

which will install dev-dependencies.

Building is done with gulp, exposed via npm script. Do in the folder

npm run gulp help

and have fun with it.

ecma-nacl API

API for secret-key authenticated encryption

Add module into code as

var nacl = require('ecma-nacl');

Secret-key authenticated encryption is provided by secret_box, which implements XSalsa20+Poly1305.

When encrypting, or packing, NaCl does following things. First, it encrypts plain text bytes using XSalas20 algorithm. Secondly, it creates 16 bytes of authentication Poly1305 code, and places these infront of the cipher. Thus, regular byte layout is 16 bytes of Poly1305 code, followed by cipher with actual message, having exactly the same length as plain text message.

Decrypting, or opening goes through these steps in reverse. First, Poly1305 code is read and is compared with code, generated by reading cipher. When these do not match, it means either that key+nonce pair is incorrect, or that cipher with message has been damaged/changed. Our code will throw an exception in such a case. When verification is successful, XSalsa20 will do decryption, producing message bytes.

// all incoming and outgoing things are Uint8Array's;
// to encrypt, or pack plain text bytes into cipher bytes, use
var cipher_bytes = nacl.secret_box.pack(plain_bytes, nonce, key);

// decryption, or opening is done by
var result_bytes =, nonce, key);

Above pack method will produce an Uint8Array with cipher, offset by 16 zero bytes in the underlying buffer. Deciphered bytes, on the other hand, are offset by 32 zero bytes. This should always be kept in mind, when transferring raw buffers to/from web-workers. In all other places, this padding is never noticed, thanks to typed array api.

Key is 32 bytes long. Nonce is 24 bytes. Nonce means number-used-once, i.e. it should be unique for every segment encrypted by the same key.

Sometimes, when storing things, it is convenient to pack cipher together with nonce (WN) into the same array.

+-------+ +------+ +---------------+
| nonce | | poly | |  data cipher  |
+-------+ +------+ +---------------+
| <----       WN format      ----> |

For this, secret_box has formatWN object, which is used analogously:

// encrypting, and placing nonce as first 24 bytes infront NaCl's byte output layout
var cipher_bytes = nacl.secret_box.formatWN.pack(plain_bytes, nonce, key);

// decryption, or opening is done by
var result_bytes =, key);

// extraction of nonce from cipher can be done as follows
var extracted_nonce = nacl.secret_box.formatWN.copyNonceFrom(cipher_bytes);

Cipher array here has no offset in the buffer, but decrypted array does have the same 32 zero bytes offset, as mentioned above.

It is important to always use different nonce, when encrypting something new with the same key. Object nonce contains functions to advance nonce, to calculate consequent nonces, etc. The 24 bytes of a nnce are taken as three 32-bit integers, and are advanced by 1 (oddly), by 2 (evenly), or by n. So, when encrypting many segments of a huge file, one can advance nonce oddly every time. When key is shared, and is used for communication between two parties, one party's initial nonce may be oddly advanced initial nonce, received from the second party, and all other respective nonces are advanced evenly on both sides of communication. This way, unique nonces are used for every message send.

// nonce changed in place oddly

// nonce changed in place evenly

// nonce changed in place by delta
nacl.nonce.advance(nonce, delta);

// calculate related nonce
var relatedNonce = nacl.nonce.calculateNonce(nonce, delta, arrayFactory);

// find delta between nonces (null result is for unrelated nonces)
var delta = nacl.nonce.calculateDelta(n1, n2);

It is common, that certain code needs to be given encryption/decryption functionality, but according to principle of least authority such code does not necessarily need to know secret key, with which encryption is done. So, one may make an encryptor and a decryptor. These are made to produce and read ciphers with-nonce format.

// delta is optional, defaults to one
var encryptor = nacl.secret_box.formatWN.makeEncryptor(key, nextNonce, delta);

// packing bytes is done with
var cipher_bytes = encryptor.pack(plain_bytes);

// when encryptor is no longer needed, key should be properly wiped from memory

var decryptor = nacl.secret_box.formatWN.makeDecryptor(key);

// opening is done with
var result_bytes =;

// when encryptor is no longer needed, key should be properly wiped from memory

API for public-key authenticated encryption

Public-key authenticated encryption is provided by box, which implements Curve25519+XSalsa20+Poly1305. Given pairs of secret-public keys, corresponding shared, in Diffie–Hellman sense, key is calculated (Curve25519) and is used for data encryption with secret_box (XSalsa20+Poly1305).

Given any random secret key, we can generate corresponding public key:

var public_key =;

Secret key may come from browser's crypto.getRandomValues(array), or be derived from a passphrase with scrypt.

There are two ways to use box. The first way is to always do two things, calculation of DH-shared key and subsequent packing/opening, in one step.

// Alice encrypts message for Bob
var cipher_bytes =, nonce, bob_pkey, alice_skey);

// Bob opens the message
var msg_bytes =, nonce, alice_pkey, bob_skey);

The second way is to calculate DH-shared key once and use it for packing/opening multiple messages, with and, which are just nicknames of described above secret_box.pack and

// Alice calculates DH-shared key
var dhshared_key =, alice_skey);
// Alice encrypts message for Bob
var cipher_bytes =, nonce, dhshared_key);

// Bob calculates DH-shared key
var dhshared_key =, bob_skey);
// Bob opens the message
var msg_bytes =, nonce, dhshared_key);

Or, we may use box encryptors that do first step of DH-shared key calculation only at creation.

Alice's side:

// generate nonce, browser example
var nonce = new Uint8Array(24);

// make encryptor to produce with-nonce format (default delta is two)
var encryptor =, alice_skey, nonce);

// pack messages to Bob
var cipher_to_send = encryptor.pack(msg_bytes);

// open mesages from Bob
var decryptor =, alice_skey);
var msg_from_bob =;
// when encryptor is no longer needed, key should be properly wiped from memory

Bob's side:

// get nonce from Alice's first message, advance it oddly, and
// use for encryptor, as encryptors on both sides advance nonces evenly
var nonce =;

// make encryptor to produce with-nonce format (default delta is two)
var encryptor =, bob_skey, nonce);

// pack messages to Alice
var cipher_to_send = encryptor.pack(msg_bytes);

// open mesages from Alice
var decryptor =, bob_skey);
var msg_from_alice =;
// when encryptor is no longer needed, key should be properly wiped from memory


Code for signing is a re-write of Ed25519 C version from SUPERCOP's, referenced in NaCl.

signing object contains all related functionality.

// signing key pair can be generated from some seed array, which can
// either be random itself, or be generated from a password
var pair = nacl.signing.generate_keypair(seed);

// make signature bytes, for msg
var msgSig = nacl.signing.signature(msg, pair.skey);

// verify signature
var sigIsOK = nacl.signing.verify(msgSig, msg, pair.pkey);

There are functions like NaCl's sign and sign_open methods, which place signature and message into one array, and expect the same for opening (verification). In a context of JWK, abovementioned functions seem to be more flexible and useful than C's API.

Random number generation

NaCl does not do it. The randombytes in the original code is a unix shim with the following rational, given in the comment, quote: "it's really stupid that there isn't a syscall for this".

So, you should obtain cryptographically strong random bytes yourself. In node, there is crypto. There is crypto in browser. IE6? IE6 must die! Stop supporting insecure crap! Respect your users, and tell them truth, that they need modern secure browser(s).

Scrypt - key derivation from passphrases

Scrypt derives a key from users password. Algorithm is memory-hard, which means it uses lots and lots of memory. There are three parameters that go into derivation: N , r and p .

Amount of memory used is roughly 128 * N * r == r * 2^(7+logN) bytes. With r = 8 , when logN is 10, it is a MB range of memory, when logN is 20, it is a GB range of memory in use.

Parameter p says how many times should the whole operation occur. So, when running out of memory (js is not giving enough memory for logN = 20 ), one may up p value.

It goes without saying, that such operations take time, and this implementation has a callback for progress reporting.

   // given pass (secret), salt and other less-secret parameters
   // key of length keyLen is generated as follows:
   var logN = 17;
   var r = 8;
   var p = 2;
   var key = nacl.scrypt(pass, salt, logN, r, p, keyLen, function(pDone) {
       console.log('derivation progress: ' + pDone + '%');

Colin Percival's paper about scrypt makes for a lovely weekend-long reading.


This code is provided here under Mozilla Public License Version 2.0.

NaCl C library is public domain code by Daniel J. Bernstein and co. We thank thy wisdom of giving us developer-friendly library.

Scrypt C library is created by Colin Percival. We thank thee for bringing us strong new ideas in key derivation tasks.