Skip to content

Abstractions for working with WebCrypto in Browser and on Server

Notifications You must be signed in to change notification settings

JWally/ez-web-crypto

ย 
ย 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

57 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

ez-web-crypto

Library Logo

npm version License: ISC Node.js Version

A lightweight, type-safe wrapper around the Web Crypto API, providing easy-to-use cryptographic operations for both browser and Node.js environments.

Features

  • ๐Ÿ” AES-GCM encryption/decryption
  • ๐Ÿ”‘ ECDH key exchange and encryption
  • โœ๏ธ ECDSA digital signatures
  • ๐Ÿ”’ Password-based encryption
  • ๐ŸŒ HKDF key derivation
  • #๏ธโƒฃ HMAC operations
  • ๐Ÿงฎ Cryptographic hashing (SHA-1, SHA-256, SHA-384, SHA-512)
  • ๐Ÿ“ฑ Cross-platform compatibility (Browser + Node.js)
  • ๐Ÿ“˜ Full TypeScript support
  • ๐Ÿ”„ Flexible key format handling

Installation

npm install @justinwwolcott/ez-web-crypto

Usage Examples

AES Encryption

import { AESMakeKey, AESEncrypt, AESDecrypt } from '@justinwwolcott/ez-web-crypto'

// Generate a new AES key
const key = await AESMakeKey()

// Encrypt data
const encrypted = await AESEncrypt(key, btoa('Hello, World!'))

// Decrypt data
const decrypted = await AESDecrypt(key, encrypted.iv, encrypted.ciphertext, true)
console.log(decrypted) // 'Hello, World!'

ECDH Key Exchange and Encryption

import { EcMakeCryptKeys, EcEncrypt, EcDecrypt } from '@justinwwolcott/ez-web-crypto'

// Generate key pairs for both parties
const aliceKeys = await EcMakeCryptKeys()
const bobKeys = await EcMakeCryptKeys()

// Alice encrypts message for Bob
const encrypted = await EcEncrypt(aliceKeys.privateKey, bobKeys.publicKey, btoa('Secret message'))

// Bob decrypts message from Alice
const decrypted = await EcDecrypt(bobKeys.privateKey, aliceKeys.publicKey, encrypted.iv, encrypted.ciphertext, true)

Digital Signatures (ECDSA)

import { EcMakeSigKeys, EcSignData, EcVerifySig } from '@justinwwolcott/ez-web-crypto'

// Generate signing keys
const keys = await EcMakeSigKeys()

// Sign data
const signature = await EcSignData(keys.privateKey, btoa('Sign this message'))

// Verify signature
const isValid = await EcVerifySig(keys.publicKey, signature, btoa('Sign this message'))

Password-Based Encryption

import { PASSWORD_ENCRYPT, PASSWORD_DECRYPT } from '@justinwwolcott/ez-web-crypto'

// Encrypt with password
const encrypted = await PASSWORD_ENCRYPT('myPassword', btoa('Secret data'))

// Decrypt with password
const decrypted = await PASSWORD_DECRYPT('myPassword', encrypted)

HKDF Encryption

import { EcMakeCryptKeys, HKDFEncrypt, HKDFDecrypt } from '@justinwwolcott/ez-web-crypto'

// Generate keys
const aliceKeys = await EcMakeCryptKeys()
const bobKeys = await EcMakeCryptKeys()

// Encrypt using HKDF
const encrypted = await HKDFEncrypt(aliceKeys.privateKey, bobKeys.publicKey, btoa('Secret data'))

// Decrypt using HKDF
const decrypted = await HKDFDecrypt(
  bobKeys.privateKey,
  aliceKeys.publicKey,
  encrypted.salt,
  encrypted.iv,
  encrypted.ciphertext,
  true
)

Hashing and HMAC

import { HASH, HMAC } from '@justinwwolcott/ez-web-crypto'

// Generate hash
const hash = await HASH('SHA-256', 'Hash this text')

// Generate HMAC
const hmac = await HMAC('secret-key', 'Message to authenticate')

API Reference

