Registry / auth-security / webcrypto-shim

webcrypto-shim

library0.1.7jsnpmunverified

The `webcrypto-shim` package provides a polyfill for the W3C Web Cryptography API, specifically targeting older browser environments that either lacked support or had prefixed and buggy implementations. Its primary purpose was to enable core Web Crypto functionality in browsers like Internet Explorer 11, Mobile Internet Explorer 11, and Safari versions 8-10 (including iOS Safari 8-10). The shim addresses deficiencies such as the absence of a `Promise` implementation in IE11, which required an external polyfill like `promiz.js`. The package's last stable version, 0.1.7, was released many years ago, and it is no longer actively maintained for modern browser environments, which universally support the Web Crypto API natively. It offered implementations for algorithms including SHA-256/384 for `digest`, HMAC, AES-CBC, AES-KW, RSASSA-PKCS1-v1_5, and RSA-OAEP for operations such as `sign`, `verify`, `encrypt`, `decrypt`, `generateKey`, `importKey`, `exportKey`, `wrapKey`, and `unwrapKey`.

auth-security http-networking

npm install webcrypto-shim

github ↗package ↗

INSTALL

IMPORT

SIG · WEBCRYPTO-SHIM

webcrypto-shim

auth-securityjavascriptv0.1.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

window.crypto

✓ /* Access after script inclusion */

✗ import { crypto } from 'webcrypto-shim';

The shim works by patching the global `window.crypto` object. It is designed for direct inclusion via `<script>` tags in legacy browser environments, not for ES module or CommonJS `import`/`require` statements.

window.crypto.subtle

✓ /* Access after script inclusion */

✗ const { subtle } = require('webcrypto-shim');

The SubtleCrypto interface is made available globally at `window.crypto.subtle` after the shim script loads. The package does not export this object for module systems.

window.crypto.subtle.digest

✓ await window.crypto.subtle.digest(/* ... */);

✗ import { digest } from 'webcrypto-shim/subtle';

Individual cryptographic operations like `digest` are accessed as methods on the `window.crypto.subtle` object, which is populated by the shim. There are no separate module exports for these methods.

This code snippet demonstrates how to check for and utilize the `window.crypto.subtle` API, potentially provided by the `webcrypto-shim`, to perform an HMAC-SHA256 key generation, signing, and verification operation within a legacy browser environment that requires the shim.

// In an HTML file, include these scripts before your application logic: // <script src="https://unpkg.com/promiz@latest/promiz.js"></script>  // <script src="https://unpkg.com/webcrypto-shim@latest/webcrypto-shim.js"></script> // After inclusion, window.crypto and window.crypto.subtle will be available. if (window.crypto && window.crypto.subtle) { console.log('WebCrypto API (window.crypto.subtle) is available, possibly via shim.'); async function testHmacSha256() { try { // Generate an HMAC key const key = await window.crypto.subtle.generateKey( { name: "HMAC", hash: { name: "SHA-256" }, length: 256 }, true, // extractable ["sign", "verify"] ); const encoder = new TextEncoder(); const data = encoder.encode("This is a test message for HMAC."); // Sign the data const signature = await window.crypto.subtle.sign( { name: "HMAC" }, key, data ); console.log("HMAC-SHA256 signature generated:", new Uint8Array(signature)); // Verify the signature const isValid = await window.crypto.subtle.verify( { name: "HMAC" }, key, signature, data ); console.log("Signature valid:", isValid); // Should be true if (!isValid) { throw new Error("HMAC signature verification failed!"); } } catch (error) { console.error("WebCrypto HMAC test failed:", error); // Handle errors, especially for legacy browser specific issues if (error.message.includes("deriveKey")) { console.warn("This error might be related to deriveKey/deriveBits not supported in IE11/Safari."); } } } testHmacSha256(); } else { console.error('WebCrypto API (window.crypto.subtle) is NOT available.'); }

Debug

Known issues

gotchaThe `deriveKey` and `deriveBits` operations are not supported by the shim in Internet Explorer 11 and Safari versions 8-10, due to a lack of underlying implementation in these browsers.

fix

Avoid using `deriveKey` or `deriveBits` if compatibility with IE11 or older Safari versions is required. Implement alternative key derivation logic if necessary.

affects: >=0.1.0

gotchaInternet Explorer 11 silently discards empty input data for cryptographic operations, leading to promises that never resolve or reject. This can cause applications to hang indefinitely.

fix

Always ensure that input data provided to cryptographic operations is non-empty when targeting IE11.

affects: >=0.1.0

breakingFor Internet Explorer 11, a Promise polyfill (such as `promiz.js`) must be loaded before `webcrypto-shim.js` for the shim to function correctly, as IE11 lacks native Promise support.

fix

Include a Promise/A+-compatible polyfill script (e.g., `<script src="bower_components/promiz/promiz.js"></script>`) in your HTML before the `webcrypto-shim.js` script.

affects: >=0.1.0

gotchaThe RSA-OAEP implementation in the shim currently only supports the 'jwk' (JSON Web Key) format for wrapped and unwrapped keys, despite the Web Crypto API specification allowing other formats.

fix

When performing key wrapping or unwrapping with RSA-OAEP using this shim, explicitly specify and use the 'jwk' format for keys.

affects: >=0.1.0

Errors

Common errors & fixes

Promise is not defined

Running `webcrypto-shim` in Internet Explorer 11 or other legacy browsers without a preceding Promise polyfill.

fix

Load a Promise polyfill (e.g., `promiz.js`) via a `<script>` tag before the `webcrypto-shim.js` script in your HTML.

Cryptographic operation promise never resolves/rejects.

Providing empty `ArrayBuffer` or `TypedArray` data as input to cryptographic operations in Internet Explorer 11, which silently fails to process it.

fix

Ensure all input data provided to `window.crypto.subtle` methods (e.g., `digest`, `sign`, `encrypt`) is non-empty when targeting IE11.

DOMException: The requested operation is not supported. (or similar browser-specific error regarding key derivation)

Attempting to use `window.crypto.subtle.deriveKey` or `window.crypto.subtle.deriveBits` in Internet Explorer 11 or Safari 8-10, as these operations are not implemented by the shim for these browsers.

fix

Avoid using `deriveKey` or `deriveBits` if support for IE11 or older Safari versions is critical for your application.

Upgrade

Version history

0.1.7latest on npm

Audit

Dependencies

promizrequiredRequired for Internet Explorer 11 to provide Promise support, as IE11 lacks native Promise implementation.

Agent activity

42 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vibornoff/webcrypto-shim ↗

packagehttps://www.npmjs.com/package/webcrypto-shim ↗