@brielov/crypto

@brielov/crypto is a secure and lightweight cryptographic utility library built on the Web Crypto API. It provides functions for hashing and verifying passwords, encrypting and decrypting data, and generating cryptographic keys and salts. Designed for modern web applications, it ensures robust security with no dependencies.

Features

• Password Hashing: Uses PBKDF2 with configurable hash algorithms (SHA-1, SHA-256, SHA-384, SHA-512) for secure password hashing.
• Password Verification: Safely verifies passwords against hashed values with constant-time comparison.
• Configurable Security: Adjustable iteration counts, key lengths, and hash algorithms for future-proofing.
• Data Encryption/Decryption: Implements AES-GCM for secure encryption and decryption of data.
• Key Derivation: Derives cryptographic keys from user-provided secrets using PBKDF2.
• Utility Functions: Includes helpers for Base64 encoding/decoding and generating cryptographically secure salts.

Installation

deno add jsr:@brielov/crypto
npx jsr add @brielov/crypto
yarn dlx jsr add @brielov/crypto
pnpm dlx jsr add @brielov/crypto
bunx jsr add @brielov/crypto

Usage

Password Hashing and Verification

import { generateSalt, hash, verify } from "@brielov/crypto";

const password = "mySecurePassword";
const salt = generateSalt(); // Generate a secure salt

// Hash the password with default settings (SHA-256, 256-bit key, 100,000 iterations)
const hashedPassword = await hash(password, salt);

// Verify the password
const isVerified = await verify(password, hashedPassword, salt);
console.log(isVerified); // true or false

// Using custom security parameters for enhanced security
const strongHashedPassword = await hash(
  password,
  salt,
  150000, // 150,000 iterations
  512, // 512-bit key length
  "SHA-512", // SHA-512 hash algorithm
);

// Verify with the same parameters
const isStrongVerified = await verify(
  password,
  strongHashedPassword,
  salt,
  150000,
  512,
  "SHA-512",
);
console.log(isStrongVerified); // true or false

Data Encryption and Decryption

import { decrypt, deriveKey, encrypt, generateSalt } from "@brielov/crypto";

const secret = "mySecretPassword";
const salt = generateSalt(); // Generate a secure salt
const key = await deriveKey(secret, salt); // Derive a cryptographic key

const data = new TextEncoder().encode("Sensitive data");

// Encrypt the data
const { encryptedData, iv } = await encrypt(data, key);

// Decrypt the data
const decryptedData = await decrypt(encryptedData, key, iv);
console.log(new TextDecoder().decode(decryptedData)); // 'Sensitive data'

Utility Functions

import { fromBase64, generateSalt, toBase64 } from "@brielov/crypto";

// Encode and decode Base64
const data = new Uint8Array([104, 101, 108, 108, 111]); // 'hello'
const encoded = toBase64(data); // 'aGVsbG8='
const decoded = fromBase64(encoded); // Uint8Array [104, 101, 108, 108, 111]

// Generate a secure salt
const salt = generateSalt(); // Uint8Array of 16 random bytes
const customSalt = generateSalt(32); // Uint8Array of 32 random bytes

Security Configuration

The library allows you to configure security parameters for password hashing:

• Iterations: Number of PBKDF2 iterations (default: 100,000). Higher values increase security but take more time.
• Key Length: Length of the derived key in bits (default: 256). Supported values: multiples of 8, minimum 8 bits.
• Hash Algorithm: The underlying hash function (default: "SHA-256"). Supported: "SHA-1", "SHA-256", "SHA-384", "SHA-512".

Important: When verifying passwords, you must use the same parameters that were used during hashing. The library does not store these parameters automatically.

API Overview

Password Hashing

• hash(password: string, salt: Uint8Array, iterations?: number, keyLength?: number, hashAlgorithm?: string): Promise<Uint8Array>
  Hashes a password using PBKDF2. Defaults: 100,000 iterations, 256-bit key length, SHA-256 algorithm.

• verify(password: string, hashedPassword: Uint8Array, salt: Uint8Array, iterations?: number, keyLength?: number, hashAlgorithm?: string): Promise<boolean>
  Verifies a password against a hashed value. Parameters must match those used during hashing.

Data Encryption/Decryption

• encrypt(data: Uint8Array, key: CryptoKey): Promise<{ encryptedData: Uint8Array; iv: Uint8Array }>
  Encrypts data using AES-GCM.

• decrypt(encryptedData: Uint8Array, key: CryptoKey, iv: Uint8Array): Promise<Uint8Array>
  Decrypts data using AES-GCM.

Key Derivation

• deriveKey(secret: string, salt: Uint8Array, iterations: number = 100000): Promise<CryptoKey>
  Derives a cryptographic key from a secret using PBKDF2.

Utilities

• toBase64(data: Uint8Array): string
  Encodes a Uint8Array to a Base64 string.

• fromBase64(encoded: string): Uint8Array
  Decodes a Base64 string to a Uint8Array.

• generateSalt(length: number = 16): Uint8Array
  Generates a cryptographically secure random salt.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

MIT