feat: update and lint encryption documentation

Author: xrissoula

docs/reference/DES.md

@@ -0,0 +1,80 @@
+# Symmetric Data Encapsulation Scheme (DES)
+
+Polykey’s state is completely stored in the database. This means everything critical to the system's function—keys, metadata, and configurations—is written to disk. To ensure the security and integrity of this data, we encrypt the database using a **32-byte Data Encryption Key (DB Key)** and the **XChaCha20-Poly1305-IETF** symmetric encryption algorithm, provided by **libsodium**.
+
+## Why We Use Symmetric Encryption
+
+Encryption is non-negotiable for a system like Polykey, where data security is a core priority. Symmetric encryption is used for:
+
+- **Confidentiality** - Ensuring database contents are only accessible to the rightful owner.
+- **Integrity** - Preventing unauthorized tampering by detecting any modifications.
+- **Performance** - Symmetric encryption is significantly faster than asymmetric encryption for large datasets.
+
+## Database Encryption Key (DB Key)
+
+### **How the DB Key Works**
+
+The DB Key is a **randomly generated 32-byte key** that encrypts all database content. This key is stored on disk, but never in plaintext—it is always encrypted before being written to storage.
+
+The DB Key is used to encrypt and decrypt the entire database, meaning that without it, **all data in the system is inaccessible**.
+
+### **Why the DB Key is Not Derived from the Root Key**
+
+A common approach in cryptographic systems is to derive all keys from a single root key. However, this is not how Polykey manages database encryption. The DB Key is independent from the root key for the following reasons:
+
+1. **Key Rotation & Flexibility**  
+   If the root key were used to derive the DB Key, changing the root key would require re-encrypting the entire database. This would be a **catastrophic** operation in terms of efficiency and usability. Instead, by keeping the DB Key separate, the database can remain encrypted even when the root key is changed.
+
+2. **Minimizing Attack Surfaces**  
+   If an attacker compromises the root key, they still cannot access the database contents without the DB Key. This adds an extra layer of security.
+
+3. **Persistence Across Keypair Changes**  
+   In Polykey, root keypairs can be swapped out periodically for security reasons (like how passwords should be rotated). By decoupling the DB Key, the database encryption remains stable across key rotations.
+
+## Encryption Algorithm: XChaCha20-Poly1305-IETF
+
+Polykey uses **XChaCha20-Poly1305-IETF**, a widely respected symmetric encryption scheme known for its:
+
+- **256-bit key size** - Strong encryption without performance tradeoffs.
+- **192-bit nonce** - Ensures nonce reuse attacks are virtually impossible.
+- **Authenticated encryption** - Includes integrity checks, so any unauthorized modifications are detected.
+
+### **Why XChaCha20-Poly1305?**
+
+1. **Nonce Misuse Resistance**  
+   Unlike AES-GCM, which has strict nonce reuse requirements, XChaCha20 allows for random nonce generation with no risk of catastrophic failures.
+
+2. **High Performance**  
+   Stream ciphers like XChaCha20 are significantly faster than block ciphers like AES in many scenarios, making them well-suited for encrypting large datasets.
+
+3. **Compatibility with Libsodium**  
+   Libsodium is a battle-tested cryptographic library that provides a simple and secure implementation of XChaCha20-Poly1305, reducing the risk of implementation errors.
+
+## Key Rotation & Secure Storage
+
+### **Key Rotation Strategy**
+
+Regular key rotation is a fundamental security practice. However, since re-encrypting an entire database is computationally expensive, Polykey manages key rotations in a way that minimizes disruption:
+
+1. **The DB Key is swapped periodically** - This reduces long-term key exposure.
+2. **New keys are securely generated and encrypted using KEM (Key Encapsulation Mechanism)** - This ensures a smooth transition without exposing old encrypted data.
+3. **Polykey handles the transition automatically** - Users do not need to worry about database re-encryption when keypairs are rotated.
+
+### **How the DB Key is Stored**
+
+The DB Key is **never stored in plaintext**. Instead, it is encrypted and saved as a **JWE (JSON Web Encryption) file**. This file is securely managed to ensure that only authorized nodes can decrypt and use it.
+
+## Security Considerations
+
+- **Loss of the DB Key = Complete Data Loss**  
+  If the encrypted DB Key is lost, **all data within Polykey is permanently inaccessible**. Users must ensure backups are properly managed.
+
+- **Frequent Key Rotation is Good Practice**  
+  Regularly rotating the DB Key prevents long-term exposure and mitigates risks from potential future cryptographic weaknesses.
+
+- **Secure Backup Management is Critical**  
+  Since Polykey does not store plaintext recovery keys, **users must securely back up their 24-word recovery code** to ensure they can regain access if needed.
+
+## Conclusion
+
+The **Symmetric Data Encapsulation Scheme (DES)** is a critical component of Polykey's security model. By leveraging XChaCha20-Poly1305-IETF for high-speed encryption and ensuring the **DB Key remains independent from the root key**, Polykey maintains a **balance between security, performance, and usability**.

