This is a wrapper around the WebCrypto API available in modern browsers. It enables fast development of applications that require storing as well as signing and verifying data. It is well tested and it comes with no external dependencies.
Huge thanks to @Jopie64 for Typescriptifying the source!
Enter this into your terminal with npm installed.
npm install --save easy-web-cryptoEither host dist/web-crypto.js yourself or use jsDelivr like this:
<script type="application/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cjs/web-crypto.js"></script>You can use globalThis.WebCrypto to access the API after installing.
Although this wrapper is compatible with SHA-1, we strongly recommend against using it in modern cryptographic applications unless absolutely necessary.
Generates an ECDA key pair for signing and verifying. By default this key can be exported.
It supports the following optional parameters: extractable (defaults to true), namedCurve
that accepts P-256, P-384, and P-521 (defaults to P-256).
// Assuming you have loaded the easy-web-crypto library in your HTML file
const WebCrypto = globalThis.WebCrypto
// generate an ECDA P-256 key pair
const keyPair = await WebCrypto.genKeyPair()Export a public key using base64 format by default. ArrayBuffer is also supported by passing
an optional format parameter with the value raw.
const keyPair = await WebCrypto.genKeyPair()
const exportedPub = await WebCrypto.exportPublicKey(keyPair.publicKey)
// console.log(exported) -> MFkwEwYHKoZ ... UmUXN7Q27txQ==
// to export using raw format
const exportedPub = await WebCrypto.exportPublicKey(keyPair.publicKey, 'raw')Export a private key using base64 format by default. ArrayBuffer is also supported by passing
an optional format parameter with the value raw.
const keyPair = await WebCrypto.genKeyPair()
const exportedPriv = await WebCrypto.exportPrivateKey(keyPair.privateKey)
// console.log(exported) -> MFkwEwYHKoZ ... UmUXN7Q27txQ==
// to export using raw format
const exportedPriv = await WebCrypto.exportPrivateKey(keyPair.privateKey, 'raw')Import a public key using the base64 format by default. It supports the following optional parameters: namedCurve that accepts P-256, P-384, and P-521 (defaults to P-256),
format that can be base64, hex, and raw for ArrayBuffer (defaults to base64).
// using the exported public key above
const importedPub = await WebCrypto.importPublicKey(exportedPub)Import a private key using the base64 format by default. It supports the following optional parameters: namedCurve that accepts P-256, P-384, and P-521 (defaults to P-256),
format that can be base64, hex, and raw for ArrayBuffer (defaults to base64).
// using the exported private key above
const importedPriv = await WebCrypto.importPrivateKey(exportedPriv)Sign data using the private key. It supports the following optional parameters: format,
that can be base64, hex, and raw for ArrayBuffer (defaults to base64), and hash that
can be of type SHA-1, SHA-256, SHA-384, or SHA-512 (defaults to SHA-256).
const data = { foo: 'bar' }
// generate keys
const keys = await WebCrypto.genKeyPair()
// sign
const sig = await WebCrypto.sign(keys.privateKey, data)
// console.log(sig) -> Cf51pRgxund ... Tvp7hYbiRQvnTnLZLpuw==Verify a signature over some data using the private key. It supports the following optional
parameters: format that can be base64, hex, and raw for ArrayBuffer (defaults to
base64), and hash that can be of type SHA-1, SHA-256, SHA-384, or SHA-512
(defaults to SHA-256).
// using the signature we got above
const isValid = await WebCrypto.verify(keys.publicKey, data, sig)
// console.log(isValid) -> trueGenerates an AES key for encryption. By default this key can be exported. It supports the
following optional parameters: extractable (defaults to true), mode (defaults to AES-GCM), and
keySize with a length of 128, 192, or 256 (defaults to 128).
// genAESKey(extractable, mode = 'AES-GCM', keySize = 128)
const key = await WebCrypto.genAESKey()Encrypt a String|Object using an AES key.
const data = { foo: 'bar' }
// using the key generated above
const encrypted = await WebCrypto.encrypt(key, data)Decrypt an encrypted String|Object using an AES key.
const val = await WebCrypto.decrypt(key, encrypted)
console.log(val) // { foo: 'bar' }Encrypt an ArrayBuffer using an AES key.
const buffer = new ArrayBuffer(8)
// using the key generated above
const encrypted = WebCrypto.encryptBuffer(key, buffer)Dncrypt an ArrayBuffer using an AES key.
WebCrypto.decryptBuffer(key, encrypted).then(val => console.log(val)) // ArrayBuffer {}Export an AES key into a raw|JWK key (defaults to raw) that can be stored.
const exported = WebCrypto.exportKey(key)Imports an AES key. It accepts the following optional parameters: type (defaults
to raw), mode (defaults to AES-GCM).
// importKey(key, type = 'raw', mode = 'AES-GCM')
const key = WebCrypto.importKey(key)
// use this AES key now to encrypt/decrypt as aboveUses PBKDF2 to derive a Key Encryption Key from a passphrase, in order to generate an encrypted
AES symmetric key that can be safely stored. It accepts the following optional parameters:
salt (defaults to a random ArrayBuffer(16)), iterations (defaults to 10000), hashAlgo
(defaults to SHA-256).
Please make sure you use a sufficiently secure passphrase as well as a minimum of 10000 iterations!
// genEncryptedMasterKey(passPhrase, salt = genRandomBuffer(16), iterations = 100000, hashAlgo = 'SHA-256')
const passphrase = 'your super secure passphrase'
const encMasterKey = await WebCrypto.genEncryptedMasterKey(passphrase)
// you can now safely store the encMasterKey for future useDecrypt a master key by deriving the encryption key from the provided passphrase and encrypted master key.
// use the values from genEncryptedMasterKey example
const key = await WebCrypto.decryptMasterKey(passphrase, encMasterKey)
// use this AES key now to encrypt/decrypt your dataUpdate the derived key encryption key (KEK) based on the new passphrase.
Please note that the actual AES key used for encryption does not change, so you can still decrypt previously encrypted data. Only the passphrase that is used to encrypt the AES key changes!
// use the values from genEncryptedMasterKey example + the new passphrase
const newPassphrase = 'something different from the last passphrase'
// updatePassphraseKey(oldassphrase, newPassphrase, oldEncryptedMasterKey)
const updatedEncMK = await WebCrypto.updatePassphraseKey(passphrase, newPassphrase, encMasterKey)
// you can now safely store the updatedEncMK for future useGenerate the hash of a string or ArrayBuffer. It accepts the following optional parameters:
outputFormat (defaults to hex), and name (defaults to SHA-256 but also supports SHA-1, SHA-384, and SHA-512 algorithms).
// hash(data, outputFormat = 'hex', name = 'SHA-256')
const hashed = await WebCrypto.hash('abc123')
console.log(hashed)
// 6ca13d52ca70c883e0f0bb101e425a89e8624de51db2d2392593af6a84118090Generate a random secure hexadecimal ID based on the provided length. Defaults to a length of 16.
const randomId = WebCrypto.genId(32)
console.log(randomId) // a6d2a143edb8b521645bf5d39c29e401That's it!
const WebCrypto = require('easy-web-crypto')
// generate a new ECDA key pair
const keyPair = await WebCrypto.genKeyPair()
// sign some data
const data = { foo: 'bar' }
const sig = await WebCrypto.sign(keyPair.privateKey, data)
// check signature
const isValid = await WebCrypto.verify(keyPair.publicKey, data, sig)
console.log(isValid) // -> true
// EXPORT
// export public key
const exportedPub = await WebCrypto.exportPublicKey(keyPair.publicKey)
// export private key
const exportedPriv = await WebCrypto.exportPrivateKey(keyPair.privateKey)
// IMPORT
// import public key
const pubKey = await WebCrypto.importPublicKey(exportedPub)
// import private key
const privKey = await WebCrypto.importPrivateKey(exportedPriv)
// sign some data using imported keys
const data = { foo: 'bar' }
const sig = await WebCrypto.sign(privKey, data)
// check signature
const isValid = await WebCrypto.verify(pubKey, data, sig)
console.log(isValid) // -> trueconst WebCrypto = require('easy-web-crypto')
const passphrase = 'your super secure passphrase'
// derive a new key from passphrase and generate the master AES key
// (you can now store this encrypted key for later use)
const encMasterKey = await WebCrypto.genEncryptedMasterKey(passphrase)
// decrypt the (stored) AES key to be able to encrypt/decrypt data
let key = await WebCrypto.decryptMasterKey(passphrase, encMasterKey)
// encrypt some data
const data = { foo: 'bar' }
// use the decrypted AES key from above
const encrypted = await WebCrypto.encrypt(key, data)
// decrypt the data we just encrypted
let val = await WebCrypto.decrypt(key, encrypted)
console.log(val) // { foo: 'bar' }
// change passphrase
const newPassphrase = 'something different from the last passphrase'
// updated the encrypted master key (for security reasons you should always
// rotate keys after a certain period of time)
const updatedEncMasterKey = await WebCrypto.updatePassphraseKey(passphrase,
newPassphrase, encMasterKey)
// decrypt new master key
key = await WebCrypto.decryptMasterKey(newPassphrase, updatedEncMasterKey)
// decrypt the previous data
val = await WebCrypto.decrypt(key, encrypted)
console.log(val) // { foo: 'bar' }