@shgysk8zer0/aes-gcm

A JWK-base crypto library using AES-GCM secret keys

• Code of Conduct
• Contributing

Description

A JWK-based crypto library using AES-GCM secret keys. This library provides a set of functions for generating, encrypting, decrypting, signing, and verifying cryptographic keys and data. It supports various cryptographic algorithms and formats, making it easy to handle secure data operations in JavaScript.

Installation

Using npm

npm install @shgysk8zer0/aes-gcm

Using unpkg.com

<script type="importmap">
{
  "imports": {
    "@shgysk8zer0/aes-gcm": "https://unpkg.com/@shgysk8zer0/aes-gcm?module"
  }
}
</script>
<script type="module">
  import { generateSecretKey } from '@shgysk8zer0/aes-gcm';

  const key = await generateSecretKey();
  console.log(key);
</script>

Usage Examples

Generating a Secret Key

import { generateSecretKey } from '@shgysk8zer0/aes-gcm';

const key = await generateSecretKey();
console.log(key);

Documentation for generateSecretKey

Encrypting and Decrypting Data

import { encrypt, decrypt, TEXT } from '@shgysk8zer0/aes-gcm';

const key = await generateSecretKey();
const data = 'Hello, World!';
const encrypted = await encrypt(key, data);
const decrypted = await decrypt(key, encrypted, { output: TEXT });

console.log(decrypted); // 'Hello, World!'

Documentation for encrypt and Documentation for decrypt

Encrypting and Decrypting Files

import { encryptFile, decryptFile } from '@shgysk8zer0/aes-gcm';

const key = await generateSecretKey();
const file = new File(['Hello, World!'], 'hello.txt', { type: 'text/plain' });
const encryptedFile = await encryptFile(key, file);
const decryptedFile = await decryptFile(key, encryptedFile);

console.log(await decryptedFile.text()); // 'Hello, World!'

Documentation for encryptFile and Documentation for decryptFile

Creating a Secret Key from a Password

import { createSecretKeyFromPassword } from '@shgysk8zer0/aes-gcm';

const password = 'super-secret-password';
const key = await createSecretKeyFromPassword(password);
console.log(key);

Documentation for createSecretKeyFromPassword

Hashing Data

import { hash, HEX } from '@shgysk8zer0/aes-gcm';

const data = 'Hello, World!';
const hashed = await hash(data, { output: HEX });

console.log(hashed);

Documentation for hash

Signing and Verifying Data

import { sign, verifySignature } from '@shgysk8zer0/aes-gcm';

const key = await generateSecretKey();
const data = 'Hello, World!';
const signature = await sign(key, data);
const isValid = await verifySignature(key, data, signature);

console.log(isValid); // true

Documentation for sign and Documentation for verifySignature

API Documentation

Methods

| Method | Description | Example | |--------|-------------|---------| | generateSecretKey(options) | Generates a new secret key. | const key = await generateSecretKey(); | | encrypt(key, thing, options) | Encrypts data using a provided CryptoKey. | const encrypted = await encrypt(key, data); | | decrypt(key, thing, options) | Decrypts data using a provided CryptoKey. | const decrypted = await decrypt(key, encrypted); | | encryptFile(key, file, name) | Encrypts a file using a provided CryptoKey. | const encryptedFile = await encryptFile(key, file); | | decryptFile(key, file) | Decrypts a file using a provided CryptoKey. | const decryptedFile = await decryptFile(key, encryptedFile); | | createSecretKeyFromPassword(pass, options) | Creates a secret key from a password. | const key = await createSecretKeyFromPassword(password); | | hash(thing, options) | Hashes data using a specified algorithm. | const hashed = await hash(data); | | sign(key, thing, options) | Signs data using a provided CryptoKey. | const signature = await sign(key, data); | | verifySignature(key, source, signature, options) | Verifies the signature of a given data using a provided CryptoKey. | const isValid = await verifySignature(key, data, signature); |

Options

Generate Secret Key

generateSecretKey(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | name | string | 'AES-GCM' | The name of the algorithm. | | length | number | 256 | The desired key length in bits. | | extractable | boolean | true | Whether the key should be extractable. | | usages | string[] | ['encrypt', 'decrypt'] | Usages for the key. |

Encrypt Data

encrypt(key, thing, options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | iv | Uint8Array | undefined | Initialization vector (IV) used for encryption. | | output | string | 'ui8' | Output format for the encrypted data. |

Decrypt Data

decrypt(key, thing, options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | input | string | 'base64' | Input format of the encrypted data when thing is a string. | | output | string | 'buffer' | Output format for the decrypted data. |

Create Secret Key from Password

createSecretKeyFromPassword(pass, options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | name | string | 'AES-GCM' | The name of the key algorithm. | | length | number | 256 | The desired key length in bits. | | hash | string | 'SHA-256' | The hash algorithm to use for PBKDF2. | | iterations | number | 100000 | The number of iterations for PBKDF2. | | extractable | boolean | false | Whether the key can be extracted. | | usages | string[] | ['encrypt', 'decrypt'] | The intended usages for the key. |

Hash Data

hash(thing, options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | algo | string | 'SHA-256' | The hashing algorithm to use. | | output | string | 'buffer' | The output format for the hash. |

Sign Data

sign(key, thing, options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | algo | string | 'SHA-256' | The hashing algorithm to use. | | iv | Uint8Array | undefined | Initialization vector (IV) used for encryption. | | output | string | 'ui8' | Output format for the signed data. |

Verify Signature

verifySignature(key, source, signature, options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | algo | string | 'SHA-256' | The hashing algorithm used for signing. | | input | string | 'hex' | The input format of the signature if it's a string. |

Encrypt File

encryptFile(key, file, name)

| Option | Type | Default | Description | |--------|------|---------|-------------| | key | CryptoKey | required | A cryptographic key for encryption. | | file | File | required | The file to encrypt. | | name | string | Date.now().toString(36) + FILE_EXT | The name of the encrypted file. |

Decrypt File

decryptFile(key, file)

| Option | Type | Default | Description | |--------|------|---------|-------------| | key | CryptoKey | required | A cryptographic key for decryption. | | file | File | required | The file to decrypt. |