docs/reference/ecis.md

@@ -0,0 +1,99 @@
+# Elliptic Curve Integrated Encryption Scheme (ECIES)
+
+## Overview
+
+Polykey's security model is built around **Elliptic Curve Integrated Encryption Scheme (ECIES)**. ECIES is a hybrid cryptosystem that combines the efficiency of symmetric encryption with the security of asymmetric encryption, making it ideal for key exchange and encrypted communication.
+
+At its core, ECIES allows secure communication between parties without requiring them to share a secret key in advance. Instead, it uses elliptic curve cryptography (ECC) to derive a shared secret dynamically, ensuring both confidentiality and authenticity.
+
+## Why Polykey Uses ECIES
+
+Polykey leverages ECIES because it provides:
+
+* **Strong security**: ECC-based key exchange ensures forward secrecy.
+* **Efficient performance**: ECC is computationally faster than RSA at equivalent security levels.
+* **Hybrid encryption**: Uses symmetric encryption for bulk data and asymmetric encryption for key exchange.
+* **Secure key encapsulation**: Keys are encrypted in a way that prevents exposure during transmission.
+
+## How ECIES Works
+
+ECIES works by using Elliptic Curve Diffie-Hellman (ECDH) for key exchange and a symmetric cipher for encryption.
+
+The encryption process follows these steps:
+
+1. **Key Exchange**:
+
+* The sender generates a temporary ephemeral key pair.
+* The sender derives a shared secret using their ephemeral private key and the recipient's public key.
+
+2. **Key Derivation**:
+
+* The shared secret is used to generate encryption keys through a Key Derivation Function (KDF).
+
+3. **Encryption**:
+
+* A symmetric encryption algorithm (e.g., XChaCha20-Poly1305 ) encrypts the plaintext.
+* An authentication tag is generated to prevent tampering.
+
+4. **Transmission**:
+
+* The ciphertext, ephemeral public key, and authentication tag are sent to the recipient.
+
+5. **Decryption**:
+
+* The recipient uses their private key to derive the shared secret.
+* The symmetric key is reconstructed using the same KDF.
+* The ciphertext is decrypted, and authenticity is verified.
+
+## ECIES in Polykey
+
+Polykey uses ECIES as the foundation for secure communication, storage, and key management. Specifically, it is used for:
+
+* **Key Encapsulation Mechanism (KEM)**: Encapsulating encryption keys for secure storage.
+* **Node-to-Node Communication**: Establishing secure tunnels between Polykey nodes.
+* **Key Exchange**: Securely transferring symmetric encryption keys for encrypted storage.
+
+### Key Encapsulation and Secure Storage
+
+Polykey encrypts sensitive keys using ECIES-based encapsulation. This means:
+
+* The Data Encryption Key (DB Key) is never stored in plaintext.
+* The DB Key is wrapped using ECIES before being saved.
+* Only an authenticated node with the correct private key can unwrap the DB Key and decrypt the database.
+
+### Secure Messaging Between Nodes
+
+When Polykey nodes communicate, they exchange keys using ECIES. This allows them to:
+
+* Establish a secure session without pre-sharing a secret key.
+* Prevent man-in-the-middle attacks by ensuring only authorized nodes can decrypt messages.
+* Authenticate each other using their public-private key pairs.
+
+## Why ECIES is Preferred Over RSA
+
+Historically, RSA-based encryption was the standard for key exchange, but ECIES provides several advantages:
+
+| Feature | ECIES (ECC) | RSA |
+|---------|------------|-----|
+| **Key Size (bits)** | 256 | 2048 |
+| **Security Level** | Stronger | Weaker at equivalent key size |
+| **Performance** | Faster | Slower |
+| **Key Exchange** | Supported | Not ideal for key exchange |
+
+Because ECIES achieves the same level of security as RSA with much smaller key sizes, it is the preferred choice for modern cryptographic systems like Polykey.
+
+## Future-Proofing Against Quantum Attacks
+
+Polykey is designed to evolve with cryptographic advancements. While ECIES is secure today, quantum computers could potentially break ECC in the future. When quantum-resistant encryption becomes practical, Polykey will migrate to a Post-Quantum Integrated Encryption Scheme (PQIES).
+
+## Conclusion
+
+ECIES is at the heart of Polykey's encryption model, providing secure, efficient, and scalable key exchange. By combining elliptic curve cryptography with hybrid encryption techniques, Polykey ensures strong security, efficient performance, and forward secrecy.
+
+Polykey's implementation of ECIES allows:
+
+* Secure key exchange without pre-shared secrets.
+* Confidential and authenticated communication between nodes.
+* Safe and efficient key storage using encapsulated encryption.
+
+As cryptographic standards evolve, Polykey remains committed to using the most secure and performant encryption schemes available.

