Documentation

Overview

The primary goal of this project is to produce a transformation of TweetNaCl to JavaScript which is arsenic close up as potential to the original C implementation, plus a reduce layer of idiomatic high-level API on top of it.

There are two versions, you can use either of them :

• nacl.js is the port of TweetNaCl with minimal differences from the original + high-level API .
• nacl-fast.js is like nacl.js, but with some functions replaced with quicker versions. ( Used by nonpayment when importing NPM box. )

Audits

TweetNaCl.js has been audited by Cure53 in January-February 2017 ( audit was sponsored by Deletype ) :

The overall consequence of this audit signals a particularly cocksure appraisal for TweetNaCl-js, as the testing team was unable to find any security problems in the library. It has to be noted that this is an exceptionally rare result of a generator code audit for any project and must be seen as a true will to a development proceeding with security system at its core .
To reiterate, the TweetNaCl-js plan, the source code was found to be bug-free at this detail .
[ … ]
In sum, the testing team is happy to recommend the TweetNaCl-js project as likely one of the safe and more batten cryptanalytic tools among its contest .

Read full moon audited account report

Installation

You can install TweetNaCl.js via a box director :
narration :

$ yarn add tweetnacl

NPM :

$ npm install tweetnacl

or download source code .

Examples

You can find usage examples in our wiki .

Usage

All API functions accept and return bytes as Uint8Array s. If you need to encode or decode strings, use functions from hypertext transfer protocol : //github.com/dchest/tweetnacl-util-js or one of the more robust codec packages .
In Node.js v4 and late Buffer objects are backed by Uint8Array randomness, so you can freely pass them to TweetNaCl.js functions as arguments. The retort objects are still Uint8Array sulfur, indeed if you need Buffer south, you ‘ll have to convert them manually ; make indisputable to convert using imitate : Buffer.from(array) ( or new Buffer(array) in Node.js v4 or earlier ), alternatively of sharing : Buffer.from(array.buffer) ( or new Buffer(array.buffer) Node 4 or earlier ), because some functions return subarrays of their buffers .

Public-key authenticated encryption (box)

Implements x25519-xsalsa20-poly1305 .
Generates a modern random key pair for box and returns it as an object with publicKey and secretKey members :

{
   publicKey: ...,  // Uint8Array with 32-byte public key
   secretKey: ...   // Uint8Array with 32-byte secret key
}

Returns a key pair for box with public identify corresponding to the given privy key .
Encrypts and authenticates message using peer ‘s populace key, our clandestine identify, and the given time being, which must be alone for each distinct message for a key match .
Returns an code and attested message, which is nacl.box.overheadLength longer than the master message .
Authenticates and decrypts the given box with peer ‘s public key, our mysterious cardinal, and the given time being .
Returns the original message, or null if authentication fails .
Returns a precomputed shared key which can be used in nacl.box.after and nacl.box.open.after .
lapp as nacl.box, but uses a share key precomputed with nacl.box.before .
same as nacl.box.open, but uses a shared key precomputed with nacl.box.before .

Constants

nacl.box.publicKeyLength = 32

Length of public key in bytes .

nacl.box.secretKeyLength = 32

Length of confidential key in bytes .

nacl.box.sharedKeyLength = 32

Length of precomputed shared key in bytes .

nacl.box.nonceLength = 24

Length of time being in bytes .

nacl.box.overheadLength = 16

length of overhead added to box compared to original message .

Secret-key authenticated encryption (secretbox)

Implements xsalsa20-poly1305 .
Encrypts and authenticates message using the key and the time being. The time being must be unique for each distinct message for this key .
Returns an code and authenticate message, which is nacl.secretbox.overheadLength longer than the original message .
Authenticates and decrypts the given secret box using the key and the time being .
Returns the original message, or null if authentication fails .

Constants

nacl.secretbox.keyLength = 32

Length of samara in bytes .

nacl.secretbox.nonceLength = 24

Length of time being in bytes .

nacl.secretbox.overheadLength = 16

length of operating expense added to secret box compared to original message .

Scalar multiplication

Implements x25519 .
Multiplies an integer n by a group element p and returns the resulting group component .
Multiplies an integer n by a standard group element and returns the resulting group component.

Constants

nacl.scalarMult.scalarLength = 32

Length of scalar in bytes .

nacl.scalarMult.groupElementLength = 32

Length of group element in bytes .

Signatures

Implements ed25519 .
Generates modern random key copulate for bless and returns it as an aim with publicKey and secretKey members :

{
   publicKey: ...,  // Uint8Array with 32-byte public key
   secretKey: ...   // Uint8Array with 64-byte secret key
}

