isomorphic-webcrypto

What is isomorphic-webcrypto?

The isomorphic-webcrypto npm package provides a unified API for cryptographic operations that work seamlessly in both Node.js and browser environments. It leverages the Web Cryptography API to offer a consistent interface for tasks such as encryption, decryption, hashing, and key generation.

What are isomorphic-webcrypto's main functionalities?

Encryption and Decryption

This feature allows you to perform encryption and decryption using the AES-GCM algorithm. The code sample demonstrates generating a key, encrypting a message, and then decrypting it back to its original form.

const crypto = require('isomorphic-webcrypto');

async function encryptDecrypt() {
  const key = await crypto.subtle.generateKey({
    name: 'AES-GCM',
    length: 256
  }, true, ['encrypt', 'decrypt']);

  const data = new TextEncoder().encode('Hello, World!');
  const iv = crypto.getRandomValues(new Uint8Array(12));

  const encrypted = await crypto.subtle.encrypt({
    name: 'AES-GCM',
    iv: iv
  }, key, data);

  const decrypted = await crypto.subtle.decrypt({
    name: 'AES-GCM',
    iv: iv
  }, key, encrypted);

  console.log(new TextDecoder().decode(decrypted)); // 'Hello, World!'
}

encryptDecrypt();

Hashing

This feature allows you to create a hash of data using the SHA-256 algorithm. The code sample demonstrates hashing a string and converting the result to a hexadecimal string.

const crypto = require('isomorphic-webcrypto');

async function hashData() {
  const data = new TextEncoder().encode('Hello, World!');
  const hash = await crypto.subtle.digest('SHA-256', data);
  console.log(Buffer.from(hash).toString('hex'));
}

hashData();

Key Generation

This feature allows you to generate a pair of RSA keys for signing and verification. The code sample demonstrates generating an RSA key pair with specific parameters.

const crypto = require('isomorphic-webcrypto');

async function generateKeyPair() {
  const keyPair = await crypto.subtle.generateKey({
    name: 'RSA-PSS',
    modulusLength: 2048,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: 'SHA-256'
  }, true, ['sign', 'verify']);

  console.log(keyPair);
}

generateKeyPair();

Other packages similar to isomorphic-webcrypto

crypto

The 'crypto' module is a built-in Node.js module that provides cryptographic functionality. It offers a wide range of cryptographic operations, including hashing, encryption, and key generation. Unlike isomorphic-webcrypto, it is not designed to work in browser environments.

node-webcrypto-ossl

The 'node-webcrypto-ossl' package is a Web Cryptography API implementation for Node.js using OpenSSL. It provides a similar API to isomorphic-webcrypto but is specifically tailored for Node.js environments and does not support browsers.

webcrypto-liner

The 'webcrypto-liner' package is a polyfill for the Web Cryptography API, designed to work in environments where the native Web Crypto API is not available. It aims to provide a consistent API across different environments, similar to isomorphic-webcrypto.

README

isomorphic-webcrypto

webcrypto library for Node, React Native and IE11+

What?

There's a great Node polyfill for the Web Crypto API, but it's not isomorphic.

IE11 and versions of Safari < 11 use an older version of the spec, so the browser implementation includes a webcrypto-shim to iron out the differences. You'll still need to provide your own Promise polyfill.

There's currently no native crypto support in React Native, so the Microsoft Research library is exposed.

Note: If you're performing cross-platform jwt operations, consider jwt-lite or jwt-verifier-lite (for OpenID Connect), which build on isomorphic-webcrypto

Install

npm install isomorphic-webcrypto

Usage

There's a simple hashing example below, but there are many more WebCrypto examples here. This example requires you to npm install hex-lite.

const crypto = require('isomorphic-webcrypto')
const hex = require('hex-lite')
// or
import crypto from 'isomorphic-webcrypto'
import hex from 'hex-lite'

crypto.subtle.digest(
  { name: 'SHA-256' },
  new Uint8Array([1,2,3]).buffer
)
.then(hash => {
  // hashes are usually represented as hex strings
  // hex-lite makes this easier
  const hashString = hex.fromBuffer(hash);
})

React Native

React Native support is implemented using the Microsoft Research library. The React Native environment only supports Math.random(), so react-native-securerandom is used to provide proper entropy. This is handled automatically, except for crypto.getRandomValues(), which requires you wait:

const crypto = require('isomorphic-webcrypto')

(async () => {
  // Only needed for crypto.getRandomValues
  // but only wait once, future calls are secure
  await crypto.ensureSecure();
  const array = new Uint8Array(1);
  crypto.getRandomValues(array);
  const safeValue = array[0];
})()