docs/reference/encryption-algorithms.md

@@ -0,0 +1,68 @@
+# Encryption Algorithms and Security Considerations
+
+## Overview
+
+Polykey's security model is built on modern cryptographic principles to ensure confidentiality, integrity, and authentication across all operations. This document outlines the encryption algorithms Polykey employs, their strengths, and key security considerations for maintaining a secure system.
+
+## Encryption Algorithms Used in Polykey
+
+Polykey integrates a hybrid cryptosystem, combining symmetric and asymmetric cryptographic algorithms for optimal security and performance.
+
+### Symmetric Encryption
+
+* **AES-GCM (Advanced Encryption Standard - Galois/Counter Mode)**
+  * Used for encrypting data at rest and in transit.
+  * Provides both encryption and authentication in a single step.
+  * 256-bit key length for strong security.
+  * Resistant to padding oracle attacks due to its authenticated encryption structure.
+
+### Asymmetric Encryption
+
+* **X25519 (Elliptic Curve Diffie-Hellman)**
+  * Used for key exchange and secure session establishment.
+  * Based on Curve25519, which is efficient and resistant to side*channel attacks.
+  * Provides forward secrecy by generating ephemeral session keys.
+
+* **Ed25519 (Elliptic Curve Digital Signature Algorithm)**
+  * Used for signing and verifying messages and transactions.
+  * Strong resistance to side-channel attacks.
+  * Deterministic signatures prevent nonce-related vulnerabilities.
+
+### Key Encapsulation Mechanism (KEM)
+
+* **ECIES (Elliptic Curve Integrated Encryption Scheme)**
+  * Facilitates secure encryption of symmetric keys during key exchange.
+  * Uses elliptic curve cryptography for efficient and secure key wrapping.
+  * Ensures confidentiality and authenticity of the exchanged key.
+
+## Security Considerations
+
+### 1. Key Management
+
+* **Recovery Codes:** Users must securely store their 24-word recovery code, as Polykey does not store private keys.
+* **Key Rotation:** Regular key rotation mitigates the risk of long-term key exposure.
+* **Secure Storage:** Encrypted key material must be stored in a secure environment to prevent unauthorized access.
+
+### 2. Forward Secrecy
+
+* Polykey ensures forward secrecy through ephemeral key exchange using X25519.
+* If a private key is compromised, past communications remain secure.
+
+### 3. Authentication & Integrity
+
+* Digital signatures (Ed25519) ensure data authenticity and prevent tampering.
+* Authenticated encryption (AES-GCM) guarantees data integrity.
+
+### 4. Resistance to Quantum Threats
+
+* While current encryption methods are secure, future quantum computing advancements may break classical cryptography.
+* Polykey's roadmap includes exploring post-quantum cryptographic alternatives.
+
+### 5. Attack Surface Reduction
+
+* Minimizing reliance on outdated cryptographic algorithms.
+* Eliminating common cryptographic pitfalls such as RSA-based key exchanges, which are vulnerable to decryption with modern computing power.
+
+## Conclusion
+
+Polykey employs a combination of AES-GCM, X25519, Ed25519, and ECIES to ensure strong security across all cryptographic operations. By following best practices in key management, forward secrecy, and attack surface reduction, Polykey maintains a robust security posture. Future updates may incorporate post-quantum cryptographic schemes to address emerging threats.

