How Emvelope Works

The Simple Version (Like a Real Envelope!)

First: A Question

How would you securely get an item from someone in real life? One way is to send them an open padlock that automatically locks when closed, but keep the key to unlock it for yourself. They use your padlock to lock the item. Only you, holding the unique key, can then unlock it.

Think of Emvelope like sending an open envelope with a lock only you can open:

• Get Your Lock and Key: First, you generate a unique set. You get a secret Key (a .key file, like a physical key you keep safe) and a corresponding Open Emvelope (a .emvelope.open file, like a special envelope with built-in lock that hasn't been clicked shut yet).
• Share the Open Emvelope: You can give copies of your Open Emvelope to anyone. They can put files inside this Open Emvelope.
• They Seal the Emvelope: Once they put files inside your Open Emvelope, it automatically snaps shut and locks. Now it's a sealed Emvelope (a .emvelope file). They can send this sealed Emvelope back to you (e.g., via email).
• Only You Can Open It: Because it was locked using your unique Open Emvelope, only your secret Key can unlock and open the sealed Emvelope to reveal the original files. No one else, not even the sender, can open it after it's sealed.

In short: Your Key stays secret. You share your Open Emvelope. Others use it to send you securely locked Emvelopes that only you can open.

---

The Technical Details (For the Curious)

Emvelope uses a standard, strong cryptographic technique called Elliptic Curve Integrated Encryption Scheme (ECIES), specifically with the secp256k1 curve (the same one used by Bitcoin) and AES-256-CBC for the bulk encryption.

Here’s a breakdown of the process:

1. Key Generation

• When you click "Generate New Key & Open Emvelope", the system creates an Elliptic Curve Cryptography (ECC) key pair.
• Your Key is the ECC Private Key (a random 32-byte number). This must be kept absolutely secret.
• Your Open Emvelope is the corresponding ECC Public Key (a point on the elliptic curve, derived from the private key, usually 65 bytes). This can be shared safely.

2. Creating an Emvelope (Encryption)

When someone wants to send you a file securely:

• Ephemeral Key Pair: The sender's browser generates a temporary, one-time-use ECC key pair (let's call them EphPriv and EphPub).
• Key Agreement (ECDH): The sender uses their temporary private key (EphPriv) and your Public Key (your Open Emvelope) to calculate a shared secret point on the curve using the Elliptic Curve Diffie-Hellman (ECDH) algorithm. This shared secret is the same one you could calculate using your Private Key and the sender's temporary public key (EphPub), but crucially, neither private key is ever transmitted.
• Derive Symmetric Key: This ECDH shared secret point is then hashed (using SHA-256) to create a robust 32-byte symmetric encryption key (let's call it AESKey).
• File Encryption (AES): The actual file(s) (zipped if multiple) are encrypted using the Advanced Encryption Standard (AES) algorithm in CBC mode with a 256-bit key (AESKey) and a randomly generated 16-byte Initialization Vector (IV).
• Integrity Check (MAC): To prevent tampering, a Message Authentication Code (MAC) is calculated using HMAC-SHA256. It signs the IV and the encrypted file data, using the AESKey as the HMAC key.
• Assemble the `.emvelope` File: The final .emvelope file bundles everything needed for decryption (except your private key!): <EMVELOPE> (Header) + IV + EphPub (the sender's temporary public key) + MAC + Encrypted File Data.

3. Opening an Emvelope (Decryption)

When you receive an .emvelope file:

• Parse the File: Your browser reads the header, IV, EphPub, MAC, and encrypted data from the file.
• Key Agreement (ECDH): Your browser uses your Private Key (Your Key) and the sender's temporary public key (EphPub found in the file) to calculate the same ECDH shared secret point as the sender did.
• Derive Symmetric Key: This point is hashed (SHA-256) to re-create the exact same AESKey the sender used.
• Verify Integrity (MAC): Your browser recalculates the HMAC-SHA256 using the received IV, the received encrypted data, and the derived AESKey. It compares this calculated MAC with the MAC stored in the file. If they don't match, the file is corrupt or has been tampered with, and decryption stops safely.
• File Decryption (AES): If the MAC verifies, your browser uses the derived AESKey and the IV from the file to decrypt the file data using AES-256-CBC.
• Success! The original file(s) are revealed.

This entire process ensures that only the holder of the correct private key can decrypt the message, and that the message hasn't been altered since it was encrypted.