Root Keypair Generation

[xrissoula]

Description

Issues Fixed

• Relates Create Article in Polykey-Docs Explaining the Polykey Elliptic Curve Article #119 PRO-262

Tasks

• 1. Add article root-keypair-generation.md under docs/reference
• 2. Push to feature-hybrid-elliptical-curve branch
• 3. Review and approve PR
• 4. Merge in to Main

Final checklist

• Domain specific tests
• Full tests
• Updated inline-comment documentation
• Lint fixed
• Squash and rebased
• Sanity check the final build

[xrissoula]

hey @CMCDragonkai, this is ready for final review before merging.

[CMCDragonkai]

Hmm because the PRs aren't stacking on top of each other. There's no way to know the order.

[CMCDragonkai]

To replace punctuation apostrophes with single quotes. Use:

sed -i "s/’/'/g" ./thefile.md

[CMCDragonkai]

So the linter hasn't been updated to the latest standards.

[CMCDragonkai]

[CMCDragonkai]

https://www.conventionalcommits.org/en/v1.0.0/

[CMCDragonkai]

Given that the documentation should start with an overview of Hybrid Elliptic Curve Integrated Encryption Scheme (ECIES) before diving into Root Keypair generation, here’s a suggested structure for the docs/reference directory:

docs/reference/
├── hybrid-ecies.md                   # Overview of ECIES
├── root-keypair.md                   # Detailed guide on Root Keypair generation
├── key-encapsulation-mechanism.md     # Explanation of KEM
├── data-encapsulation-scheme.md       # Explanation of DEM
└── key-derivation-functions.md       # Explanation of KDFs

Suggested Structure:

1. hybrid-ecies.md
   This article should serve as the foundation for understanding the encryption model used in Polykey. It should introduce ECIES, its components (KEM and DEM), and its role in secure communication and key derivation.

   # Hybrid Elliptic Curve Integrated Encryption Scheme (ECIES)
   
   Hybrid ECIES is the cryptographic model that underpins Polykey's secure communication and encryption system. It combines the strengths of asymmetric and symmetric cryptography to provide efficient and secure encryption.
   
   ## Overview
   
   ECIES is a hybrid cryptosystem that consists of two main components:
   
   1. **Key Encapsulation Mechanism (KEM)**: Uses asymmetric encryption (Elliptic Curve Cryptography) to securely transmit a symmetric key.
   2. **Data Encapsulation Scheme (DEM)**: Uses symmetric encryption (e.g., AES or ChaCha20) for bulk encryption of data.
   
   By combining these two components, ECIES ensures that data is securely encrypted and that the keys used for encryption are securely shared.
   
   ## Why ECIES?
   
   - **Efficiency**: Elliptic Curve Cryptography (ECC) is more efficient than traditional RSA, providing the same level of security with smaller key sizes.
   - **Security**: The hybrid nature of ECIES ensures that both the key exchange and data encryption are secure.
   - **Scalability**: ECIES is well-suited for modern applications, including decentralized systems like Polykey.
   
   ## Components of ECIES
   
   ### Key Encapsulation Mechanism (KEM)
   
   KEM is the process of securely transmitting a symmetric key using asymmetric encryption. In Polykey, this is done using the Ed25519 curve.
   
   ### Data Encapsulation Scheme (DEM)
   
   DEM is the process of encrypting actual data using the symmetric key obtained from KEM. In Polykey, this is typically done using AES or ChaCha20.
   
   ### Key Derivation Functions (KDF)
   
   KDFs are used to derive a symmetric key from the shared secret generated by the KEM. In Polykey, HKDF-SHA256 is used for this purpose.
   
   ## How ECIES Works in Polykey
   
   1. **Key Exchange**: Two parties use their public and private keys to derive a shared secret.
   2. **Key Derivation**: The shared secret is passed through a KDF to generate a symmetric key.
   3. **Data Encryption**: The symmetric key is used to encrypt and decrypt data.
   
   This process ensures that data is securely encrypted and that the keys used for encryption are securely shared.
   
   ## Next Steps
   
   Now that you understand the basics of ECIES, you can dive deeper into how Polykey implements these concepts in the [Root Keypair](./root-keypair.md) article.

