🔐 browserify-hybrid-crypto

> Hybrid encryption and signing library built on Web Crypto (AES + RSA + HMAC)


---

✨ Features

- 🔒 Hybrid Encryption: AES-GCM for fast encryption + RSA-OAEP for secure key exchange.
- 🖊️ Integrity Protection: HMAC-SHA signatures to ensure authenticity, protecting against tampering.
- 📦 Lightweight: Uses only the native Web Crypto API.
- 🌐 Cross-Platform: Works in modern browsers and Node.js.
- 🛠️ Simple API: Just call hybridEncrypt and hybridDecrypt.

---

📦 Installation

``bash
npm install browserify-hybrid-crypto
`

or with yarn:

`bash
yarn add browserify-hybrid-crypto
`

---

🚀 Usage

$3

`ts
import { hybridEncrypt } from "browserify-hybrid-crypto";

const publicKeyPEM = -----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----;

async function runEncrypt() {
// You can pass options to configure encryption
const result = await hybridEncrypt(publicKeyPEM, "Hello Hybrid Crypto! 🔐", {
aesAlgorithm: "AES-GCM", // "AES-GCM" | "AES-CBC" | "AES-CTR"
aesKeyLength: 256, // 128 | 192 | 256
ivLength: 12, // IV length in bytes (default: 12 for GCM)
hmacHash: "SHA-256", // "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512"
rsaOaepHash: "SHA-256", // "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512"
ctrCounter: undefined, // Uint8Array (for AES-CTR only)
ctrLength: 64, // Counter length in bits (for AES-CTR only)
});

console.log(result);
/*
{
encryptedSessionKey: Uint8Array,
encryptedSigningKey: Uint8Array,
encryptedData: Uint8Array,
signature: Uint8Array,
iv: Uint8Array // IV or counter used for AES
}
*/
}
`

---

$3

`ts
import { hybridDecrypt } from "browserify-hybrid-crypto";

const privateKeyPEM = -----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASC...
-----END PRIVATE KEY-----;

async function runDecrypt(encryptedPayload) {
// Pass the same options used for encryption if you customized them
const message = await hybridDecrypt(privateKeyPEM, encryptedPayload, {
aesAlgorithm: "AES-GCM",
aesKeyLength: 256,
ivLength: 12,
hmacHash: "SHA-256",
rsaOaepHash: "SHA-256",
ctrCounter: undefined,
ctrLength: 64,
});

console.log("Decrypted message:", message);
// "Hello Hybrid Crypto! 🔐"
}
`

---

🔑 Generating RSA Keys

You’ll need an RSA key pair in PEM format. You can generate them either via OpenSSL or directly in the browser.

$3

`bash


Generate a 4096-bit private key

openssl genrsa -out private.pem 4096

Extract the public key from the private key

openssl rsa -in private.pem -pubout -out public.pem
`

Now you’ll have:

- private.pem → RSA private key (use in hybridDecrypt)
- public.pem → RSA public key (use in hybridEncrypt)

---

$3

You can generate RSA keys directly with the Web Crypto API:

`ts
async function generateRSAKeyPair() {
const keyPair = await crypto.subtle.generateKey(
{
name: "RSA-OAEP",
modulusLength: 4096,
publicExponent: new Uint8Array([1, 0, 1]), // 65537
hash: "SHA-256",
},
true,
["encrypt", "decrypt"],
);

const spki = await crypto.subtle.exportKey("spki", keyPair.publicKey);
const pkcs8 = await crypto.subtle.exportKey("pkcs8", keyPair.privateKey);

const publicKeyPEM = toPEM(spki, "PUBLIC KEY");
const privateKeyPEM = toPEM(pkcs8, "PRIVATE KEY");

console.log("Public Key PEM:\n", publicKeyPEM);
console.log("Private Key PEM:\n", privateKeyPEM);

return { publicKeyPEM, privateKeyPEM };
}

function toPEM(buffer, type) {
const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
const chunks = base64.match(/.{1,64}/g).join("\n");
return -----BEGIN ${type}-----\n${chunks}\n-----END ${type}-----;
}
`

This will generate a fresh key pair and export both keys in PEM format, ready to use with hybridEncrypt and hybridDecrypt.

---

🛡️ Secure Chat Example

browserify-hybrid-crypto combines asymmetric encryption (RSA-OAEP), symmetric session keys (AES-CBC), and signing keys (HMAC) to ensure secure, authenticated communication.

Below is a typical flow for a chat between Alice and Bob (the same process applies to group chats):

1. Room Creation:

Bob creates a chat room and immediately generates an RSA-OAEP public/private key pair.

2. Key Exchange:

Alice joins the room and also generates her own RSA-OAEP key pair. Both users exchange public keys.

3. Message Preparation:

When Bob sends a message, he generates:
- A random session key (AES-CBC)
- A signing key (HMAC-SHA256)
- An initialization vector (IV) for encryption

4. Encryption & Signing:

Bob encrypts his message using the session key and IV, then signs the encrypted message with the signing key.

5. Key Wrapping:

The session key and signing key are each encrypted (wrapped) with every recipient’s public key (for a group chat, this is done for each participant).

6. Sending the Package:

Bob sends a package to all recipients containing:
- The encrypted message
- The IV
- The signature
- The encrypted session key(s)
- The encrypted signing key(s)

7. Decryption & Verification:

Each recipient (e.g., Alice) decrypts the session and signing keys with their private key, decrypts the message, and verifies the signature.

Group chats follow the same process: each recipient receives their own encrypted keys, and can independently decrypt and verify messages.

---

$3

`mermaid
sequenceDiagram
participant Bob
participant Alice

Bob->>Bob: Generate RSA key pair
Alice->>Alice: Generate RSA key pair
Bob->>Alice: Send Bob's public key
Alice->>Bob: Send Alice's public key

Bob->>Bob: hybridEncrypt(Alice's public key, message)
Bob->>Alice: Send { encrypted message, IV, signature, encrypted session key, encrypted signing key }
Alice->>Alice: hybridDecrypt(Alice's private key, encrypted payload)
Note over Alice: Decrypts session key and signing key
Decrypts message
Verifies signature

Alice->>Alice: hybridEncrypt(Bob's public key, reply message)
Alice->>Bob: Send { encrypted reply, IV, signature, encrypted session key, encrypted signing key }
Bob->>Bob: hybridDecrypt(Bob's private key, encrypted payload)
Note over Bob: Decrypts session key and signing key
Decrypts reply message
Verifies signature
``

---

Note:
In group chats, Bob repeats the key encryption step for each participant, so every user receives their own encrypted session and signing keys.

$3

To protect against replay attacks, you can include a nonce or timestamp in each message. This ensures that even if an attacker intercepts a message, they cannot resend it without the correct nonce or timestamp.

It's recommended to implement a mechanism to track used nonces or timestamps on the server side, so that each one can only be used once.

Beware that this library does not handle replay attack prevention directly; you need to implement it in your application logic.

---

⚖️ License

MIT © Vlad Kucherov

---

💡 Notes

- Supports RSA-OAEP + AES-GCM + HMAC-SHA256.
- Works in browsers and Node.js environments.
- RSA key length recommended: 4096 bits.
- Always keep your private key secret!