4 Port of [TweetNaCl](http://tweetnacl.cr.yp.to) / [NaCl](http://nacl.cr.yp.to/)
5 to JavaScript for modern browsers and Node.js. Public domain.
7 [![Build Status](https://travis-ci.org/dchest/tweetnacl-js.svg?branch=master)
8 ](https://travis-ci.org/dchest/tweetnacl-js)
10 [Demo](https://dchest.github.io/tweetnacl-js/)
12 **:warning: Beta version. The library is stable and API is frozen, however
13 it has not been independently reviewed. If you can help reviewing it, please
14 [contact me](mailto:dmitry@codingrobots.com).**
19 * [Overview](#overview)
20 * [Installation](#installation)
22 * [Public-key authenticated encryption (box)](#public-key-authenticated-encryption-box)
23 * [Secret-key authenticated encryption (secretbox)](#secret-key-authenticated-encryption-secretbox)
24 * [Scalar multiplication](#scalar-multiplication)
25 * [Signatures](#signatures)
27 * [Random bytes generation](#random-bytes-generation)
28 * [Constant-time comparison](#constant-time-comparison)
29 * [Utilities](#utilities)
30 * [Examples](#examples)
31 * [System requirements](#system-requirements)
32 * [Development and testing](#development-and-testing)
33 * [Contributors](#contributors)
34 * [Who uses it](#who-uses-it)
40 The primary goal of this project is to produce a translation of TweetNaCl to
41 JavaScript which is as close as possible to the original C implementation, plus
42 a thin layer of idiomatic high-level API on top of it.
44 There are two versions, you can use either of them:
46 * `nacl.js` is the port of TweetNaCl with minimum differences from the
47 original + high-level API.
49 * `nacl-fast.js` is like `nacl.js`, but with some functions replaced with
56 You can install TweetNaCl.js via a package manager:
58 [Bower](http://bower.io):
60 $ bower install tweetnacl
62 [NPM](https://www.npmjs.org/):
64 $ npm install tweetnacl
66 or [download source code](https://github.com/dchest/tweetnacl-js/releases).
72 All API functions accept and return bytes as `Uint8Array`s. If you need to
73 encode or decode strings, use functions from `nacl.util` namespace.
75 ### Public-key authenticated encryption (box)
77 Implements *curve25519-xsalsa20-poly1305*.
79 #### nacl.box.keyPair()
81 Generates a new random key pair for box and returns it as an object with
82 `publicKey` and `secretKey` members:
85 publicKey: ..., // Uint8Array with 32-byte public key
86 secretKey: ... // Uint8Array with 32-byte secret key
90 #### nacl.box.keyPair.fromSecretKey(secretKey)
92 Returns a key pair for box with public key corresponding to the given secret
95 #### nacl.box(message, nonce, theirPublicKey, mySecretKey)
97 Encrypt and authenticates message using peer's public key, our secret key, and
98 the given nonce, which must be unique for each distinct message for a key pair.
100 Returns an encrypted and authenticated message, which is
101 `nacl.box.overheadLength` longer than the original message.
103 #### nacl.box.open(box, nonce, theirPublicKey, mySecretKey)
105 Authenticates and decrypts the given box with peer's public key, our secret
106 key, and the given nonce.
108 Returns the original message, or `false` if authentication fails.
110 #### nacl.box.before(theirPublicKey, mySecretKey)
112 Returns a precomputed shared key which can be used in `nacl.box.after` and
113 `nacl.box.open.after`.
115 #### nacl.box.after(message, nonce, sharedKey)
117 Same as `nacl.box`, but uses a shared key precomputed with `nacl.box.before`.
119 #### nacl.box.open.after(box, nonce, sharedKey)
121 Same as `nacl.box.open`, but uses a shared key precomputed with `nacl.box.before`.
123 #### nacl.box.publicKeyLength = 32
125 Length of public key in bytes.
127 #### nacl.box.secretKeyLength = 32
129 Length of secret key in bytes.
131 #### nacl.box.sharedKeyLength = 32
133 Length of precomputed shared key in bytes.
135 #### nacl.box.nonceLength = 24
137 Length of nonce in bytes.
139 #### nacl.box.overheadLength = 16
141 Length of overhead added to box compared to original message.
144 ### Secret-key authenticated encryption (secretbox)
146 Implements *xsalsa20-poly1305*.
148 #### nacl.secretbox(message, nonce, key)
150 Encrypt and authenticates message using the key and the nonce. The nonce must
151 be unique for each distinct message for this key.
153 Returns an encrypted and authenticated message, which is
154 `nacl.secretbox.overheadLength` longer than the original message.
156 #### nacl.secretbox.open(box, nonce, key)
158 Authenticates and decrypts the given secret box using the key and the nonce.
160 Returns the original message, or `false` if authentication fails.
162 #### nacl.secretbox.keyLength = 32
164 Length of key in bytes.
166 #### nacl.secretbox.nonceLength = 24
168 Length of nonce in bytes.
170 #### nacl.secretbox.overheadLength = 16
172 Length of overhead added to secret box compared to original message.
175 ### Scalar multiplication
177 Implements *curve25519*.
179 #### nacl.scalarMult(n, p)
181 Multiplies an integer `n` by a group element `p` and returns the resulting
184 #### nacl.scalarMult.base(n)
186 Multiplies an integer `n` by a standard group element and returns the resulting
189 #### nacl.scalarMult.scalarLength = 32
191 Length of scalar in bytes.
193 #### nacl.scalarMult.groupElementLength = 32
195 Length of group element in bytes.
200 Implements [ed25519](http://ed25519.cr.yp.to).
202 #### nacl.sign.keyPair()
204 Generates new random key pair for signing and returns it as an object with
205 `publicKey` and `secretKey` members:
208 publicKey: ..., // Uint8Array with 32-byte public key
209 secretKey: ... // Uint8Array with 64-byte secret key
212 #### nacl.sign.keyPair.fromSecretKey(secretKey)
214 Returns a signing key pair with public key corresponding to the given
215 64-byte secret key. The secret key must have been generated by
216 `nacl.sign.keyPair` or `nacl.sign.keyPair.fromSeed`.
218 #### nacl.sign.keyPair.fromSeed(seed)
220 Returns a new signing key pair generated deterministically from a 32-byte seed.
221 The seed must contain enough entropy to be secure. This method is not
222 recommended for general use: instead, use `nacl.sign.keyPair` to generate a new
223 key pair from a random seed.
225 #### nacl.sign(message, secretKey)
227 Signs the message using the secret key and returns a signed message.
229 #### nacl.sign.open(signedMessage, publicKey)
231 Verifies the signed message and returns the message without signature.
233 Returns `null` if verification failed.
235 #### nacl.sign.detached(message, secretKey)
237 Signs the message using the secret key and returns a signature.
239 #### nacl.sign.detached.verify(message, signature, publicKey)
241 Verifies the signature for the message and returns `true` if verification
242 succeeded or `false` if it failed.
244 #### nacl.sign.publicKeyLength = 32
246 Length of signing public key in bytes.
248 #### nacl.sign.secretKeyLength = 64
250 Length of signing secret key in bytes.
252 #### nacl.sign.seedLength = 32
254 Length of seed for `nacl.sign.keyPair.fromSeed` in bytes.
256 #### nacl.sign.signatureLength = 64
258 Length of signature in bytes.
263 Implements *SHA-512*.
265 #### nacl.hash(message)
267 Returns SHA-512 hash of the message.
269 #### nacl.hash.hashLength = 64
271 Length of hash in bytes.
274 ### Random bytes generation
276 #### nacl.randomBytes(length)
278 Returns a `Uint8Array` of the given length containing random bytes of
279 cryptographic quality.
281 **Implementation note**
283 TweetNaCl.js uses the following methods to generate random bytes,
284 depending on the platform it runs on:
286 * `window.crypto.getRandomValues` (WebCrypto standard)
287 * `window.msCrypto.getRandomValues` (Internet Explorer 11)
288 * `crypto.randomBytes` (Node.js)
290 Note that browsers are required to throw `QuotaExceededError` exception if
291 requested `length` is more than 65536, so do not ask for more than 65536 bytes
292 in *one call* (multiple calls to get as many bytes as you like are okay:
293 browsers can generate infinite amount of random bytes without any bad
296 If the platform doesn't provide a suitable PRNG, the following functions,
297 which require random numbers, will throw exception:
301 * `nacl.sign.keyPair`
303 Other functions are deterministic and will continue working.
305 If a platform you are targeting doesn't implement secure random number
306 generator, but you somehow have a cryptographically-strong source of entropy
307 (not `Math.random`!), and you know what you are doing, you can plug it into
308 TweetNaCl.js like this:
310 nacl.setPRNG(function(x, n) {
311 // ... copy n random bytes into x ...
314 Note that `nacl.setPRNG` *completely replaces* internal random byte generator
315 with the one provided.
318 ### Constant-time comparison
320 #### nacl.verify(x, y)
322 Compares `x` and `y` in constant time and returns `true` if their lengths are
323 non-zero and equal, and their contents are equal.
325 Returns `false` if either of the arguments has zero length, or arguments have
326 different lengths, or their contents differ.
331 Encoding/decoding functions are provided for convenience. They are correct,
332 however their performance and wide compatibility with uncommon runtimes is not
333 something that is considered important compared to the simplicity and size of
334 implementation. You can use third-party libraries if you need to.
336 #### nacl.util.decodeUTF8(string)
338 Decodes string and returns `Uint8Array` of bytes.
340 #### nacl.util.encodeUTF8(array)
342 Encodes `Uint8Array` or `Array` of bytes into string.
344 #### nacl.util.decodeBase64(string)
346 Decodes Base-64 encoded string and returns `Uint8Array` of bytes.
348 #### nacl.util.encodeBase64(array)
350 Encodes `Uint8Array` or `Array` of bytes into string using Base-64 encoding.
356 TweetNaCl.js supports modern browsers that have a cryptographically secure
357 pseudorandom number generator and typed arrays, including the latest versions
363 * Internet Explorer 11
367 * Node.js (we test on 0.10 and later)
370 Development and testing
371 ------------------------
373 Install NPM modules needed for development:
377 To build minified versions:
381 Tests use minified version, so make sure to rebuild it every time you change
382 `nacl.js` or `nacl-fast.js`.
386 To run tests in Node.js:
390 By default all tests described here work on `nacl.min.js`. To test other
391 versions, set environment variable `NACL_SRC` to the file name you want to test.
392 For example, the following command will test fast minified version:
394 $ NACL_SRC=nacl-fast.min.js npm test
396 To run full suite of tests in Node.js, including comparing outputs of
397 JavaScript port to outputs of the original C version:
401 To prepare tests for browsers:
405 and then open `test/browser/test.html` (or `test/browser/test-fast.html`) to
408 To run headless browser tests with `testling`:
412 (If you get `Error: spawn ENOENT`, install *xvfb*: `sudo apt-get install xvfb`.)
416 To run benchmarks in Node.js:
419 $ NACL_SRC=nacl-fast.min.js npm run bench
421 To run benchmarks in a browser, open `test/benchmark/bench.html` (or
422 `test/benchmark/bench-fast.html`).
430 * [Dmitry Chestnykh](http://github.com/dchest) (ported xsalsa20, poly1305, curve25519)
431 * [Devi Mandiri](https://github.com/devi) (ported curve25519, ed25519, sha512)
433 Original authors of [NaCl](http://nacl.cr.yp.to), [TweetNaCl](http://tweetnacl.cr.yp.to)
434 and [Poly1305-donna](https://github.com/floodyberry/poly1305-donna)
435 (who are *not* responsible for any errors in this implementation):
437 * [Daniel J. Bernstein](http://cr.yp.to/djb.html)
439 * [Tanja Lange](http://hyperelliptic.org/tanja)
440 * [Peter Schwabe](http://www.cryptojedi.org/users/peter/)
441 * [Matthew Dempsky](https://github.com/mdempsky)
442 * [Andrew Moon](https://github.com/floodyberry)
444 Contributors have dedicated their work to the public domain.
446 This software is distributed without any warranty.
449 Third-party libraries based on TweetNaCl.js
450 -------------------------------------------
452 * [forward-secrecy](https://github.com/alax/forward-secrecy) — Axolotl ratchet implementation
453 * [nacl-stream](https://github.com/dchest/nacl-stream-js) - streaming encryption
454 * [tweetnacl-auth-js](https://github.com/dchest/tweetnacl-auth-js) — implementation of [`crypto_auth`](http://nacl.cr.yp.to/auth.html)
460 Some notable users of TweetNaCl.js:
462 * [miniLock](http://minilock.io/)
463 * [Stellar](https://www.stellar.org/)