2. root-keypair.md
   This article should build on the ECIES foundation, focusing on how the Root Keypair is generated and how it fits into the broader encryption model.

   # Root Keypair
   
   The Root Keypair is the foundation of Polykey's encryption model. It is used for secure communication, key derivation, and encryption.
   
   ## What is the Root Keypair?
   
   The Root Keypair is an Ed25519 elliptic curve keypair that serves as the cryptographic identity of a Polykey node. It consists of:
   
   - **Private Key**: A 256-bit secret used for signing and key derivation.
   - **Public Key**: Derived from the private key and used for verification and key exchange.
   
   ## Key Roles of the Root Keypair
   
   1. **Identity**: The public key serves as the unique identity of the node.
   2. **Key Exchange**: The keypair is used in the Key Encapsulation Mechanism (KEM) to securely share encryption keys.
   3. **Data Encryption**: The keypair is used to derive a Data Encryption Key (DEK), which is used for encrypting and decrypting data.
   
   ## How is the Root Keypair Generated?
   
   The Root Keypair is generated using a deterministic process that ensures security and consistency.
   
   1. **Entropy Collection**: High-entropy randomness is collected to seed the key generation process.
   2. **Mnemonic Generation**: The entropy is converted into a 24-word mnemonic phrase using the BIP39 standard.
   3. **Seed Derivation**: The mnemonic is passed through a Key Derivation Function (KDF) to generate a 256-bit seed.
   4. **Keypair Generation**: The seed is used to generate the Ed25519 keypair.
   
   ## Deriving the DEK
   
   The Data Encryption Key (DEK) is derived from the Root Keypair using a Key Derivation Function (KDF).
   
   1. **ECDH**: The Root Private Key and another node's Public Key are combined to create a shared secret.
   2. **KDF**: The shared secret is passed through a KDF (HKDF-SHA256) to generate the DEK.
   3. **Encryption**: The DEK is used for encrypting and decrypting data.
   
   ## Conclusion
   
   The Root Keypair is the cornerstone of Polykey's encryption system. It enables secure communication, key exchange, and data encryption using Elliptic Curve Cryptography. Understanding how the Root Keypair is generated and how it fits into the broader ECIES model is essential for understanding Polykey's security architecture.
   
   ## Next Steps
   
   Learn more about the [Key Encapsulation Mechanism](./key-encapsulation-mechanism.md) and [Data Encapsulation Scheme](./data-encapsulation-scheme.md) that build on the Root Keypair.

3. key-encapsulation-mechanism.md
   This article should explain the Key Encapsulation Mechanism (KEM) in detail, focusing on how it securely transmits symmetric keys.

4. data-encapsulation-scheme.md
   This article should explain the Data Encapsulation Scheme (DEM), focusing on how it encrypts actual data using symmetric keys.

5. key-derivation-functions.md
   This article should explain how Key Derivation Functions (KDFs) are used to derive symmetric keys from shared secrets.

Rationale:

• Logical Flow: Starting with ECIES provides a high-level overview of the encryption model, making it easier to understand the role of the Root Keypair.
• Modularity: Breaking down the components (KEM, DEM, KDF) into separate articles allows for more detailed explanations without overwhelming the reader.
• Progressive Learning: Readers can start with the basics and progressively dive deeper into each component as needed.

[CMCDragonkai]

[CMCDragonkai]

So basically this section:

Should be moved to an overview ECIES.

The other thing is that all images should really stick to excalidraw without too much outside tools, even for cropping.

Then you can experiment with using HTML tags instead of ![](...) in order get images to float to the right.

[CMCDragonkai]

Use the device toolbar to know what it will look like on different devices. Use chrome.

[CMCDragonkai]

Even though the content can be improved, we're not going to gatekeep this. We're going to merge quickly and get you to iterate on the content going forward based on the above.