Easy-web-crypto

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!

Installing

via npm

Enter this into your terminal with npm installed.

npm install --save easy-web-crypto

via <script> tag

Either 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.

Usage

Sidenote

Although this wrapper is compatible with SHA-1, we strongly recommend against using it in modern cryptographic applications unless absolutely necessary.

ECDA public key

genKeyPair

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()

exportPublicKey

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')

exportPrivateKey

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')

importPublicKey

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)

importPrivateKey

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

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

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) -> true

AES

genAESKey

Generates 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

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

Decrypt an encrypted String|Object using an AES key.

const val = await WebCrypto.decrypt(key, encrypted)
console.log(val) // { foo: 'bar' }

encryptBuffer

Encrypt an ArrayBuffer using an AES key.

const buffer = new ArrayBuffer(8)

// using the key generated above
const encrypted = WebCrypto.encryptBuffer(key, buffer)

decryptBuffer

Dncrypt an ArrayBuffer using an AES key.

WebCrypto.decryptBuffer(key, encrypted).then(val => console.log(val)) // ArrayBuffer {}

exportKey

Export an AES key into a raw|JWK key (defaults to raw) that can be stored.

const exported = WebCrypto.exportKey(key)

importKey

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 above

Passphrase-based key derivation

genEncryptedMasterKey

Uses 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 use

decryptMasterKey

Decrypt 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 data

updatePassphraseKey

Update 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 use

Utility

hash

Generate 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)
// 6ca13d52ca70c883e0f0bb101e425a89e8624de51db2d2392593af6a84118090

genId

Generate a random secure hexadecimal ID based on the provided length. Defaults to a length of 16.

const randomId = WebCrypto.genId(32)

console.log(randomId) // a6d2a143edb8b521645bf5d39c29e401

That's it!

Full example for signing / verifying data

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) // -> true

Full example for encrypting / decrypting data

const 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' }