Returns a sign winder match with populace key corresponding to the given 64-byte secret key. The confidential key must have been generated by nacl.sign.keyPair or nacl.sign.keyPair.fromSeed .
Returns a new sign key pair generated deterministically from a 32-byte seed. The seeded player must contain enough randomness to be fasten. This method acting is not recommended for general habit : rather, use nacl.sign.keyPair to generate a new key couple from a random source .
Signs the message using the mysterious key and returns a signed message .
Verifies the sign message and returns the message without signature .
Returns null if verification failed .
Signs the message using the mysterious key and returns a key signature .
Verifies the signature for the message and returns true if verification succeeded or false if it failed .

Constants

nacl.sign.publicKeyLength = 32

length of signing populace key in bytes .

nacl.sign.secretKeyLength = 64

length of signing secret identify in bytes .

nacl.sign.seedLength = 32

Length of seed for nacl.sign.keyPair.fromSeed in bytes .

nacl.sign.signatureLength = 64

Length of signature in bytes .

Hashing

Implements SHA-512 .
Returns SHA-512 hashish of the message .

Constants

nacl.hash.hashLength = 64

Length of hashish in bytes .

Random bytes generation

Returns a Uint8Array of the given duration containing random bytes of cryptanalytic quality .
Implementation note
TweetNaCl.js uses the follow methods to generate random bytes, depending on the platform it runs on :

• window.crypto.getRandomValues (WebCrypto standard)
• window.msCrypto.getRandomValues (Internet Explorer 11)
• crypto.randomBytes (Node.js)

If the platform does n’t provide a suitable PRNG, the following functions, which require random numbers, will throw exception :

• nacl.randomBytes
• nacl.box.keyPair
• nacl.sign.keyPair

other functions are deterministic and will continue working .
If a platform you are targeting does n’t implement procure random number generator, but you somehow have a cryptographically-strong source of information ( not Math.random ! ), and you know what you are doing, you can plug it into TweetNaCl.js like this :

nacl.setPRNG(function(x, n) {
  // ... copy n random bytes into x ...
});

note that nacl.setPRNG completely replaces inner random byte generator with the one provided .

Constant-time comparison

Compares x and y in constant time and returns true if their lengths are non-zero and equal, and their contents are equal .
Returns false if either of the arguments has zero length, or arguments have different lengths, or their contents differ .

System requirements

TweetNaCl.js supports modern browsers that have a cryptographically fasten pseudorandom numeral generator and typed arrays, including the latest versions of :

• Chrome
• Firefox
• Safari (Mac, iOS)
• Internet Explorer 11

other systems :

• Node.js

Development and testing

Install NPM modules needed for growth :

$ npm install

To build decrease versions :

$ npm run build

Tests use decrease version, so make surely to rebuild it every time you change nacl.js or nacl-fast.js .

Testing

To run tests in Node.js :

$ npm run test-node

By default all tests described here work on nacl.min.js. To test other versions, set environment variable NACL_SRC to the file identify you want to test. For case, the follow command will test fast decrease version :

$ NACL_SRC=nacl-fast.min.js npm run test-node

To run full suite of tests in Node.js, including comparing outputs of JavaScript port to outputs of the original C adaptation :

$ npm run test-node-all

To prepare tests for browsers :

$ npm run build-test-browser

and then open test/browser/test.html ( or test/browser/test-fast.html ) to run them .
To run tests in both Node and Electron :

$ npm test

Benchmarking

To run benchmarks in Node.js :

$ npm run bench
$ NACL_SRC=nacl-fast.min.js npm run bench

To run benchmarks in a browser, capable test/benchmark/bench.html ( or test/benchmark/bench-fast.html ) .

Benchmarks

For reference, here are benchmarks from MacBook Pro ( Retina, 13-inch, Mid 2014 ) laptop with 2.6 GHz Intel Core i5 CPU ( Intel ) in Chrome 53/OS X and Xiaomi Redmi Note 3 smartphone with 1.8 GHz Qualcomm Snapdragon 650 64-bit CPU ( ARM ) in Chrome 52/Android :

( You can run benchmarks on your devices by clicking on the links at the bottom of the base page ).

In short, with nacl-fast.js and 1024-byte messages you can expect to encrypt and authenticate more than 57000 messages per moment on a typical laptop or more than 14000 messages per moment on a $ 170 smartphone, gestural about 200 and verify 100 messages per second gear on a laptop or 60 and 30 messages per second on a smartphone, per CPU core ( with Web Workers you can do these operations in parallel ), which is good enough for most applications .

Contributors

See AUTHORS.md charge .

Third-party libraries based on TweetNaCl.js

• forward-secrecy — Axolotl ratchet implementation
• nacl-stream – streaming encryption
• tweetnacl-auth-js — implementation of crypto_auth
• tweetnacl-sealed-box — implementation of sealed boxes
• chloride – unified API for various NaCl modules

Who uses it

Some luminary users of TweetNaCl.js :