docs/reference/hybrid-cryptosystem.md

@@ -0,0 +1,73 @@
+# Hybrid Cryptosystem
+
+Polykey's security model is built on a Hybrid Cryptosystem, which combines both symmetric and asymmetric encryption to achieve secure communication, storage, and identity management.
+
+## Why Hybrid Encryption?
+
+Encryption is necessary to protect sensitive data, but different encryption methods serve different purposes. A hybrid cryptosystem merges the strengths of both:
+
+**Asymmetric Encryption** (Public and Private Key Pairs)
+
+* Used for securely exchanging encryption keys
+* Allows verification of signatures
+* Ensures secure communication without prior key exchange
+
+**Symmetric Encryption** (Shared Secret Keys)
+
+* Used for encrypting large amounts of data efficiently
+* Faster than asymmetric encryption
+* Requires a secure method to exchange keys
+
+By combining these two, Polykey ensures security in transit, at rest, and in use.
+
+## Polykey's Implementation of Hybrid Cryptography
+
+Polykey's hybrid cryptosystem is based on the Elliptic Curve Integrated Encryption Scheme (ECIES) and consists of two primary mechanisms:
+
+1. **Key Encapsulation Mechanism (KEM)**  
+
+* Uses symmetric encryption to securely exchange a symmetric key.
+* This ensures that even if an attacker intercepts the communication, they cannot derive the encryption key without access to the private key.
+
+2. **Data Encapsulation Scheme (DES)**  
+
+* Uses symmetric encryption (XChaCha20-Poly1305) to encrypt all Polykey data.
+* This ensures that once the symmetric key is established, encryption is fast and efficient.
+
+### How This Works in Polykey
+
+* The sender encrypts data using a symmetric key.
+* This symmetric key is then encrypted using the recipient's public key.
+* The recipient decrypts the symmetric key using their private key.
+* Once the symmetric key is obtained, it is used to decrypt the original data.
+
+This method keeps encryption fast and secure, reducing computational overhead while maintaining strong security guarantees.
+
+## Why Not Just Use One Type of Encryption?
+
+Each encryption method has limitations:
+
+**Asymmetric encryption is slow**  
+
+* Encrypting large amounts of data with public-private key pairs is inefficient.
+* It is only practical for encrypting small pieces of data, like symmetric keys.
+
+**Symmetric encryption needs secure key exchange**  
+
+* If a secret key is leaked or intercepted, the encrypted data is compromised.
+* It requires a secure way to distribute and manage encryption keys.
+
+A **hybrid cryptosystem** provides the best of both worlds:  
+
+* **Asymmetric encryption** protects the key exchange.  
+* **Symmetric encryption** handles bulk data encryption efficiently.
+
+## Future-Proofing with Post-Quantum Cryptography
+
+Polykey currently uses Elliptic Curve Cryptography (ECC) for its hybrid system, specifically **Ed25519**. However, quantum computing could break ECC in the future. When quantum-safe encryption becomes more practical, Polykey will upgrade to a Post-Quantum Integrated Encryption Scheme to maintain long-term security.
+
+## Conclusion
+
+A hybrid cryptosystem is essential for balancing security, efficiency, and scalability. By leveraging symmetric encryption for key exchange and symmetric encryption for data protection, Polykey ensures robust security while keeping performance high.
+
+Polykey's use of ECIES, KEM, and DES provides a secure foundation for encrypted communication, identity management, and data storage. This hybrid approach ensures that data remains protected, both now and in the future.