@webcrypto/tools

Web Crypto Tools

This project is a set of tools to facilitate and give good defaults for use of the native Web Crypto API.

This project depends on the browser implementation of Crypto API and TextEncoder API, which are both current implemented on all green browsers. If you do need to support IE or any older browser, you should look for available polyfills.

The native browser implementation of crypto algorithms are much more fast and secure than any other JavaScript library out there. But at the same time, it is a low level API that relies on you to decide every little detail of it, so this project will give you good defaults and a better developer experience, and still let you decide if you prefer use other algorithms or extra protections. Be aware that, even if this project facilitates the use of the Web Crypto API, it will not prevent you from make any mistakes if you have no idea about cryptography concepts, so take your time to study a little before use it in a real project.

In the end, this is a simple collection of stateless functions, values and types, that can be individually imported and used. The minified project has currently only about 3kb in total and it is also tree-shaking friendly, so you can end up using even less.

:gear: Usage

Install it at your project

npm install @webcrypto/tools --save

Encrypt everything

import {
  generateBaseCryptoKey,
  deriveCryptKey,
  generateSalt,
  encryptValue,
  decryptValue,
  decode,
} from '@webcrypto/tools';

// get any data, string or typed arrays
const originalData = 'any data';

// create a secure base key that cannot be reverted to the original key value
const baseKey = await generateBaseCryptoKey('any raw key');

// create new keys for each crypto operation from the base key
const cryptoKey = await deriveCryptKey(baseKey, generateSalt());

// encrypt any value with military level security
const [cryptoValue, nonce] = await encryptValue(originalData, cryptoKey);

// decrypt your value when necessary
const decryptedValue = await decryptValue(cryptoValue, cryptoKey, nonce);

// the decrypted value should be the same of the original
expect(originalData).toEqual(decode(decryptedValue));

:book: Documentation

The documentation with all available API and options at our GitHub Pages.

The test cases are also quite readable and can be used as example for all the possible API uses.

License

MIT

Changelog

1.2.0 (2020-10-26)

Features

• getCryptoObject: method to get the crypto object depending on the environment (bac4919)