Skip to content

Commit

Permalink
add crypto docs
Browse files Browse the repository at this point in the history
  • Loading branch information
JarbasAl committed Dec 24, 2024
1 parent dbe3b95 commit f37f466
Show file tree
Hide file tree
Showing 4 changed files with 107 additions and 2 deletions.
2 changes: 0 additions & 2 deletions docs/12_handshake.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,6 @@ For detailed code and various usage examples, you can refer to the [Poorman Hand
- Encrypts the symmetric session key to allow further communication using the shared key.


![HANDSHAKE.png](HANDSHAKE_V1.png)

---

## Workflow: Server Perspective
Expand Down
106 changes: 106 additions & 0 deletions docs/19_crypto.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# Encryption

HiveMind ensures secure communication between devices by using modern cryptographic techniques. This page provides an overview of how messages are encrypted in transit, the structure of encrypted messages, and the process of encryption key generation.

- **End-to-End Encryption**: Messages are encrypted on the sender's device and decrypted only on the receiver's device, ensuring complete confidentiality.
- **Mutual Authentication**: The identity verification step ensures that both devices share the same credentials and trust each other.
- **Resistance to Replay Attacks**: The use of unique IVs for each message prevents attackers from reusing captured messages.
- **Strong Key Derivation**: By leveraging PBKDF2 and a shared salt, HiveMind protects against brute-force and dictionary attacks.

---

## Terminology

Before diving into the details, here are key terms used in this documentation:

- **Plaintext**: Unencrypted data, the original readable content before encryption.
- **Ciphertext**: Encrypted data, unreadable without the decryption key.
- **[AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)**: Advanced Encryption Standard, a symmetric encryption algorithm.
- **[GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode)**: Galois/Counter Mode, a mode of operation for AES that provides both encryption and message authentication.
- **[IV](https://en.wikipedia.org/wiki/Initialization_vector)**: Initialization vector (sometimes called `nonce`), a unique value used to initialize encryption and ensure message uniqueness.
- **[MAC](https://en.wikipedia.org/wiki/Message_authentication_code)**: Message Authentication Code (sometimes called `tag` or Integrity Check Value (`ICV`)), used to verify the authenticity and integrity of a message.
- **[Salt](https://en.wikipedia.org/wiki/Salt_(cryptography))**: A random value used during key derivation to ensure unique and secure key generation, even with repeated passwords.
- **[SHA-2](https://en.wikipedia.org/wiki/SHA-2)**: A family of cryptographic hash functions, used for generating hash values (e.g., SHA-256 is used in HiveMind).
- **[PBKDF2](https://en.wikipedia.org/wiki/PBKDF2)**: Password-Based Key Derivation Function 2, a cryptographic function that strengthens passwords by applying hashing multiple times to derive secure keys.

---

## Overview

HiveMind uses **AES-GCM (Advanced Encryption Standard in Galois/Counter Mode)** for authenticated encryption of messages in transit. This method provides both **confidentiality** (protecting the message content) and **integrity** (ensuring that messages have not been tampered with during transmission).

To securely exchange messages, HiveMind leverages a **key derivation and exchange mechanism** that avoids directly sharing sensitive credentials, ensuring secure key generation and agreement between devices.

---

## Encryption in Transit

When two devices communicate over HiveMind, all messages are encrypted before being transmitted over the network. This prevents eavesdropping and ensures that any intercepted messages are unreadable without the appropriate key.

Each encrypted message contains the following components:
```json
{
"ciphertext": "<encrypted_message>",
"tag": "<authentication_tag>",
"nonce": "<initialization_vector>"
}
```

- **Ciphertext**: The encrypted form of the original plaintext message.
- **Tag**: A message authentication code (MAC) that ensures the integrity and authenticity of the message.
- **Nonce (IV)**: A unique initialization vector used for encryption. It ensures that each message is encrypted uniquely, even if the same key and plaintext are reused.

The `nonce` and `tag` are included in the message unencrypted, while the `ciphertext` remains confidential. This allows the receiving device to verify and decrypt the message.

---

## Key Generation and Exchange

To securely encrypt and decrypt messages, HiveMind uses a shared secret key. This key is never transmitted directly but is derived independently by each device using the following steps:


![HANDSHAKE.png](HANDSHAKE_V1.png)


### 1. **Handshake and Identity Verification**
- Each device generates a **hash-based subkey (HSUB)** using:
- A randomly generated **initialization vector (IV)**.
- The user's **password** (or pre-shared secret).
- A cryptographic hash function, such as `SHA-256`.
- Devices exchange their `HSUB` and `IV` values over the network.
- Upon receiving the other's `HSUB`, each device regenerates it locally using the received `IV` and its own password. If the computed and received `HSUB` match, the devices verify each other's identity.

### 2. **Deriving a Common Salt**
- A shared salt is generated by XORing the `IV` values exchanged during the handshake:
```text
Salt = IV_A ⊕ IV_B
```
- This salt ensures that each session has a unique basis for key derivation.

### 3. **Key Derivation**
- Both devices derive a **common secret key** using the following inputs:
- The **salt** from the previous step.
- The user's **password**.
- The key derivation process uses **PBKDF2** (Password-Based Key Derivation Function 2) with `HMAC-SHA256` to produce a cryptographically strong key.

This approach ensures that both devices independently derive the same encryption key without directly transmitting it over the network.

---

## Secure Message Exchange

Once the secret key is derived, it is used to encrypt and decrypt all messages exchanged between devices. The process is as follows:

1. **Encryption**:
- The sending device uses the secret key to encrypt the plaintext message using AES-GCM.
- The resulting ciphertext, along with the `nonce` and `tag`, is packaged into a message and sent over the network.

2. **Decryption**:
- The receiving device extracts the `ciphertext`, `nonce`, and `tag` from the message.
- Using the same secret key, it decrypts the `ciphertext` and verifies the message integrity using the `tag`.



---

HiveMind's encryption process provides a secure foundation for communication, protecting sensitive data against unauthorized access and tampering. Let us know if you'd like to explore specific implementation details or examples!
Binary file removed docs/pswd_HANDSHAKE.png
Binary file not shown.
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ nav:
- Database: 17_database.md
- Pairing: 03_pairing.md
- Permissions: 16_permissions.md
- Encryption: 19_crypto.md
- Handshake: 12_handshake.md
- Developers:
- Libraries: 11_devs.md
Expand Down

0 comments on commit f37f466

Please sign in to comment.