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.
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.
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')
import crypto from 'isomorphic-webcrypto'
import hex from 'hex-lite'
crypto.subtle.digest(
{ name: 'SHA-256' },
new Uint8Array([1,2,3]).buffer
)
.then(hash => {
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 () => {
await crypto.ensureSecure();
const array = new Uint8Array(1);
crypto.getRandomValues(array);
const safeValue = array[0];
})()
Working React Native examples:
I just want to drop in a script tag
You should use the webcrypto-shim library directly:
<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 4+
- React Native
Although the library runs on IE11+, the level of functionality varies between implementations. They're organized using 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 |
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 |
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 | x | importKey exportKey generateKey sign verify | importKey exportKey generateKey sign verify | x | x | x |
PS256 | ? | ? | ? | ? | ? | ? |
PS384 | ? | ? | ? | ? | ? | ? |
PS512 | ? | ? | ? | ? | ? | ? |
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 | ? | ? | ? | ? | ? | ? |
License
MIT