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
Public-key authenticated encryption (box)
Secret-key authenticated encryption (secretbox)
Scalar multiplication
Signatures
Hashing
Random bytes generation
Constant-time comparisonOverview
Originally this project had been a port ofnacl-fast.js
to TypeScript.
Now it also includes support of SealedBox and HMAC-Auth.Usage
All API functions accept and return bytes asByteArray
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 withpublicKey
and secretKey
members: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 inbox_after
and
box_open_after
.box\_after(message, nonce, sharedKey)
Same asbox
, but uses a shared key precomputed with box_before
.box\_open\_after(box, nonce, sharedKey)
Same asbox_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 integern
by a group element p
and returns the resulting
group element.scalarMult\_base(n)
Multiplies an integern
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 withpublicKey
and secretKey
members: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 bysign_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, usesign_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 returnstrue
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 forsign_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-256auth(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 keyAuthLength.Auth = 32
Length of authenticator returned byauth
.AuthLength.AuthFull = 64
Length of authenticator returned byauth_full
.AuthLength.Key = 32
Length of key forauth
and auth_full
(key length is currently not
enforced).Random bytes generation
randomBytes(length)
Returns aByteArray
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)
Comparesx
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