TweetNaCl.js
ES6 version of the tweetnacljs naclfast.js
Work in browser and in node (with "r esm")
Documentation
See tweetnacljs
Usage
import nacl from './tweetnacles6.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/tweetnaclutiljs 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)
,
instead of sharing: Buffer.from(array.buffer)
, because some functions
return subarrays of their buffers.
Publickey authenticated encryption (box)
Implements x25519xsalsa20poly1305.
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 32byte public key
secretKey: ... // Uint8Array with 32byte 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.
Secretkey authenticated encryption (secretbox)
Implements xsalsa20poly1305.
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 32byte public key
secretKey: ... // Uint8Array with 64byte secret key
}
nacl.sign.keyPair.fromSecretKey(secretKey)
Returns a signing key pair with public key corresponding to the given
64byte 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 32byte 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 SHA512.
nacl.hash(message)
Returns SHA512 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 cryptographicallystrong 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.
Constanttime comparison
nacl.verify(x, y)
Compares x
and y
in constant time and returns true
if their lengths are
nonzero 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 testall
$ npm run testquick
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.