Notable Pottery Manufacturer
    Wondering what’s next for npm?Check out our public roadmap! »

    @empo/encryption
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.9 • Public • Published

    npm version GitHub Workflow Status Coverage Status LGTM Grade Dependabot for update dependencies Snyk Vulnerabilities for npm package

    A TypeScript library for widely used crypto standards.

    Features

    • Generate a random key for IV (24-byte long) or salt (32-byte long) using CSPRNG (Cryptographically-secure PRNG)
    • HMAC-SHA256 encryption
    • SHAKE256 (SHA-3) encryption
    • AES256-GCM encryption and decryption
    • Argon2i key derivation and hash verification

    Installation

    This is a Node.js package available through the npm registry. Before installing this package, download and install Node.js. Node.js v10.0.0 or higher is required.

    Installation is done by using npm:

    npm install @empo/encryption

    Usage

    Generate a random key

    This provides CSPRNG, to be used as a cryptographic function (e.g. AES, SHA, Argon2) backend. The length of the output value is determined by its type (IV or salt). You could also add an encoding option behind the type.

    import { generateRandomBytes } from '@empo/encryption'
    
    // Generate random iv (24-byte String)
    const buffer = generateRandomBytes({ type: 'iv' })
    
    // Generate random base64 encoded salt (32-byte String)
    const salt = generateRandomBytes({ type: 'salt', encoding: 'base64' })

    Encryption

    This provides a basic API for block cipher encryption using AES256-GCM.

    import { AES } from '@empo/encryption'
    
    const plaintext = 'password'
    
    // Secret used for encryption/decryption and
    // it has to be cryptographic safe - this means randomBytes or derived by PBKDF2 (for example)
    const secret = generateRandomBytes({ type: 'salt', encoding: 'base64' })
    
    const aes = new AES(secret)
    
    // Generate base64 encoded cipher text
    const encrypted = aes.encrypt(plaintext)

    Decryption

    This provides a basic API for block cipher decryption using AES256-GCM.

    import { AES } from '@empo/encryption'
    
    const plaintext = 'password'
    
    // Secret used for encryption/decryption and
    // it has to be cryptographic safe - this means randomBytes or derived by PBKDF2 (for example)
    const secret = generateRandomBytes({ type: 'salt', encoding: 'base64' })
    
    const aes = new AES(secret)
    const encrypted = aes.encrypt(plaintext)
    
    // Generate utf8 encoded plain text
    const decrypted = aes.decrypt(encrypted)

    Secure hash function

    This provides a secure hash function using HMAC with SHA256. A hash function is deterministic — meaning that for a given input value it must always generate the same hash value, and the function can't be reversible.

    import { SHA } from '@empo/encryption'
    
    const plaintext = 'password'
    
    // Pepper used for the cryptographic function
    const pepper = generateRandomBytes({ type: 'salt', encoding: 'base64' })
    
    const sha = new SHA(pepper)
    
    // Generate base64 encoded hash
    const encrypted = sha.encrypt(plaintext)

    This provides a generalization of a cryptographic hash function using SHAKE256. SHAKE256 is an extensible-output function (XOF) in the SHA-3 family, as specified in FIPS 202. The 256 in its name indicates its maximum security level (in bits), as described in Sections A.1 and A.2 of FIPS 202. Unlike HMAC with SHA256, SHAKE256 doesn't need a pepper.

    import { SHAKE256 } from '@empo/encryption'
    
    const plaintext = 'password'
    
    const sha3 = new SHAKE256()
    
    // Generate base64 encoded hash
    const encrypted = sha3.encrypt(plaintext)

    This provides a key derivation function using Argon2 algorithm. A key derivation function is a cryptographic hash function that derives one or more secret keys such as a password, or a passphrase using pseudorandom function — meaning that for a given input value it must always generate different hash value, and the function can't be reversible.

    import { Argon2 } from '@empo/encryption'
    
    const plaintext = 'password'
    
    // Pepper is similar to salt but stored in the application environment variables, not in DB
    const pepper = generateRandomBytes({ type: 'salt', encoding: 'base64' })
    const salt = generateRandomBytes({ type: 'salt', encoding: 'base64' })
    
    const argon2 = new Argon2(pepper, salt)
    
    // Generate hash
    const encrypted = await argon2.encrypt(text)
    
    // Verify hashed value with given text (outputs True or False)
    const match = await argon2.match(encrypted, text)

    FAQ

    See FAQ.md.

    License

    This package is freely distributable under the terms of the MIT license. When required, please check P-H-C/phc-winner-argon2 for license over Argon2 and the reference implementation.

    FOSSA Status

    Install

    npm i @empo/encryption

    DownloadsWeekly Downloads

    51

    Version

    0.2.9

    License

    MIT

    Unpacked Size

    22.6 kB

    Total Files

    10

    Homepage

    empo.im

    Last publish

    Collaborators

    • avatar
    • avatar