# TweetNaCl in TypeScript (and ES6)

Port of TweetNaCl.js to **TypeScript** with several API changes for compatibility with Tree-Shaking to help modern JavaScript bundlers like Rollup and Webpack >2.x attain much optimization.

Also includes:

**NOTE: May be you need crypto.getRandomValues() polyfill for browsers which doesn't supported it.**

# Documentation

## Overview

Originally this project had been a port of `nacl-fast.js`

to TypeScript.
Now it also includes support of SealedBox and HMAC-Auth.

## Usage

All API functions accept and return bytes as `ByteArray`

s (natively as `Uint8Array`

s).
If you need to encode or decode strings, use functions `encodeUTF8/decodeUTF8`

.

### Public-key authenticated encryption (box)

Implements *x25519-xsalsa20-poly1305*.

#### box_keyPair()

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

and `secretKey`

members:

#### box_keyPair_fromSecretKey(secretKey)

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

#### 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
`BoxLength.Overhead`

longer than the original message.

#### 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 `undefined`

if authentication fails.

#### box_before(theirPublicKey, mySecretKey)

Returns a precomputed shared key which can be used in `box_after`

and
`box_open_after`

.

#### box_after(message, nonce, sharedKey)

Same as `box`

, but uses a shared key precomputed with `box_before`

.

#### box_open_after(box, nonce, sharedKey)

Same as `box_open`

, but uses a shared key precomputed with `box_before`

.

#### Constants

##### BoxLength.PublicKey = 32

Length of public key in bytes.

##### BoxLength.SecretKey = 32

Length of secret key in bytes.

##### BoxLength.SharedKey = 32

Length of precomputed shared key in bytes.

##### BoxLength.Nonce = 24

Length of nonce in bytes.

##### BoxLength.Overhead = 16

Length of overhead added to box compared to original message.

### Secret-key authenticated encryption (secretbox)

Implements *xsalsa20-poly1305*.

#### 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
`SecretBox.Overhead`

longer than the original message.

#### secretbox_open(box, nonce, key)

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

Returns the original message, or `undefined`

if authentication fails.

#### Constants

##### SecretBoxLength.Key = 32

Length of key in bytes.

##### SecretBoxLength.Nonce = 24

Length of nonce in bytes.

##### SecretBoxLength.Overhead = 16

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

### Sealed box encryption

Sealed boxes are designed to anonymously send messages to a recipient given its public key.

#### sealedbox(message, publicKey)

Encrypts message using the recipient's public key.

Returns an encrypted message, which is `SealedBox.Overhead`

longer than the original message.

#### sealedbox_open(box, publicKey, secretKey)

Decrypts the given sealed box using the recipient's key pair.

Returns the original message, or `undefined`

if decryption fails.

#### Constants

##### SealedBoxLength.PublicKey = 32

Length of public key of recipient in bytes.

##### SealedBoxLength.SecretKey = 32

Length of secret key of recipient in bytes.

##### SealedBoxLength.Nonce = 24

Length of nonce in bytes.

##### SealedBoxLength.Overhead = 48

Length of overhead added to box compared to original message.

### Scalar multiplication

Implements *x25519*.

#### scalarMult(n, p)

Multiplies an integer `n`

by a group element `p`

and returns the resulting
group element.

#### scalarMult_base(n)

Multiplies an integer `n`

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

#### Constants

##### ScalarMultLength.Scalar = 32

Length of scalar in bytes.

##### ScalarMultLength.GroupElement = 32

Length of group element in bytes.

### Signatures

Implements ed25519.

#### sign_keyPair()

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

and `secretKey`

members:

#### 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
`sign_keyPair`

or `sign_keyPair_fromSeed`

.

#### 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 `sign_keyPair`

to generate a new
key pair from a random seed.

#### sign(message, secretKey)

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

#### sign_open(signedMessage, publicKey)

Verifies the signed message and returns the message without signature.

Returns `undefined`

if verification failed.

#### sign_detached(message, secretKey)

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

#### sign_detached_verify(message, signature, publicKey)

Verifies the signature for the message and returns `true`

if verification
succeeded or `false`

if it failed.

#### Constants

##### SignLength.PublicKey = 32

Length of signing public key in bytes.

##### SignLength.SecretKey = 64

Length of signing secret key in bytes.

##### SignLength.Seed = 32

Length of seed for `sign_keyPair_fromSeed`

in bytes.

##### SignLength.Signature = 64

Length of signature in bytes.

### Hashing

Implements *SHA-512*.

#### hash(message)

Returns SHA-512 hash of the message.

#### Constants

##### HashLength.Hash = 64

Length of hash in bytes.

### Authenticating

Implements *HMAC-SHA-512-256*

#### auth(message, key)

Authenticates the given message with the secret key. (In other words, returns HMAC-SHA-512-256 of the message under the key.)

#### auth_full(message, key)

Returns HMAC-SHA-512 (without truncation) of the message under the key

#### AuthLength.Auth = 32

Length of authenticator returned by `auth`

.

#### AuthLength.AuthFull = 64

Length of authenticator returned by `auth_full`

.

#### AuthLength.Key = 32

Length of key for `auth`

and `auth_full`

(key length is currently not
enforced).

### Random bytes generation

#### randomBytes(length)

Returns a `ByteArray`

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:

`randomBytes`

`box_keyPair`

`sign_keyPair`

Other functions are deterministic and will continue working.

### Constant-time comparison

#### 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.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 js run compilation:

```
$ npm run compile
```

### Testing

To run tests in Node:

```
$ npm run test-node
```

To run tests in browsers and Node (CI-mode):

```
$ npm run test
```

To run tests in browsers and Node (Dev-mode):

```
$ npm run test-dev
```