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

Here's a legend for the JWA alg abbreviations:

License

MIT