AES Operations

  • AESMakeKey(exportable?: boolean): Promise<Base64String | CryptoKey>

    • Generates a new AES-GCM key
    • exportable: Whether the key should be exportable (default: true)
  • AESEncrypt(key: Base64String | CryptoKey, data: Base64String, nonce?: Base64String): Promise<AESEncryptResult>

    • Encrypts data using AES-GCM
    • Returns ciphertext and IV
  • AESDecrypt(key: Base64String | CryptoKey, nonce: Base64String, data: Base64String, returnText?: boolean): Promise<string | ArrayBuffer>

    • Decrypts AES-GCM encrypted data
    • Optional text return format

ECDH Operations

  • EcMakeCryptKeys(exportable?: boolean): Promise<ECKeyPair>

    • Generates ECDH key pair for encryption
    • Returns public/private keys in multiple formats
  • EcEncrypt(privateKey: Base64String | CryptoKey, publicKey: Base64String | CryptoKey, data: Base64String): Promise<AESEncryptResult>

    • Encrypts data using ECDH key exchange
    • Returns encrypted data and IV
  • EcDecrypt(privateKey: Base64String | CryptoKey, publicKey: Base64String | CryptoKey, nonce: Base64String, data: Base64String, returnText?: boolean): Promise<string | ArrayBuffer>

    • Decrypts ECDH encrypted data

ECDSA Digital Signatures

  • EcMakeSigKeys(exportable?: boolean): Promise<ECSignatureKeyPair>
    • Generates ECDSA signing key pair
  • EcSignData(privateKey: Base64String | CryptoKey, data: Base64String): Promise<Base64String>
    • Signs data using ECDSA
  • EcVerifySig(publicKey: Base64String | CryptoKey, signature: Base64String, data: Base64String): Promise<boolean>
    • Verifies ECDSA signature

HKDF Operations

  • HKDFEncrypt(privateKey: Base64String | CryptoKey, publicKey: Base64String | CryptoKey, data: Base64String, ivLength?: number, saltLength?: number): Promise<HKDFEncryptResult>
    • Encrypts data using HKDF key derivation
  • HKDFDecrypt(privateKey: Base64String | CryptoKey, publicKey: Base64String | CryptoKey, salt: Base64String, iv: Base64String, data: Base64String, returnText?: boolean): Promise<string | ArrayBuffer>
    • Decrypts HKDF encrypted data

Password Operations

  • PASSWORD_ENCRYPT(password: string, data: Base64String): Promise<Base64String>
    • Encrypts data using password-based encryption
  • PASSWORD_DECRYPT(password: string, data: Base64String): Promise<string>
    • Decrypts password-protected data

Hashing Operations

  • HASH(algorithm: HashAlgorithm, data: string, length?: number): Promise<Base64String>
    • Generates cryptographic hash
    • Supports SHA-1, SHA-256, SHA-384, SHA-512
  • HMAC(secret: string, data: string): Promise<HexString>
    • Generates HMAC using SHA-256

Type Definitions

type Base64String = string
type HexString = string
type HashAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512'

interface AESEncryptResult {
  ciphertext: Base64String
  iv: Base64String
}

interface HKDFEncryptResult {
  ciphertext: Base64String
  salt: Base64String
  iv: Base64String
}

interface ECKeyPair {
  publicKey: Base64String
  privateKey: Base64String | CryptoKey
  rawPublicKey: Base64String
  rawPublicKeyLite: Base64String
  jwkPublicKey?: JsonWebKey
  jwkPrivateKey?: JsonWebKey
}

Environment Support

  • Node.js โ‰ฅ 14.0.0
  • Modern browsers with Web Crypto API support
  • Full TypeScript support included

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Security Notes

  • All cryptographic operations use standard Web Crypto API implementations
  • Keys can be handled in both exportable and non-exportable formats
  • Password-based encryption uses multiple rounds of hashing for key strengthening
  • All operations are async and type-safe

License

This project is licensed under the ISC License - see the LICENSE file for details.

Author

Justin W. Wolcott

Support

If you encounter any problems or have questions, please open an issue on GitHub.

About

Abstractions for working with WebCrypto in Browser and on Server

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 99.0%
  • JavaScript 1.0%