TweetNaCl.js

TweetNaCl.js is a low-level library. Users should be aware of the following properties of its primitives:

• No secret key commitment: nacl.secretbox and nacl.box are not key-committing; a ciphertext might decrypt to valid plaintexts under different keys.
• Signature malleability: Ed25519 signatures (nacl.sign) are malleable; one can create a different valid signature for the same message without the secret key.
• Hash length-extension: The SHA-512 implementation (nacl.hash) is not resistant to length-extension attacks.
• Side-channel attacks: While using algorithmic constant-time operations, physical constant-time execution cannot be guaranteed due to JavaScript runtimes and JIT compilers.

You can install TweetNaCl.js using your preferred package manager or by downloading the source code directly from the releases page.

yarn add tweetnacl
# or
npm install tweetnacl

If your platform lacks a secure random number generator but you have a cryptographically strong source of entropy, you can replace the internal generator using nacl.setPRNG.

nacl.setPRNG(function(x, n) {
  // ... copy n random bytes into x ...
});

Implements x25519-xsalsa20-poly1305. This allows two parties to communicate securely using their respective public and secret keys.

All functions accept and return Uint8Arrays. If you are using Node.js, you can pass Buffer objects directly as they are backed by Uint8Arrays. However, when converting returned Uint8Arrays back to Buffers, use Buffer.from(array) to ensure a copy is made, as some functions return subarrays of their buffers.

crypto_box_keypair generates a new random private key and its corresponding public key. It relies on a randombytes function being available in the environment.

Parameters:

• y: Output buffer for the public key (32 bytes).
• x: Output buffer for the private key (32 bytes).

Use nacl.secretbox to encrypt a message using a shared secret key and a nonce. Use nacl.secretbox.open to decrypt it. Both functions require Uint8Array inputs.

Constants:

• nacl.secretbox.keyLength: 32 bytes
• nacl.secretbox.nonceLength: 24 bytes
• nacl.secretbox.overheadLength: 16 bytes

crypto_box_open decrypts and verifies a ciphertext using the public keys of both parties. If the authentication fails (e.g., due to tampering), it returns -1 and the output buffer m is not considered valid.

Parameters:

• m: Output buffer for the decrypted message.
• c: Input buffer containing the ciphertext.
• d: Length of the ciphertext.
• n: Nonce (must be 24 bytes).
• y: Public key of the sender.
• x: Public key of the recipient.

crypto_box provides authenticated encryption using a public key from one party and a public key from another. It uses crypto_box_beforenm internally to derive a shared secret before performing encryption via crypto_secretbox.

Parameters:

• c: Output buffer for the ciphertext.
• m: Input buffer containing the message.
• d: Length of the message.
• n: Nonce (must be 24 bytes).
• y: Public key of the recipient.
• x: Public key of the sender.