# TweetNaCl.js

ES6 version of the tweetnacl-js `nacl-fast.js`

Work in browser and in node (with "-r esm")

# Documentation

See tweetnacl-js

## Usage

```
import nacl from './tweetnacl-es6.js';
```

All API functions accept and return bytes as `Uint8Array`

s. If you need to
encode or decode strings, use functions from
https://github.com/dchest/tweetnacl-util-js or one of the more robust codec
packages.

In Node.js v4 and later `Buffer`

objects are backed by `Uint8Array`

s, so you
can freely pass them to TweetNaCl.js functions as arguments. The returned
objects are still `Uint8Array`

s, so if you need `Buffer`

s, you'll have to
convert them manually; make sure to convert using copying: `Buffer.from(array)`

(or `new Buffer(array)`

in Node.js v4 or earlier), instead 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*.

#### nacl.box.keyPair()

Generates a new 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
}
```

#### nacl.box.keyPair.fromSecretKey(secretKey)

Returns a key pair for box with public key corresponding to the given secret key.

#### nacl.box(message, nonce, theirPublicKey, mySecretKey)

Encrypts and authenticates message using peer's public key, our secret key, and the given nonce, which must be unique for each distinct message for a key pair.

Returns an encrypted and authenticated message, which is
`nacl.box.overheadLength`

longer than the original message.

#### nacl.box.open(box, nonce, theirPublicKey, mySecretKey)

Authenticates and decrypts the given box with peer's public key, our secret key, and the given nonce.

Returns the original message, or `null`

if authentication fails.

#### nacl.box.before(theirPublicKey, mySecretKey)

Returns a precomputed shared key which can be used in `nacl.box.after`

and
`nacl.box.open.after`

.

#### nacl.box.after(message, nonce, sharedKey)

Same as `nacl.box`

, but uses a shared key precomputed with `nacl.box.before`

.

#### nacl.box.open.after(box, nonce, sharedKey)

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 secret key in bytes.

##### nacl.box.sharedKeyLength = 32

Length of precomputed shared key in bytes.

##### nacl.box.nonceLength = 24

Length of nonce in bytes.

##### nacl.box.overheadLength = 16

Length of overhead added to box compared to original message.

### Secret-key authenticated encryption (secretbox)

Implements *xsalsa20-poly1305*.

#### nacl.secretbox(message, nonce, key)

Encrypts and authenticates message using the key and the nonce. The nonce must be unique for each distinct message for this key.

Returns an encrypted and authenticated message, which is
`nacl.secretbox.overheadLength`

longer than the original message.

#### nacl.secretbox.open(box, nonce, key)

Authenticates and decrypts the given secret box using the key and the nonce.

Returns the original message, or `null`

if authentication fails.

#### Constants

##### nacl.secretbox.keyLength = 32

Length of key in bytes.

##### nacl.secretbox.nonceLength = 24

Length of nonce in bytes.

##### nacl.secretbox.overheadLength = 16

Length of overhead added to secret box compared to original message.

### Scalar multiplication

Implements *x25519*.

#### nacl.scalarMult(n, p)

Multiplies an integer `n`

by a group element `p`

and returns the resulting
group element.

#### nacl.scalarMult.base(n)

Multiplies an integer `n`

by a standard group element and returns the resulting
group element.

#### Constants

##### nacl.scalarMult.scalarLength = 32

Length of scalar in bytes.

##### nacl.scalarMult.groupElementLength = 32

Length of group element in bytes.

### Signatures

Implements ed25519.

#### nacl.sign.keyPair()

Generates new random key pair for signing and returns it as an object with
`publicKey`

and `secretKey`

members:

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

#### nacl.sign.keyPair.fromSecretKey(secretKey)

Returns a signing key pair with public key corresponding to the given
64-byte secret key. The secret key must have been generated by
`nacl.sign.keyPair`

or `nacl.sign.keyPair.fromSeed`

.

#### nacl.sign.keyPair.fromSeed(seed)

Returns a new signing key pair generated deterministically from a 32-byte seed.
The seed must contain enough entropy to be secure. This method is not
recommended for general use: instead, use `nacl.sign.keyPair`

to generate a new
key pair from a random seed.

#### nacl.sign(message, secretKey)

Signs the message using the secret key and returns a signed message.

#### nacl.sign.open(signedMessage, publicKey)

Verifies the signed message and returns the message without signature.

Returns `null`

if verification failed.

#### nacl.sign.detached(message, secretKey)

Signs the message using the secret key and returns a signature.

#### nacl.sign.detached.verify(message, signature, publicKey)

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 public key in bytes.

##### nacl.sign.secretKeyLength = 64

Length of signing secret key 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*.

#### nacl.hash(message)

Returns SHA-512 hash of the message.

#### Constants

##### nacl.hash.hashLength = 64

Length of hash in bytes.

### Random bytes generation

#### nacl.randomBytes(length)

Returns a `Uint8Array`

of the given length containing random bytes of
cryptographic quality.

**Implementation note**

TweetNaCl.js uses the following 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 doesn'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 doesn't implement secure random number
generator, but you somehow have a cryptographically-strong source of entropy
(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* internal random byte generator
with the one provided.

### Constant-time comparison

#### nacl.verify(x, y)

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.

### Testing

To run test in Node.js:

```
$ npm run test-all
$ npm run test-quick
```

To run itest in browser:

### Benchmarking

To run benchmarks in Node.js:

```
$ npm run bench
```

To run itest in browser:

## Contributors

See AUTHORS.md file.