Working React Native examples:

• Using create-react-native-app with Expo
• Using an ejected create-react-native-app

I just want to drop in a script tag

You should use the webcrypto-shim library directly:

<!-- Any Promise polyfill will do -->
<script src="https://unpkg.com/bluebird"></script>
<script src="https://unpkg.com/webcrypto-shim"></script>

Compatibility

• IE11+
• Safari 8+
• Edge 12+
• Chrome 43+
• Opera 24+
• Firefox 34+
• Node 8+
• React Native

Although the library runs on IE11+, the level of functionality varies between implementations. The grid below shows the discrepancies between the latest versions of each environment.

Legend

• ~ works with some caveats - see the __tests__ directory for the caveats
• ? untested
• x unsupported algorithm
• strikethrough broken method

Key	Node	React Native	Chrome/Firefox	Safari	Edge	IE11
HS256	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify
HS384	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify
HS512	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	x
RS256	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	~importKey exportKey ~generateKey sign verify	~importKey ~exportKey generateKey sign verify
RS384	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	~importKey exportKey ~generateKey sign verify	importKey exportKey generateKey sign verify
RS512	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	~importKey exportKey ~generateKey sign verify	importKey exportKey generateKey sign verify
PS256	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	?	?
PS384	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	?	?
PS512	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	?	?
ES256	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	x	x
ES384	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	x	x
ES512	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	importKey exportKey generateKey sign verify	x	x	x
RSA1_5	?	?	?	?	?	?
RSA-OAEP	?	?	?	?	?	?
RSA-OAEP-256	?	?	?	?	?	?
A128KW	?	?	?	?	?	?
A192KW	?	?	?	?	?	?
A256KW	?	?	?	?	?	?
dir	?	?	?	?	?	?
ECDH-ES	?	?	?	?	?	?
ECDH-ES+A128KW	?	?	?	?	?	?
ECDH-ES+A192KW	?	?	?	?	?	?
ECDH-ES+A256KW	?	?	?	?	?	?
A128GCMKW	?	?	?	?	?	?
A192GCMKW	?	?	?	?	?	?
A256GCMKW	?	?	?	?	?	?
PBES2-HS256+A128KW	?	?	?	?	?	?
PBES2-HS384+A192KW	?	?	?	?	?	?
PBES2-HS512+A256KW	?	?	?	?	?	?

Here's a legend for the JWA alg abbreviations:

Key	Signature, MAC or Key Management Algorithm
HS256	HMAC using SHA-256
HS384	HMAC using SHA-384
HS512	HMAC using SHA-512
RS256	RSASSA-PKCS1-v1_5 using SHA-256
RS384	RSASSA-PKCS1-v1_5 using SHA-384
RS512	RSASSA-PKCS1-v1_5 using SHA-512
ES256	ECDSA using P-256 and SHA-256
ES384	ECDSA using P-384 and SHA-384
ES512	ECDSA using P-521 and SHA-512
PS256	RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384	RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512	RSASSA-PSS using SHA-512 and MGF1 with SHA-512
RSA1_5	RSAES-PKCS1-v1_5
RSA-OAEP	RSAES OAEP using default parameters
RSA-OAEP-256	RSAES OAEP using SHA-256 and MGF1 with SHA-256
A128KW	AES Key Wrap with default initial value using 128-bit key
A192KW	AES Key Wrap with default initial value using 192-bit key
A256KW	AES Key Wrap with default initial value using 256-bit key
dir	Direct use of a shared symmetric key as the CEK
ECDH-ES	Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDF
ECDH-ES+A128KW	ECDH-ES using Concat KDF and CEK wrapped with "A128KW"
ECDH-ES+A192KW	ECDH-ES using Concat KDF and CEK wrapped with "A192KW"
ECDH-ES+A256KW	ECDH-ES using Concat KDF and CEK wrapped with "A256KW"
A128GCMKW	Key wrapping with AES GCM using 128-bit key
A192GCMKW	Key wrapping with AES GCM using 192-bit key
A256GCMKW	Key wrapping with AES GCM using 256-bit key
PBES2-HS256+A128KW	PBES2 with HMAC SHA-256 and "A128KW" wrapping
PBES2-HS384+A192KW	PBES2 with HMAC SHA-384 and "A192KW" wrapping
PBES2-HS512+A256KW	PBES2 with HMAC SHA-512 and "A256KW" wrapping

License

MIT