TweetNaCl-blake2b.js

Fork of TweetNaCl (ed25519), but using blake2b instead of sha512 (like raiblocks)Documentation

*Public-key authenticated encryption (box)*

*Secret-key authenticated encryption (secretbox)*

*Scalar multiplication*

*Signatures*

*Hashing*

*Random bytes generation*

*Constant-time comparison*

## Overview

The primary goal of this project is to produce a translation of TweetNaCl using the blake2b hash algorithm instead of sha512 to JavaScript which is as close as possible to the original C implementation, plus a thin 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 minimum differences from the

`nacl-fast.js`

is like`nacl.js`

, but with some functions replaced with

## Audits

TweetNaCl.js (parent project) has been audited by Cure53 in January-February 2017 (audit was sponsored by Deletype):The overall outcome of this audit signals a particularly positive assessment 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 source code audit for any project and must be seen as a true testament to a development proceeding with security at its core.

To reiterate, the TweetNaCl-js project, the source code was found to be bug-free at this point.

...

In sum, the testing team is happy to recommend the TweetNaCl-js project as likely one of the safer and more secure cryptographic tools among its competition.

Read full audit report

## Installation

You can install TweetNaCl-blake2b.js via a package manager:Yarn:

`$ yarn add tweetnacl-blake2b`

NPM:`$ npm install tweetnacl-blake2b`

or download source code.## Usage

All API functions accept and return bytes as`Uint8Array`

s. If you need to
encode or decode strings, use functions from
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-blake2b.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: `new Buffer(array)`

,
instead of sharing: `new Buffer(array.buffer)`

, 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`

.#### 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.#### 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.#### 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.#### 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.#### 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-blake2b.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-blake2b.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.## System requirements

TweetNaCl-blake2b.js supports modern browsers that have a cryptographically secure pseudorandom number 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 development:`$ npm install`

To build minified versions:`$ npm run build`

Tests use minified version, so make sure to rebuild it every time you change
`nacl.js`

or `nacl-fast.js`

.