README.md (13166B)
1 TweetNaCl.js 2 ============ 3 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. 6 7 [ 8 ](https://travis-ci.org/dchest/tweetnacl-js) 9 10 Demo: <https://tweetnacl.js.org> 11 12 **:warning: The library is stable and API is frozen, however it has not been 13 independently reviewed. If you can help reviewing it, please [contact 14 me](mailto:dmitry@codingrobots.com).** 15 16 Documentation 17 ============= 18 19 * [Overview](#overview) 20 * [Installation](#installation) 21 * [Usage](#usage) 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) 26 * [Hashing](#hashing) 27 * [Random bytes generation](#random-bytes-generation) 28 * [Constant-time comparison](#constant-time-comparison) 29 * [System requirements](#system-requirements) 30 * [Development and testing](#development-and-testing) 31 * [Benchmarks](#benchmarks) 32 * [Contributors](#contributors) 33 * [Who uses it](#who-uses-it) 34 35 36 Overview 37 -------- 38 39 The primary goal of this project is to produce a translation of TweetNaCl to 40 JavaScript which is as close as possible to the original C implementation, plus 41 a thin layer of idiomatic high-level API on top of it. 42 43 There are two versions, you can use either of them: 44 45 * `nacl.js` is the port of TweetNaCl with minimum differences from the 46 original + high-level API. 47 48 * `nacl-fast.js` is like `nacl.js`, but with some functions replaced with 49 faster versions. 50 51 52 Installation 53 ------------ 54 55 You can install TweetNaCl.js via a package manager: 56 57 [Bower](http://bower.io): 58 59 $ bower install tweetnacl 60 61 [NPM](https://www.npmjs.org/): 62 63 $ npm install tweetnacl 64 65 or [download source code](https://github.com/dchest/tweetnacl-js/releases). 66 67 68 Usage 69 ----- 70 71 All API functions accept and return bytes as `Uint8Array`s. If you need to 72 encode or decode strings, use functions from 73 <https://github.com/dchest/tweetnacl-util-js> or one of the more robust codec 74 packages. 75 76 In Node.js v4 and later `Buffer` objects are backed by `Uint8Array`s, so you 77 can freely pass them to TweetNaCl.js functions as arguments. The returned 78 objects are still `Uint8Array`s, so if you need `Buffer`s, you'll have to 79 convert them manually; make sure to convert using copying: `new Buffer(array)`, 80 instead of sharing: `new Buffer(array.buffer)`, because some functions return 81 subarrays of their buffers. 82 83 84 ### Public-key authenticated encryption (box) 85 86 Implements *curve25519-xsalsa20-poly1305*. 87 88 #### nacl.box.keyPair() 89 90 Generates a new random key pair for box and returns it as an object with 91 `publicKey` and `secretKey` members: 92 93 { 94 publicKey: ..., // Uint8Array with 32-byte public key 95 secretKey: ... // Uint8Array with 32-byte secret key 96 } 97 98 99 #### nacl.box.keyPair.fromSecretKey(secretKey) 100 101 Returns a key pair for box with public key corresponding to the given secret 102 key. 103 104 #### nacl.box(message, nonce, theirPublicKey, mySecretKey) 105 106 Encrypt and authenticates message using peer's public key, our secret key, and 107 the given nonce, which must be unique for each distinct message for a key pair. 108 109 Returns an encrypted and authenticated message, which is 110 `nacl.box.overheadLength` longer than the original message. 111 112 #### nacl.box.open(box, nonce, theirPublicKey, mySecretKey) 113 114 Authenticates and decrypts the given box with peer's public key, our secret 115 key, and the given nonce. 116 117 Returns the original message, or `false` if authentication fails. 118 119 #### nacl.box.before(theirPublicKey, mySecretKey) 120 121 Returns a precomputed shared key which can be used in `nacl.box.after` and 122 `nacl.box.open.after`. 123 124 #### nacl.box.after(message, nonce, sharedKey) 125 126 Same as `nacl.box`, but uses a shared key precomputed with `nacl.box.before`. 127 128 #### nacl.box.open.after(box, nonce, sharedKey) 129 130 Same as `nacl.box.open`, but uses a shared key precomputed with `nacl.box.before`. 131 132 #### nacl.box.publicKeyLength = 32 133 134 Length of public key in bytes. 135 136 #### nacl.box.secretKeyLength = 32 137 138 Length of secret key in bytes. 139 140 #### nacl.box.sharedKeyLength = 32 141 142 Length of precomputed shared key in bytes. 143 144 #### nacl.box.nonceLength = 24 145 146 Length of nonce in bytes. 147 148 #### nacl.box.overheadLength = 16 149 150 Length of overhead added to box compared to original message. 151 152 153 ### Secret-key authenticated encryption (secretbox) 154 155 Implements *xsalsa20-poly1305*. 156 157 #### nacl.secretbox(message, nonce, key) 158 159 Encrypt and authenticates message using the key and the nonce. The nonce must 160 be unique for each distinct message for this key. 161 162 Returns an encrypted and authenticated message, which is 163 `nacl.secretbox.overheadLength` longer than the original message. 164 165 #### nacl.secretbox.open(box, nonce, key) 166 167 Authenticates and decrypts the given secret box using the key and the nonce. 168 169 Returns the original message, or `false` if authentication fails. 170 171 #### nacl.secretbox.keyLength = 32 172 173 Length of key in bytes. 174 175 #### nacl.secretbox.nonceLength = 24 176 177 Length of nonce in bytes. 178 179 #### nacl.secretbox.overheadLength = 16 180 181 Length of overhead added to secret box compared to original message. 182 183 184 ### Scalar multiplication 185 186 Implements *curve25519*. 187 188 #### nacl.scalarMult(n, p) 189 190 Multiplies an integer `n` by a group element `p` and returns the resulting 191 group element. 192 193 #### nacl.scalarMult.base(n) 194 195 Multiplies an integer `n` by a standard group element and returns the resulting 196 group element. 197 198 #### nacl.scalarMult.scalarLength = 32 199 200 Length of scalar in bytes. 201 202 #### nacl.scalarMult.groupElementLength = 32 203 204 Length of group element in bytes. 205 206 207 ### Signatures 208 209 Implements [ed25519](http://ed25519.cr.yp.to). 210 211 #### nacl.sign.keyPair() 212 213 Generates new random key pair for signing and returns it as an object with 214 `publicKey` and `secretKey` members: 215 216 { 217 publicKey: ..., // Uint8Array with 32-byte public key 218 secretKey: ... // Uint8Array with 64-byte secret key 219 } 220 221 #### nacl.sign.keyPair.fromSecretKey(secretKey) 222 223 Returns a signing key pair with public key corresponding to the given 224 64-byte secret key. The secret key must have been generated by 225 `nacl.sign.keyPair` or `nacl.sign.keyPair.fromSeed`. 226 227 #### nacl.sign.keyPair.fromSeed(seed) 228 229 Returns a new signing key pair generated deterministically from a 32-byte seed. 230 The seed must contain enough entropy to be secure. This method is not 231 recommended for general use: instead, use `nacl.sign.keyPair` to generate a new 232 key pair from a random seed. 233 234 #### nacl.sign(message, secretKey) 235 236 Signs the message using the secret key and returns a signed message. 237 238 #### nacl.sign.open(signedMessage, publicKey) 239 240 Verifies the signed message and returns the message without signature. 241 242 Returns `null` if verification failed. 243 244 #### nacl.sign.detached(message, secretKey) 245 246 Signs the message using the secret key and returns a signature. 247 248 #### nacl.sign.detached.verify(message, signature, publicKey) 249 250 Verifies the signature for the message and returns `true` if verification 251 succeeded or `false` if it failed. 252 253 #### nacl.sign.publicKeyLength = 32 254 255 Length of signing public key in bytes. 256 257 #### nacl.sign.secretKeyLength = 64 258 259 Length of signing secret key in bytes. 260 261 #### nacl.sign.seedLength = 32 262 263 Length of seed for `nacl.sign.keyPair.fromSeed` in bytes. 264 265 #### nacl.sign.signatureLength = 64 266 267 Length of signature in bytes. 268 269 270 ### Hashing 271 272 Implements *SHA-512*. 273 274 #### nacl.hash(message) 275 276 Returns SHA-512 hash of the message. 277 278 #### nacl.hash.hashLength = 64 279 280 Length of hash in bytes. 281 282 283 ### Random bytes generation 284 285 #### nacl.randomBytes(length) 286 287 Returns a `Uint8Array` of the given length containing random bytes of 288 cryptographic quality. 289 290 **Implementation note** 291 292 TweetNaCl.js uses the following methods to generate random bytes, 293 depending on the platform it runs on: 294 295 * `window.crypto.getRandomValues` (WebCrypto standard) 296 * `window.msCrypto.getRandomValues` (Internet Explorer 11) 297 * `crypto.randomBytes` (Node.js) 298 299 If the platform doesn't provide a suitable PRNG, the following functions, 300 which require random numbers, will throw exception: 301 302 * `nacl.randomBytes` 303 * `nacl.box.keyPair` 304 * `nacl.sign.keyPair` 305 306 Other functions are deterministic and will continue working. 307 308 If a platform you are targeting doesn't implement secure random number 309 generator, but you somehow have a cryptographically-strong source of entropy 310 (not `Math.random`!), and you know what you are doing, you can plug it into 311 TweetNaCl.js like this: 312 313 nacl.setPRNG(function(x, n) { 314 // ... copy n random bytes into x ... 315 }); 316 317 Note that `nacl.setPRNG` *completely replaces* internal random byte generator 318 with the one provided. 319 320 321 ### Constant-time comparison 322 323 #### nacl.verify(x, y) 324 325 Compares `x` and `y` in constant time and returns `true` if their lengths are 326 non-zero and equal, and their contents are equal. 327 328 Returns `false` if either of the arguments has zero length, or arguments have 329 different lengths, or their contents differ. 330 331 332 System requirements 333 ------------------- 334 335 TweetNaCl.js supports modern browsers that have a cryptographically secure 336 pseudorandom number generator and typed arrays, including the latest versions 337 of: 338 339 * Chrome 340 * Firefox 341 * Safari (Mac, iOS) 342 * Internet Explorer 11 343 344 Other systems: 345 346 * Node.js 347 348 349 Development and testing 350 ------------------------ 351 352 Install NPM modules needed for development: 353 354 $ npm install 355 356 To build minified versions: 357 358 $ npm run build 359 360 Tests use minified version, so make sure to rebuild it every time you change 361 `nacl.js` or `nacl-fast.js`. 362 363 ### Testing 364 365 To run tests in Node.js: 366 367 $ npm run test-node 368 369 By default all tests described here work on `nacl.min.js`. To test other 370 versions, set environment variable `NACL_SRC` to the file name you want to test. 371 For example, the following command will test fast minified version: 372 373 $ NACL_SRC=nacl-fast.min.js npm run test-node 374 375 To run full suite of tests in Node.js, including comparing outputs of 376 JavaScript port to outputs of the original C version: 377 378 $ npm run test-node-all 379 380 To prepare tests for browsers: 381 382 $ npm run build-test-browser 383 384 and then open `test/browser/test.html` (or `test/browser/test-fast.html`) to 385 run them. 386 387 To run headless browser tests with `tape-run` (powered by Electron): 388 389 $ npm run test-browser 390 391 (If you get `Error: spawn ENOENT`, install *xvfb*: `sudo apt-get install xvfb`.) 392 393 To run tests in both Node and Electron: 394 395 $ npm test 396 397 ### Benchmarking 398 399 To run benchmarks in Node.js: 400 401 $ npm run bench 402 $ NACL_SRC=nacl-fast.min.js npm run bench 403 404 To run benchmarks in a browser, open `test/benchmark/bench.html` (or 405 `test/benchmark/bench-fast.html`). 406 407 408 Benchmarks 409 ---------- 410 411 For reference, here are benchmarks from MacBook Pro (Retina, 13-inch, Mid 2014) 412 laptop with 2.6 GHz Intel Core i5 CPU (Intel) in Chrome 53/OS X and Xiaomi Redmi 413 Note 3 smartphone with 1.8 GHz Qualcomm Snapdragon 650 64-bit CPU (ARM) in 414 Chrome 52/Android: 415 416 | | nacl.js Intel | nacl-fast.js Intel | nacl.js ARM | nacl-fast.js ARM | 417 | ------------- |:-------------:|:-------------------:|:-------------:|:-----------------:| 418 | salsa20 | 1.3 MB/s | 128 MB/s | 0.4 MB/s | 43 MB/s | 419 | poly1305 | 13 MB/s | 171 MB/s | 4 MB/s | 52 MB/s | 420 | hash | 4 MB/s | 34 MB/s | 0.9 MB/s | 12 MB/s | 421 | secretbox 1K | 1113 op/s | 57583 op/s | 334 op/s | 14227 op/s | 422 | box 1K | 145 op/s | 718 op/s | 37 op/s | 368 op/s | 423 | scalarMult | 171 op/s | 733 op/s | 56 op/s | 380 op/s | 424 | sign | 77 op/s | 200 op/s | 20 op/s | 61 op/s | 425 | sign.open | 39 op/s | 102 op/s | 11 op/s | 31 op/s | 426 427 (You can run benchmarks on your devices by clicking on the links at the bottom 428 of the [home page](https://tweetnacl.js.org)). 429 430 In short, with *nacl-fast.js* and 1024-byte messages you can expect to encrypt and 431 authenticate more than 57000 messages per second on a typical laptop or more than 432 14000 messages per second on a $170 smartphone, sign about 200 and verify 100 433 messages per second on a laptop or 60 and 30 messages per second on a smartphone, 434 per CPU core (with Web Workers you can do these operations in parallel), 435 which is good enough for most applications. 436 437 438 Contributors 439 ------------ 440 441 See AUTHORS.md file. 442 443 444 Third-party libraries based on TweetNaCl.js 445 ------------------------------------------- 446 447 * [forward-secrecy](https://github.com/alax/forward-secrecy) — Axolotl ratchet implementation 448 * [nacl-stream](https://github.com/dchest/nacl-stream-js) - streaming encryption 449 * [tweetnacl-auth-js](https://github.com/dchest/tweetnacl-auth-js) — implementation of [`crypto_auth`](http://nacl.cr.yp.to/auth.html) 450 * [chloride](https://github.com/dominictarr/chloride) - unified API for various NaCl modules 451 452 453 Who uses it 454 ----------- 455 456 Some notable users of TweetNaCl.js: 457 458 * [miniLock](http://minilock.io/) 459 * [Stellar](https://www.stellar.org/)