Merge pull request #137 from MatrixAI/feature-update-reference

Feature update reference, branch renaming

Author: aryanjassal

docs/reference/architecture.md

@@ -2,9 +2,9 @@
 
 ### Node ID
 
-In order to interact with other nodes, PolyKey uses a unique node ID identifier.
+In order to interact with other nodes, Polykey uses a unique node ID identifier.
 Currently, the fingerprint of the root public key of a keynode is calculated
-using a sha256 has function and is then transformed into base64 encoding to
+using a SHA256 hash function and is then transformed into base64 encoding to
 obtain a keynode’s Node ID. This will consistently produce a string of 44
 characters. In the future, PolyKey will used an ed25519 public key directly
 encoded using base64 to create the Node ID. As the signature of ed25519 keys can

docs/reference/architecture/DES.md

@@ -0,0 +1,122 @@
+# 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** 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
+
+Polykey uses **XChaCha20-Poly1305**, 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 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/architecture/README.md

@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Architecture
+
+<DocCardList />

docs/reference/architecture/ecis.md

@@ -0,0 +1,129 @@
+# 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/architecture/encryption-algorithms.md

@@ -0,0 +1,84 @@
+# 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.