Web-based OpenSSL-like random key generator (WASM or min.js). Provides rand -base64 and -hex outputs using WebCrypto or optional OpenSSL-wasm.
npm install webopensslWebOpenSSL
==========
Web-based OpenSSL-like random key generator that can be loaded as either:
- A minified JavaScript library (dist/webopenssl.min.js)
- With optional WASM provider (compiled OpenSSL via Emscripten) to use RAND_bytes
Purpose
-------
Create random keys similar to openssl rand -base64 32, using secure system randomness:
- WebCrypto (browser): crypto.getRandomValues, backed by OS CSPRNG
- Node.js (min.js UMD): crypto.randomBytes
- Optional OpenSSL WASM module: calls RAND_bytes from libcrypto compiled to WebAssembly
This matches OpenSSL's security model for randomness (OS-backed CSPRNG).
Files
-----
- src/index.js (ESM) — readable source
- dist/webopenssl.min.js (UMD) — minified build for browser or Node
- examples/index.html — simple usage in a web page
- scripts/build-openssl-wasm.sh — builds OpenSSL libcrypto to WASM
- src/wasm/openssl_rand_wrapper.c — small wrapper that exposes openssl_rand_bytes(...) for Emscripten
API
---
- randBytes(length: number): Uint8Array
- randBase64(length: number): string
- randHex(length: number): string
- setProvider(provider: { name: string; randBytes(length): Uint8Array })
- setWasmModule(Module: EmscriptenModule) — configures OpenSSL WASM provider
- getProviderName(): string
- autoLoadOpenSSLWASM(options?: { url?: string; factoryGlobalName?: string }): Promise
- When OpenSSL WASM provider is loaded (openssl-wasm), additional functions are available:
- sha256(bytes: Uint8Array): Uint8Array (32 bytes)
- sha512(bytes: Uint8Array): Uint8Array (64 bytes)
- pbkdf2HmacSha256(password: Uint8Array, salt: Uint8Array, iterations: number, keyLen: number): Uint8Array
- pbkdf2HmacSha512(password: Uint8Array, salt: Uint8Array, iterations: number, keyLen: number): Uint8Array
- aes256GcmEncrypt(key: Uint8Array(32), iv: Uint8Array, aad: Uint8Array, plaintext: Uint8Array): { ciphertext: Uint8Array, tag: Uint8Array(16) }
- aes256GcmDecrypt(key: Uint8Array(32), iv: Uint8Array, aad: Uint8Array, ciphertext: Uint8Array, tag: Uint8Array(16)): Uint8Array
Usage (Browser, min.js)
-----------------------
Include the minified UMD bundle:
``html`
Auto-load OpenSSL WASM (Browser)
--------------------------------
If you build the OpenSSL WASM module, you can auto-load it:
`html`
Usage (ESM)
-----------
`js
import { randBase64, randHex, getProviderName, autoLoadOpenSSLWASM } from "./src/index.js";
console.log(randBase64(32));
console.log(randHex(32));
console.log(getProviderName()); // "webcrypto"
await autoLoadOpenSSLWASM({ url: "./dist/openssl-wasm/openssl_module.js" });
console.log(getProviderName()); // "openssl-wasm" if loaded
`
Build OpenSSL to WASM (Emscripten)
----------------------------------
Prerequisites:
- macOS/Linux with bash, curl, tar, make, perl
- Emscripten SDK (emsdk) in PATH, or this script will fetch and activate a local copy
Steps:
- Using npm script:
- npm run build:wasm
- Or directly:
- bash scripts/build-openssl-wasm.sh
What the script does:
- Downloads OpenSSL 3.5.3
- Builds libcrypto with emconfigure/emmake (disables unsupported features in WASM)
- Compiles a small wrapper (src/wasm/openssl_rand_wrapper.c) and links against libcrypto
- Emits a modularized factory (OpenSSLModuleFactory) at dist/openssl-wasm/openssl_module.js with a .wasm sidecar
- WebOpenSSL can auto-load it via autoLoadOpenSSLWASM or manually via setWasmModule
Manual wiring example
---------------------
`html`
Deploy to Vercel
----------------
This repo includes an npm script that prepares a deployable folder (vercel-build) and deploys it to Vercel. It:
- Builds a fresh WASM (npm run build:wasm)
- Copies the entire project into vercel-build (excluding dev/build artifacts)
- Moves examples/index.html to vercel-build/index.html
- Rewrites relative paths so index.html references dist and src from vercel-build root
- Deploys vercel-build with the Vercel CLI
Prerequisites (one-time):
- Install Vercel CLI:
`bash`
npm i -g vercel
`
- Login:
bash`
vercel login
`
- Link the deploy folder (must be done once before the first deployment):
- Ensure the folder exists:
bash`
mkdir -p vercel-build
`
- Link vercel-build to a Vercel project:
bash`
vercel link --cwd vercel-build
Follow the prompts to create/select a project and scope.
Deploy
- Run:
`bash`
npm run deploy:vercel
The script will:
- Build fresh WASM
- Sync files into vercel-build
- Move examples/index.html to vercel-build/index.html
- Rewrite any ../dist/... and ../src/... references to dist/... and src/...
- Deploy vercel-build to production with Vercel
Notes
- If you relocate or rename examples/index.html, adjust the script at scripts/deploy-vercel.sh accordingly.
- The script preserves vercel-build/.vercel, so you only need to run vercel link once.
- You can view deployment logs and URLs in your Vercel dashboard.
Notes on Security
-----------------
- WebOpenSSL uses cryptographically secure randomness:
- Browser: WebCrypto getRandomValues (OS CSPRNG)crypto.randomBytes
- Node.js: (OS CSPRNG)RAND_bytes
- OpenSSL WASM: via libcrypto (OpenSSL's CSPRNG)openssl rand
- Output length semantics mirror :randBase64(n)
- generates n random bytes and returns base64 encoding of those bytes.randHex(n)` generates n random bytes and returns hex encoding.
-
Limitations
-----------
- This library focuses on secure random key generation. It is not a full re-implementation of OpenSSL.
- Building OpenSSL to WASM can be environment-sensitive. The provided script targets modern Emscripten and OpenSSL 3.5.3.
License
-------
MIT