org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/request/node_modules/http-signature/node_modules/sshpk/node_modules/tweetnacl/README.md

   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 [![Build Status](https://travis-ci.org/dchest/tweetnacl-js.svg?branch=master)
   8 ](https://travis-ci.org/dchest/tweetnacl-js)
   9
  10 [Demo](https://dchest.github.io/tweetnacl-js/)
  11
  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).**
  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   * [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)
  35
  36
  37 Overview
  38 --------
  39
  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.
  43
  44 There are two versions, you can use either of them:
  45
  46 * `nacl.js` is the port of TweetNaCl with minimum differences from the
  47   original + high-level API.
  48
  49 * `nacl-fast.js` is like `nacl.js`, but with some functions replaced with
  50   faster versions.
  51
  52
  53 Installation
  54 ------------
  55
  56 You can install TweetNaCl.js via a package manager:
  57
  58 [Bower](http://bower.io):
  59
  60     $ bower install tweetnacl
  61
  62 [NPM](https://www.npmjs.org/):
  63
  64     $ npm install tweetnacl
  65
  66 or [download source code](https://github.com/dchest/tweetnacl-js/releases).
  67
  68
  69 Usage
  70 ------
  71
  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.
  74
  75 ### Public-key authenticated encryption (box)
  76
  77 Implements *curve25519-xsalsa20-poly1305*.
  78
  79 #### nacl.box.keyPair()
  80
  81 Generates a new random key pair for box and returns it as an object with
  82 `publicKey` and `secretKey` members:
  83
  84     {
  85        publicKey: ...,  // Uint8Array with 32-byte public key
  86        secretKey: ...   // Uint8Array with 32-byte secret key
  87     }
  88
  89
  90 #### nacl.box.keyPair.fromSecretKey(secretKey)
  91
  92 Returns a key pair for box with public key corresponding to the given secret
  93 key.
  94
  95 #### nacl.box(message, nonce, theirPublicKey, mySecretKey)
  96
  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.
  99
 100 Returns an encrypted and authenticated message, which is
 101 `nacl.box.overheadLength` longer than the original message.
 102
 103 #### nacl.box.open(box, nonce, theirPublicKey, mySecretKey)
 104
 105 Authenticates and decrypts the given box with peer's public key, our secret
 106 key, and the given nonce.
 107
 108 Returns the original message, or `false` if authentication fails.
 109
 110 #### nacl.box.before(theirPublicKey, mySecretKey)
 111
 112 Returns a precomputed shared key which can be used in `nacl.box.after` and
 113 `nacl.box.open.after`.
 114
 115 #### nacl.box.after(message, nonce, sharedKey)
 116
 117 Same as `nacl.box`, but uses a shared key precomputed with `nacl.box.before`.
 118
 119 #### nacl.box.open.after(box, nonce, sharedKey)
 120
 121 Same as `nacl.box.open`, but uses a shared key precomputed with `nacl.box.before`.
 122
 123 #### nacl.box.publicKeyLength = 32
 124
 125 Length of public key in bytes.
 126
 127 #### nacl.box.secretKeyLength = 32
 128
 129 Length of secret key in bytes.
 130
 131 #### nacl.box.sharedKeyLength = 32
 132
 133 Length of precomputed shared key in bytes.
 134
 135 #### nacl.box.nonceLength = 24
 136
 137 Length of nonce in bytes.
 138
 139 #### nacl.box.overheadLength = 16
 140
 141 Length of overhead added to box compared to original message.
 142
 143
 144 ### Secret-key authenticated encryption (secretbox)
 145
 146 Implements *xsalsa20-poly1305*.
 147
 148 #### nacl.secretbox(message, nonce, key)
 149
 150 Encrypt and authenticates message using the key and the nonce. The nonce must
 151 be unique for each distinct message for this key.
 152
 153 Returns an encrypted and authenticated message, which is
 154 `nacl.secretbox.overheadLength` longer than the original message.
 155
 156 #### nacl.secretbox.open(box, nonce, key)
 157
 158 Authenticates and decrypts the given secret box using the key and the nonce.
 159
 160 Returns the original message, or `false` if authentication fails.
 161
 162 #### nacl.secretbox.keyLength = 32
 163
 164 Length of key in bytes.
 165
 166 #### nacl.secretbox.nonceLength = 24
 167
 168 Length of nonce in bytes.
 169
 170 #### nacl.secretbox.overheadLength = 16
 171
 172 Length of overhead added to secret box compared to original message.
 173
 174
 175 ### Scalar multiplication
 176
 177 Implements *curve25519*.
 178
 179 #### nacl.scalarMult(n, p)
 180
 181 Multiplies an integer `n` by a group element `p` and returns the resulting
 182 group element.
 183
 184 #### nacl.scalarMult.base(n)
 185
 186 Multiplies an integer `n` by a standard group element and returns the resulting
 187 group element.
 188
 189 #### nacl.scalarMult.scalarLength = 32
 190
 191 Length of scalar in bytes.
 192
 193 #### nacl.scalarMult.groupElementLength = 32
 194
 195 Length of group element in bytes.
 196
 197
 198 ### Signatures
 199
 200 Implements [ed25519](http://ed25519.cr.yp.to).
 201
 202 #### nacl.sign.keyPair()
 203
 204 Generates new random key pair for signing and returns it as an object with
 205 `publicKey` and `secretKey` members:
 206
 207     {
 208        publicKey: ...,  // Uint8Array with 32-byte public key
 209        secretKey: ...   // Uint8Array with 64-byte secret key
 210     }
 211
 212 #### nacl.sign.keyPair.fromSecretKey(secretKey)
 213
 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`.
 217
 218 #### nacl.sign.keyPair.fromSeed(seed)
 219
 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.
 224
 225 #### nacl.sign(message, secretKey)
 226
 227 Signs the message using the secret key and returns a signed message.
 228
 229 #### nacl.sign.open(signedMessage, publicKey)
 230
 231 Verifies the signed message and returns the message without signature.
 232
 233 Returns `null` if verification failed.
 234
 235 #### nacl.sign.detached(message, secretKey)
 236
 237 Signs the message using the secret key and returns a signature.
 238
 239 #### nacl.sign.detached.verify(message, signature, publicKey)
 240
 241 Verifies the signature for the message and returns `true` if verification
 242 succeeded or `false` if it failed.
 243
 244 #### nacl.sign.publicKeyLength = 32
 245
 246 Length of signing public key in bytes.
 247
 248 #### nacl.sign.secretKeyLength = 64
 249
 250 Length of signing secret key in bytes.
 251
 252 #### nacl.sign.seedLength = 32
 253
 254 Length of seed for `nacl.sign.keyPair.fromSeed` in bytes.
 255
 256 #### nacl.sign.signatureLength = 64
 257
 258 Length of signature in bytes.
 259
 260
 261 ### Hashing
 262
 263 Implements *SHA-512*.
 264
 265 #### nacl.hash(message)
 266
 267 Returns SHA-512 hash of the message.
 268
 269 #### nacl.hash.hashLength = 64
 270
 271 Length of hash in bytes.
 272
 273
 274 ### Random bytes generation
 275
 276 #### nacl.randomBytes(length)
 277
 278 Returns a `Uint8Array` of the given length containing random bytes of
 279 cryptographic quality.
 280
 281 **Implementation note**
 282
 283 TweetNaCl.js uses the following methods to generate random bytes,
 284 depending on the platform it runs on:
 285
 286 * `window.crypto.getRandomValues` (WebCrypto standard)
 287 * `window.msCrypto.getRandomValues` (Internet Explorer 11)
 288 * `crypto.randomBytes` (Node.js)
 289
 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
 294 consequences).
 295
 296 If the platform doesn't provide a suitable PRNG, the following functions,
 297 which require random numbers, will throw exception:
 298
 299 * `nacl.randomBytes`
 300 * `nacl.box.keyPair`
 301 * `nacl.sign.keyPair`
 302
 303 Other functions are deterministic and will continue working.
 304
 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:
 309
 310     nacl.setPRNG(function(x, n) {
 311       // ... copy n random bytes into x ...
 312     });
 313
 314 Note that `nacl.setPRNG` *completely replaces* internal random byte generator
 315 with the one provided.
 316
 317
 318 ### Constant-time comparison
 319
 320 #### nacl.verify(x, y)
 321
 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.
 324
 325 Returns `false` if either of the arguments has zero length, or arguments have
 326 different lengths, or their contents differ.
 327
 328
 329 ### Utilities
 330
 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.
 335
 336 #### nacl.util.decodeUTF8(string)
 337
 338 Decodes string and returns `Uint8Array` of bytes.
 339
 340 #### nacl.util.encodeUTF8(array)
 341
 342 Encodes `Uint8Array` or `Array` of bytes into string.
 343
 344 #### nacl.util.decodeBase64(string)
 345
 346 Decodes Base-64 encoded string and returns `Uint8Array` of bytes.
 347
 348 #### nacl.util.encodeBase64(array)
 349
 350 Encodes `Uint8Array` or `Array` of bytes into string using Base-64 encoding.
 351
 352
 353 System requirements
 354 -------------------
 355
 356 TweetNaCl.js supports modern browsers that have a cryptographically secure
 357 pseudorandom number generator and typed arrays, including the latest versions
 358 of:
 359
 360 * Chrome
 361 * Firefox
 362 * Safari (Mac, iOS)
 363 * Internet Explorer 11
 364
 365 Other systems:
 366
 367 * Node.js (we test on 0.10 and later)
 368
 369
 370 Development and testing
 371 ------------------------
 372
 373 Install NPM modules needed for development:
 374
 375     $ npm install
 376
 377 To build minified versions:
 378
 379     $ npm run build
 380
 381 Tests use minified version, so make sure to rebuild it every time you change
 382 `nacl.js` or `nacl-fast.js`.
 383
 384 ### Testing
 385
 386 To run tests in Node.js:
 387
 388     $ npm test
 389
 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:
 393
 394     $ NACL_SRC=nacl-fast.min.js npm test
 395
 396 To run full suite of tests in Node.js, including comparing outputs of
 397 JavaScript port to outputs of the original C version:
 398
 399     $ npm run testall
 400
 401 To prepare tests for browsers:
 402
 403     $ npm run browser
 404
 405 and then open `test/browser/test.html` (or `test/browser/test-fast.html`) to
 406 run them.
 407
 408 To run headless browser tests with `testling`:
 409
 410     $ npm run testling
 411
 412 (If you get `Error: spawn ENOENT`, install *xvfb*: `sudo apt-get install xvfb`.)
 413
 414 ### Benchmarking
 415
 416 To run benchmarks in Node.js:
 417
 418     $ npm run bench
 419     $ NACL_SRC=nacl-fast.min.js npm run bench
 420
 421 To run benchmarks in a browser, open `test/benchmark/bench.html` (or
 422 `test/benchmark/bench-fast.html`).
 423
 424
 425 Contributors
 426 ------------
 427
 428 JavaScript port:
 429
 430  * [Dmitry Chestnykh](http://github.com/dchest) (ported xsalsa20, poly1305, curve25519)
 431  * [Devi Mandiri](https://github.com/devi) (ported curve25519, ed25519, sha512)
 432
 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):
 436
 437   * [Daniel J. Bernstein](http://cr.yp.to/djb.html)
 438   * Wesley Janssen
 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)
 443
 444 Contributors have dedicated their work to the public domain.
 445
 446 This software is distributed without any warranty.
 447
 448
 449 Third-party libraries based on TweetNaCl.js
 450 -------------------------------------------
 451
 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)
 455
 456
 457 Who uses it
 458 -----------
 459
 460 Some notable users of TweetNaCl.js:
 461
 462 * [miniLock](http://minilock.io/)
 463 * [Stellar](https://www.stellar.org/)