Nighttime Pachinko Marathon
    Wondering what’s next for npm?Check out our public roadmap! »

    easy-web-crypto
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.7 • Public • Published

    Easy-web-crypto

    Build Status

    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/easy-web-crypto@1.2.6/dist/cjs/web-crypto.js"></script>

    You can use window.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).

    const WebCrypto = require('easy-web-crypto')
    
    // 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 changed!

    // 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
    const encMasterKey = await WebCrypto.genEncryptedMasterKey(passphrase)
    
    // decrypt the AES key
    let key = await WebCrypto.decryptMasterKey(passphrase, encMasterKey)
    
    // encrypt some data
    const data = { foo: 'bar' }
    
    // using the key generated above
    const encrypted = await WebCrypto.encrypt(key, data)
    
    // decrypt the data
    let val = await WebCrypto.decrypt(key, encrypted)
    console.log(val) // { foo: 'bar' }
    
    // change passphrase
    const newPassphrase = 'something different from the last passphrase'
    
    // updatePassphraseKey(oldPassphrase, newPassphrase, oldEncryptedMasterKey)
    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' }

    Install

    npm i easy-web-crypto

    DownloadsWeekly Downloads

    102

    Version

    1.2.7

    License

    MIT

    Unpacked Size

    211 kB

    Total Files

    9

    Last publish

    Collaborators

    • avatar