tweetnacl-blake2b - npm explorer

TweetNaCl-blake2b.js
============

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

Documentation
=============

* Overview
* Audits
* Installation
* Usage
* Public-key authenticated encryption (box)
* Secret-key authenticated encryption (secretbox)
* Scalar multiplication
* Signatures
* Hashing
* Random bytes generation
* Constant-time comparison
* System requirements
* Development and testing
* Benchmarks
* Contributors
* Who uses it

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
original + high-level API.

* nacl-fast.js is like nacl.js, but with some functions replaced with
faster versions. (Used by default when importing NPM package.)

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 Uint8Arrays. 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 Uint8Arrays, so you
can freely pass them to TweetNaCl-blake2b.js functions as arguments. The returned
objects are still Uint8Arrays, so if you need Buffers, 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.

$3

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.

$3

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.

$3

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.

$3

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.

$3

Implements SHA-512.

#### nacl.hash(message)

Returns SHA-512 hash of the message.

#### nacl.hash.hashLength = 64

Length of hash in bytes.

$3

#### 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.

$3

#### 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.

Contributors
------------

See AUTHORS.md file.

TweetNaCl-blake2b.js
============

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

Documentation
=============

Overview
--------

There are two versions, you can use either of them:

* nacl.js is the port of TweetNaCl with minimum differences from the
original + high-level API.

* nacl-fast.js is like nacl.js, but with some functions replaced with
faster versions. (Used by default when importing NPM package.)

Audits
------

TweetNaCl.js (parent project) has been audited by Cure53 in January-February
2017 (audit was sponsored by Deletype):

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 Uint8Arrays. If you need to
encode or decode strings, use functions from
or one of the more robust codec
packages.

$3

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.

$3

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.

$3

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.

$3

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)

#### 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.

$3

Implements SHA-512.

#### nacl.hash(message)

Returns SHA-512 hash of the message.

#### nacl.hash.hashLength = 64

Length of hash in bytes.

$3

#### 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.

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.

$3

#### 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.

Contributors
------------

See AUTHORS.md file.