Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/katyo/tweetnacl-ts

Port of TweetNaCl cryptographic library to TypeScript (and ES6)
https://github.com/katyo/tweetnacl-ts
Last synced: 2 months ago
JSON representation
Port of TweetNaCl cryptographic library to TypeScript (and ES6)
Host: GitHub
URL: https://github.com/katyo/tweetnacl-ts
Owner: katyo
License: unlicense
Created: 2018-04-18T04:26:03.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2021-11-30T09:34:32.000Z (about 3 years ago)
Last Synced: 2024-09-28T02:45:23.738Z (3 months ago)
Language: TypeScript
Size: 3.08 MB
Stars: 11
Watchers: 3
Forks: 7
Open Issues: 2
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.tweetnacl-js.md
- License: LICENSE
Awesome Lists containing this project

README

        # TweetNaCl in TypeScript (and ES6)

[![npm version](https://badge.fury.io/js/tweetnacl-ts.svg)](https://badge.fury.io/js/tweetnacl-ts)

[![npm downloads](https://img.shields.io/npm/dm/tweetnacl-ts.svg)](https://www.npmjs.com/package/tweetnacl-ts)

[![Build Status](https://travis-ci.org/katyo/tweetnacl-ts.svg?branch=master)](https://travis-ci.org/katyo/tweetnacl-ts)

Port of [TweetNaCl.js](https://tweetnacl.js.org) 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:

* [TweetNaCl-Auth.js](https://github.com/dchest/tweetnacl-auth-js)

* [TweetNaCl-Utils.js](https://github.com/dchest/tweetnacl-util-js)

* [BlakeJS](https://github.com/dcposch/blakejs)

* [TweetNaCl-SealedBox.js](https://github.com/whs/tweetnacl-sealed-box)

__NOTE: May be you need `crypto.getRandomValues()` polyfill for browsers which doesn't supported it.__

Documentation

=============

* [Overview](#overview)

* [Usage](#usage)

  * [Public-key authenticated encryption (box)](#public-key-authenticated-encryption-box)

  * [Secret-key authenticated encryption (secretbox)](#secret-key-authenticated-encryption-secretbox)

  * [Scalar multiplication](#scalar-multiplication)

  * [Signatures](#signatures)

  * [Hashing](#hashing)

  * [Random bytes generation](#random-bytes-generation)

  * [Constant-time comparison](#constant-time-comparison)

* [System requirements](#system-requirements)

* [Development and testing](#development-and-testing)

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:

```typescript

interface BoxKeyPair {

    publicKey: ByteArray; // Array with 32-byte public key

    secretKey: ByteArray; // Array with 32-byte secret key

}

```

#### 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](http://ed25519.cr.yp.to).

#### sign\_keyPair()

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

`publicKey` and `secretKey` members:

```typescript

interface SignKeyPair {

    publicKey: ByteArray; // Array with 32-byte public key

    secretKey: ByteArray; // Array with 64-byte secret key

}

```

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